diff --git a/docs/learn/101-use.md b/docs/learn/101-use.md index 2ec10f95..1384ceec 100644 --- a/docs/learn/101-use.md +++ b/docs/learn/101-use.md @@ -22,7 +22,7 @@ First, you'll need to make sure [you have installed dagger on your local machine **Step 1**: Clone the example repository -```sh +```shell git clone https://github.com/dagger/examples.git ``` @@ -32,7 +32,7 @@ git clone https://github.com/dagger/examples.git Go to the app directory: -```sh +```shell cd ./examples/todoapp ``` @@ -46,7 +46,7 @@ dagger input list || curl -sfL https://releases.dagger.io/examples/key.txt >> ~/ **Step 4**: Deploy! -```sh +```shell dagger up ``` @@ -56,7 +56,7 @@ At the end of the deploy, you should see a list of outputs. There is one that is This repository is already configured to deploy the code in the directory `./todoapp`, so you can change some code (or replace the app code with another react app!) and re-run the following command to re-deploy when you want your changes to be live: -```sh +```shell dagger up ``` @@ -70,7 +70,7 @@ An Environment holds the entire deployment configuration. You can list existing environment from the `./todoapp` directory: -```sh +```shell dagger list ``` @@ -82,7 +82,7 @@ Each environment can have different kind of deployment code. For example, a `dev The plan is the deployment code, that includes the logic to deploy the local application to an AWS S3 bucket. From the `todoapp` directory, you can list the code of the plan: -```sh +```shell ls -l .dagger/env/s3/plan/ ``` @@ -92,7 +92,7 @@ Any code change to the plan will be applied during the next `dagger up`. The plan can define one or several `inputs` in order to take some information from the user. Here is how to list the current inputs: -```sh +```shell dagger input list ``` @@ -102,7 +102,7 @@ The inputs are persisted inside the `.dagger` directory and pushed to your git r The plan defines one or several `outputs`. They can show useful information at the end of the deployment. That's how we read the deploy `url` at the end of the deployment. Here is the command to list all inputs: -```sh +```shell dagger output list ``` diff --git a/docs/learn/102-dev.md b/docs/learn/102-dev.md index 6924c279..fecb756d 100644 --- a/docs/learn/102-dev.md +++ b/docs/learn/102-dev.md @@ -77,13 +77,13 @@ If you are new to Cue, we recommend keeping the following resources in browser t You will need a local copy of the [Dagger examples repository](https://github.com/dagger/examples). -```bash +```shell git clone https://github.com/dagger/examples ``` Make sure that all commands are run from the `todoapp` directory: -```bash +```shell cd examples/todoapp ``` @@ -95,7 +95,7 @@ Otherwise, don't worry: a Cue module is simply a directory with one or more Cue In this guide we will use the same directory as the root of the Dagger workspace and the root of the Cue module; but you can create your Cue module anywhere inside the Dagger workspace. -```bash +```shell cue mod init ``` @@ -114,7 +114,7 @@ But you can call your packages anything you want. Let's layout the structure of our package by creating all the files in advance: -```bash +```shell touch multibucket-source.cue multibucket-yarn.cue multibucket-netlify.cue ``` @@ -129,7 +129,7 @@ In Dagger terms, this component has 2 important properties: Let's write the corresponding Cue code to `multibucket-source.cue`: -```cue +```cue title="~/examples/todoapp/multibucket-source.cue" package multibucket import ( @@ -148,7 +148,7 @@ The second component of our plan is the Yarn package built from the source code. Let's write it to `multibucket-yarn.cue`: -```cue +```cue title="~/examples/todoapp/multibucket-yarn.cue" package multibucket import ( @@ -179,7 +179,7 @@ The third component of our plan is the Netlify site to which the app will be dep Let's write it to `multibucket-netlify.cue`: -```cue +```cue title="~/examples/todoapp/multibucket-netlify.cue" package multibucket import ( @@ -205,7 +205,7 @@ This is very similar to the previous component: But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`? Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](https://github.com/dagger/dagger/tree/main/stdlib). -```bash +```shell dagger doc dagger.io/netlify dagger doc dagger.io/js/yarn ``` @@ -218,7 +218,7 @@ You can also browse the [Dagger Universe](/reference/universe) reference in the Now that your Cue package is ready, let's create an environment to run it, -```bash +```shell dagger new 'multibucket' ``` @@ -226,7 +226,7 @@ dagger new 'multibucket' Now let's configure the new environment to use our package as its plan: -```bash +```shell cp multibucket-*.cue .dagger/env/multibucket/plan/ ``` diff --git a/docs/learn/107-kubernetes.md b/docs/learn/107-kubernetes.md index 60bdfbd7..2af4aa7b 100644 --- a/docs/learn/107-kubernetes.md +++ b/docs/learn/107-kubernetes.md @@ -46,7 +46,7 @@ docker run -d -p 5000:5000 --name registry registry:2 3\. Create a cluster with the local registry enabled in containerd -```bash +```shell cat <S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HostingWebsiteOnS3Setup.html) provisioning. Thanksfully, the AWS documentation contains a working [Cloudformation template](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/quickref-s3.html#scenario-s3-bucket-website) that fits 95% of our needs. -1. Tweaking the template: removing some of the ouputs +1.Tweaking the template: removing some of the ouputs The [template](https://docs.aws.amazon.com/fr_fr/AWSCloudFormation/latest/UserGuide/quickref-s3.html#scenario-s3-bucket-website) has far more outputs than necessary, as we just want to retrieve the bucket name: @@ -184,11 +182,11 @@ import TabItem from "@theme/TabItem"; -2. Some _"Pro tips"_ +2.Some _"Pro tips"_ Double-checks at the template level can be done with manual uploads on Cloudformation's web interface or by executing the below command locally: -```bash +```shell aws cloudformation validate-template --template-body file://template.json ``` @@ -198,7 +196,7 @@ aws cloudformation validate-template --template-body file://template.json Once you'll get used to Cue, you might directly write Cloudformation templates in this language. As most of the current examples are either written in JSON or in YAML, let's see how to lazily convert them in Cue (optional but recommended). -###### 1. Modify main.cue +#### 1. Modify main.cue We will temporarly modify `main.cue` to process the conversion @@ -212,8 +210,7 @@ We will temporarly modify `main.cue` to process the conversion }> -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import "encoding/json" @@ -226,12 +223,11 @@ data: #""" -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "encoding/json" + "encoding/json" ) point: json.Unmarshal(data) @@ -288,7 +284,7 @@ data: #""" "Value": { "Fn::GetAtt": [ "S3Bucket", - "Arn" + "Arn" ] }, "Description": "Name S3 Bucket" @@ -301,8 +297,7 @@ data: #""" -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import "encoding/yaml" @@ -315,7 +310,7 @@ data: """ -###### 2. Retrieve the Unmarshalled JSON +#### 2. Retrieve the Unmarshalled JSON Then, still in the same folder, query the `point` value to retrieve the Unmarshalled result of `data`: @@ -328,8 +323,7 @@ Then, still in the same folder, query the `point` value to retrieve the Unmarsha }> -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger query point # Output: # { @@ -396,8 +390,7 @@ dagger query point -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger query point # Output: # { @@ -408,7 +401,7 @@ dagger query point -###### 3. Store the output +#### 3. Store the output This Cue version of the JSON template is going to be integrated inside our provisioning plan. Save the output for the next steps of the guide. @@ -418,8 +411,7 @@ With the Cloudformation template now finished, tested and converted in Cue. We c Before continuing, don't forget to reset your `main.cue` plan to it's _Setup_ form: -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main ``` @@ -438,7 +430,7 @@ As our plan relies on [Cloudformation's relay](https://dagger.io/aws/clou | _timeout_ | `*10 \| \>=0 & int` | Timeout for waiting for the stack to be created/updated (in minutes) | | _neverUpdate_ | `*false \| bool` | Never update the stack if already exists | -1. General insights +1.General insights As seen before in the documentation, values starting with `*` are default values. However, as a plan developer, we may face the need to add default values to inputs from relays that don't have one : Cue gives you this flexibility (cf. `config` value detailed below). @@ -450,7 +442,7 @@ As seen before in the documentation, values starting with `*` are default values > - _source_ > - _stackName_ -2. The config value +2.The config value The config values are all part of the `aws` relay. Regarding this package, as you can see above, none of the 3 required inputs contain default options. @@ -466,44 +458,41 @@ For the sake of the exercise, let's say that our company's policy is to mainly d }> -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main ``` -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "dagger.io/aws" + "dagger.io/aws" ) // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) } ``` -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config + "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config ) // AWS account: credentials and region awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named `awsConfig` // awsConfig will be a directly requestable key : `dagger query awsConfig` // awsConfig sets the region to either an input, or a default string: "us-east-2" - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) // As we declare an aws.#Config, Dagger/Cue will automatically know that some others values inside this definition // are inputs, especially secrets (AccessKey, secretKey). Due to the confidential nature of secrets, we won't declare default values to them } @@ -512,7 +501,7 @@ awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named -_Pro tips: In order to check wether it worked or not, these two commands might help_ +Pro tips: In order to check wether it worked or not, these two commands might help -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger input list # List required input in our personal plan # Output: # Input Value Set by user Description @@ -537,8 +525,7 @@ dagger input list # List required input in our personal plan -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger query # Query values / inspect default values (Very useful in case of conflict) # Output: # { @@ -551,8 +538,7 @@ dagger query # Query values / inspect default values (Very useful in case of con -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger up # Try to run the plan. As expected, we encounter a failure # Output: # 9:07PM ERR system | required input is missing input=awsConfig.accessKey @@ -567,7 +553,7 @@ Inside the `firstCommand` tab, we see that the `awsConfig.region` key has a defa Furthemore, in the `Failed execution` tab, the execution of the `dagger up` command fails because of the unspecified secret inputs. -3. Integrating Cloudformation relay +3.Integrating Cloudformation relay Now that we have the `config` definition properly configured, we can now import the Cloudformation one, and properly fill it : @@ -582,42 +568,40 @@ Now that we have the `config` definition properly configured, we can now import }> -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "dagger.io/aws" + "dagger.io/aws" ) // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) } ``` -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "dagger.io/aws" + "dagger.io/aws" "dagger.io/random" "dagger.io/aws/cloudformation" ) // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) } // Create a random suffix suffix: random.#String & { - seed: "" + seed: "" } // Request the cloudformation stackname as an input, or generated a default one with a random suffix to keep uniqueness @@ -625,10 +609,10 @@ cfnStackName: *"stack-\(suffix.out)" | string @dagger(input) // Has to be uniqu // AWS Cloudformation stdlib cfnStack: cloudformation.#Stack & { - config: awsConfig - stackName: cfnStackName - onFailure: "DO_NOTHING" - source: json.Marshal(#cfnTemplate) + config: awsConfig + stackName: cfnStackName + onFailure: "DO_NOTHING" + source: json.Marshal(#cfnTemplate) } #cfnTemplate: { @@ -639,12 +623,11 @@ cfnStack: cloudformation.#Stack & { -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config + "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config "dagger.io/random" // <-- Import Random relay to instanciate random.#String "dagger.io/aws/cloudformation" // <-- Import Cloudformation relay to instanciate aws.#Cloudformation ) @@ -653,7 +636,7 @@ import ( awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named `awsConfig` // awsConfig will be a directly requestable key : `dagger query awsConfig` // awsConfig sets the region to either an input, or a default string: "us-east-2" - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) // As we declare an aws.#Config, Dagger/Cue will automatically know that some others values inside this definition // are inputs, especially secrets (AccessKey, secretKey). Due to the confidential nature of secrets, we won't declare default values to them } @@ -662,21 +645,21 @@ awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named cfnStack: cloudformation.#Stack & { // Assign an aws.#Cloudformation definition to a field named `cfnStack` // This definition is the stdlib package to use in order to deploy AWS instances programmatically - config: awsConfig // As seen in the relay doc, 3 config fields have to be provided : `config.region`, `config.accessKey` and `config.secretKey` + config: awsConfig // As seen in the relay doc, 3 config fields have to be provided : `config.region`, `config.accessKey` and `config.secretKey` // As their names contain a `.`, it means that the value `config` expects 3 fields `region`, `accessKey` and `secretKey`, included in a `aws.#Config` parent definition stackName: cfnStackName // We assign to the `stackName` the `cfnStackName` declared below. // `stackName` expects a string type. However, as a plan developer, we wanted to give the developer a choice : either a default random value, or an input // The default random value *"stack-\(suffix.out)" uses the random.#String relay to generate a random value. We append it's result inside `"\(append_happening_here)"` - onFailure: "DO_NOTHING" // As cited in the Cloudformation relay, the `onFailure` key defines Cloudformation's stack behavior on failure + onFailure: "DO_NOTHING" // As cited in the Cloudformation relay, the `onFailure` key defines Cloudformation's stack behavior on failure - source: json.Marshal(#cfnTemplate) // source expects a JSON artifact. Here we remarshall the template decaled in Cue + source: json.Marshal(#cfnTemplate) // source expects a JSON artifact. Here we remarshall the template decaled in Cue } // Create a random suffix (cf. random relay) suffix: random.#String & { // Assign a #random definition to a field named `suffix` - seed: "" // Set seed to empty string, to generate a new random string every time + seed: "" // Set seed to empty string, to generate a new random string every time } // Output -> suffix.out is a random string // Request the cloudformation stackname as an input, or generated a default one with a random suffix to keep uniqueness @@ -690,26 +673,25 @@ cfnStackName: *"stack-\(suffix.out)" | string @dagger(input) // Has to be uniqu -```cue --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue -- +```cue title=".dagger/env/s3-provisioning/plan/main.cue" package main import ( - "encoding/json" + "encoding/json" - "dagger.io/aws" + "dagger.io/aws" "dagger.io/random" - "dagger.io/aws/cloudformation" + "dagger.io/aws/cloudformation" ) // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: *"us-east-2" | string @dagger(input) } // Create a random suffix suffix: random.#String & { - seed: "" + seed: "" } // Query the Cloudformation stackname, or create one with a random suffix to keep unicity @@ -717,10 +699,10 @@ cfnStackName: *"stack-\(suffix.out)" | string @dagger(input) // AWS Cloudformation stdlib cfnStack: cloudformation.#Stack & { - config: awsConfig - stackName: cfnStackName - onFailure: "DO_NOTHING" - source: json.Marshal(#cfnTemplate) + config: awsConfig + stackName: cfnStackName + onFailure: "DO_NOTHING" + source: json.Marshal(#cfnTemplate) } #cfnTemplate: { @@ -800,14 +782,11 @@ Finally ! We now have a working template ready to be used to provision S3 infras }> -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger input secret awsConfig.accessKey yourAccessKey --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger input secret awsConfig.secretKey yourSecretKey --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger input list # Input Value Set by user Description # awsConfig.region *"us-east-2" | string false AWS region @@ -819,7 +798,6 @@ dagger input list # All the other inputs have default values, we're good to go ! --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger up # Output: #2:22PM INF suffix.out | computing @@ -833,7 +811,6 @@ dagger up #2:22PM INF cfnStack.outputs | #15 2.948 } #2:22PM INF cfnStack.outputs | completed duration=35s --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger output list # Output Value Description # suffix.out "emktqcfwksng" generated random string @@ -843,14 +820,11 @@ dagger output list -```bash --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- +```shell dagger input secret awsConfig.accessKey yourAccessKey --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger input secret awsConfig.secretKey yourSecretKey --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger input list # Input Value Set by user Description # awsConfig.region *"us-east-2" | string false AWS region @@ -874,7 +848,6 @@ dagger up -l debug # suffix.out "abnyiemsoqbm" generated random string # cfnStack.outputs.Name "arn:aws:s3:::stack-abnyiemsoqbm-s3bucket-9eiowjs1jab4" - --- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ -- dagger output list # Output Value Description # suffix.out "abnyiemsoqbm" generated random string