From f8d8a68a5e5a80985c8745db2a46be660e076094 Mon Sep 17 00:00:00 2001 From: Guillaume de Rouville Date: Wed, 16 Jun 2021 18:57:19 +0200 Subject: [PATCH] docs: Modify 107 and 108 packages to follow 102 guidelines => work in subdir Signed-off-by: Guillaume de Rouville --- docs/learn/107-kubernetes.md | 106 +++++++++++++++++++------ docs/learn/108-cloudformation.md | 132 +++++++++++++++++++------------ 2 files changed, 164 insertions(+), 74 deletions(-) diff --git a/docs/learn/107-kubernetes.md b/docs/learn/107-kubernetes.md index 2af4aa7b..72391095 100644 --- a/docs/learn/107-kubernetes.md +++ b/docs/learn/107-kubernetes.md @@ -23,7 +23,7 @@ values={[ {label: 'EKS', value: 'eks'}, ]}> - + [Kind](https://kind.sigs.k8s.io/docs/user/quick-start) is a tool for running local Kubernetes clusters using Docker. @@ -80,19 +80,43 @@ This tutorial can be run against a [AWS EKS](https://aws.amazon.com/eks/) cluste ## Initialize a Dagger Workspace and Environment +### (optional) Setup example app + +You will need the local copy of the [Dagger examples repository](https://github.com/dagger/examples) used in previous guides + ```shell -mkdir dagger-kubernetes && cd dagger-kubernetes -dagger init -dagger new default +git clone https://github.com/dagger/examples +``` + +Make sure that all commands are run from the todoapp directory: + +```shell +cd examples/todoapp +``` + +### (optional) Initialize a Cue module + +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. + +```shell +cue mod init +``` + +### Organize your package + +Let's create a new directory for our Cue package: + +```shell +mkdir kube ``` ## Create a basic plan -Create a file named `.dagger/env/default/plan/manifest.cue` and add the +Create a file named `manifest.cue` and add the following configuration to it. -```cue title=".dagger/env/default/plan/manifest.cue" -package main +```cue title="todoapp/kube/manifest.cue" +package kube // inlined kubernetes manifest as a string manifest: """ @@ -123,7 +147,7 @@ manifest: """ This will define a `manifest` variable containing the inlined Kubernetes YAML used to create a _nginx_ deployment. -Next, create `.dagger/env/default/plan/main.cue`. +Next, create `source.cue`. -```cue title=".dagger/env/default/plan/main.cue" -package main +```cue title="todoapp/kube/source.cue" +package kube import ( "dagger.io/dagger" @@ -163,8 +187,8 @@ deploy: kubernetes.#Resources & { -```cue title=".dagger/env/default/plan/main.cue" -package main +```cue title="todoapp/kube/source.cue" +package kube import ( "dagger.io/kubernetes" @@ -191,8 +215,8 @@ deploy: kubernetes.#Resources & { -```cue title=".dagger/env/default/plan/main.cue" -package main +```cue title="todoapp/kube/source.cue" +package kube import ( "dagger.io/kubernetes" @@ -225,6 +249,26 @@ This defines: - `deploy`: Deployment step using the package `dagger.io/kubernetes`. It takes the `manifest` defined earlier and deploys it to the Kubernetes cluster specified in `kubeconfig`. +### Setup the environment + +#### Create a new environment + +Now that your Cue package is ready, let's create an environment to run it: + +```shell +dagger new 'kube' +``` + +#### Load the plan into the environment + +Now let's configure the new environment to use our package as its plan: + +```shell +cp kube/*.cue .dagger/env/kube/plan/ +``` + +Note: you need to copy the files from your package into the environment, as shown above. If you make more changes to your package, you will need to copy the new version, or it will not be used. In the future, we will add the ability to reference your Cue package directory, making this manual copy unnecessary. + ### Configure the environment Before we can bring up the deployment, we need to provide the `kubeconfig` input @@ -379,8 +423,8 @@ For a more advanced example, see the First, let's replace `manifest.cue` with the following configuration. This is a straightforward one-to-one conversion from YAML to CUE, only the syntax has changed. -```cue title=".dagger/env/default/plan/manifest.cue" -package main +```cue title="todoapp/kube/manifest.cue" +package kube import ( "encoding/yaml" @@ -415,6 +459,12 @@ manifest: yaml.Marshal(nginx) We're using the built-in `yaml.Marshal` function to convert CUE back to YAML so Kubernetes still receives the same manifest. +You need to copy the changes to the plan in order for Dagger to reference them + +```shell +cp kube/*.cue .dagger/env/kube/plan/ +``` + You can inspect the configuration using `dagger query` to verify it produces the same manifest: @@ -428,10 +478,10 @@ kind: Deployment Now that the manifest is defined in CUE, we can take advantage of the language to remove a lot of boilerplate and repetition. -Let's define a re-usable `#Deployment` definition in `.dagger/env/default/plan/deployment.cue"`: +Let's define a re-usable `#Deployment` definition in `todoapp/kube/deployment.cue"`: -```cue title=".dagger/env/default/plan/deployment.cue" -package main +```cue title="todoapp/kube/deployment.cue" +package kube // Deployment template containing all the common boilerplate shared by // deployments of this application. @@ -478,7 +528,7 @@ package main `manifest.cue` can be rewritten as follows: -```cue title=".dagger/env/default/plan/manifest.cue" +```cue title="todoapp/kube/manifest.cue" import ( "encoding/yaml" ) @@ -491,6 +541,12 @@ nginx: #Deployment & { manifest: yaml.Marshal(nginx.manifest) ``` +Update the plan + +```shell +cp kube/*.cue .dagger/env/kube/plan/ +``` + Let's make sure it yields the same result: ```shell @@ -524,8 +580,8 @@ The following configuration will: - Use `dagger.io/docker` to build and push the image - Use the registry image reference (`push.ref`) as the image for the deployment. -```cue title=".dagger/env/default/plan/manifest.cue" -package main +```cue title="todoapp/kube/manifest.cue" +package kube import ( "encoding/yaml" @@ -565,6 +621,12 @@ app: #Deployment & { manifest: yaml.Marshal(app.manifest) ``` +Update the plan + +```shell +cp kube/*.cue .dagger/env/kube/plan/ +``` + ### Connect the Inputs Next, we'll provide the two new inputs, `repository` and `registry`. diff --git a/docs/learn/108-cloudformation.md b/docs/learn/108-cloudformation.md index 0cead728..47451383 100644 --- a/docs/learn/108-cloudformation.md +++ b/docs/learn/108-cloudformation.md @@ -20,28 +20,46 @@ The provisioning strategy detailed below follows S3 best practices. In order to When developing a plan based on relays, the first thing to consider is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](https://dagger.io/aws/cloudformation) is the Cloudformation one. -### Setup +## Initialize a Dagger Workspace and Environment -1.Initialize a new folder and a new workspace +### (optional) Setup example app + +You will need the local copy of the [Dagger examples repository](https://github.com/dagger/examples) used in previous guides ```shell -mkdir infra-provisioning -cd ./infra-provisioning -dagger init +git clone https://github.com/dagger/examples ``` -2.Create a new environment and create a `main.cue` file +Make sure that all commands are run from the todoapp directory: ```shell -dagger new s3-provisioning -cd ./.dagger/env/s3-provisioning/plan/ #Personal preference to directly work inside the plan -touch main.cue +cd examples/todoapp ``` -3.Create corresponding `main` package +### (optional) Initialize a Cue module -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +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. + +```shell +cue mod init +``` + +### Organize your package + +Let's create a new directory for our Cue package: + +```shell +mkdir cloudformation +``` + +### Setup the environment + +#### Create a new environment + +Now that your Cue package is ready, let's create an environment to run it: + +```shell +dagger new 'cloudformation' ``` ## Cloudformation @@ -196,9 +214,9 @@ 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. Create convert.cue -We will temporarly modify `main.cue` to process the conversion +We will create a `convert.cue` to process the conversion -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/convert.cue" +package cloudformation import "encoding/json" point: json.Unmarshal(data) @@ -223,12 +241,9 @@ data: #""" -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main - -import ( - "encoding/json" -) +```cue title="todoapp/cloudformation/convert.cue" +package cloudformation +import "encoding/json" point: json.Unmarshal(data) data: #""" @@ -297,8 +312,8 @@ data: #""" -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/convert.cue" +package cloudformation import "encoding/yaml" point: yaml.Unmarshal(data) @@ -310,6 +325,12 @@ data: """ +You need to copy the changes to the plan in order for Dagger to reference them + +```shell +cp cloudformation/*.cue .dagger/env/cloudformation/plan/ +``` + #### 2. Retrieve the Unmarshalled JSON Then, still in the same folder, query the `point` value to retrieve the Unmarshalled result of `data`: @@ -409,10 +430,11 @@ This Cue version of the JSON template is going to be integrated inside our provi With the Cloudformation template now finished, tested and converted in Cue. We can now enter the last part of our guide: piping everything together inside our personal plan. -Before continuing, don't forget to reset your `main.cue` plan to it's _Setup_ form: +Before continuing, don't forget to delete your `convert.cue` plan: -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```shell +rm todoapp/cloudformation/convert.cue +rm .dagger/env/cloudformation/plan/convert.cue ``` ### Cloudformation relay @@ -432,7 +454,7 @@ As our plan relies on [Cloudformation's relay](https://dagger.io/aws/clou 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). +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. > WARNING: All inputs without a default option have to be filled for a proper execution of the relay. In our case: > @@ -446,7 +468,7 @@ As seen before in the documentation, values starting with `*` are default values 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. -For the sake of the exercise, let's say that our company's policy is to mainly deploy on the `us-east-2` region. Having this value set as a default option could be a smart and efficient decision for our dev teams. Let's see how to implement it: +Let's implement the first step : use the `aws.#Config` relay and request the user it's first input, the region to deploy in. -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation ``` -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "dagger.io/aws" @@ -474,15 +496,15 @@ import ( // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: string @dagger(input) } ``` -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config @@ -492,7 +514,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: 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 } @@ -501,6 +523,12 @@ awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named +Update the plan + +```shell +cp cloudformation/*.cue .dagger/env/cloudformation/plan/ +``` + Pro tips: In order to check wether it worked or not, these two commands might help -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "dagger.io/aws" @@ -577,15 +605,15 @@ import ( // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: string @dagger(input) } ``` -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "dagger.io/aws" @@ -595,7 +623,7 @@ import ( // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: string @dagger(input) } @@ -623,8 +651,8 @@ cfnStack: cloudformation.#Stack & { -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "dagger.io/aws" // <-- Import AWS relay to instanciate aws.#Config @@ -636,7 +664,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: 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 } @@ -673,8 +701,8 @@ cfnStackName: *"stack-\(suffix.out)" | string @dagger(input) // Has to be uniqu -```cue title=".dagger/env/s3-provisioning/plan/main.cue" -package main +```cue title="todoapp/cloudformation/source.cue" +package cloudformation import ( "encoding/json" @@ -686,7 +714,7 @@ import ( // AWS account: credentials and region awsConfig: aws.#Config & { - region: *"us-east-2" | string @dagger(input) + region: string @dagger(input) } // Create a random suffix @@ -789,7 +817,7 @@ dagger input secret awsConfig.secretKey yourSecretKey dagger input list # Input Value Set by user Description -# awsConfig.region *"us-east-2" | string false AWS region +# awsConfig.region string false AWS region # awsConfig.accessKey dagger.#Secret true AWS access key <-- Specified # awsConfig.secretKey dagger.#Secret true AWS secret key <-- Specified # suffix.length *12 | number false length of the string @@ -827,7 +855,7 @@ dagger input secret awsConfig.secretKey yourSecretKey dagger input list # Input Value Set by user Description -# awsConfig.region *"us-east-2" | string false AWS region +# awsConfig.region string false AWS region # awsConfig.accessKey dagger.#Secret true AWS access key <-- Specified # awsConfig.secretKey dagger.#Secret true AWS secret key <-- Specified # suffix.length *12 | number false length of the string