Merge pull request #659 from grouville/uniform_codeblocs
docs: uniform codeblocs => use shell language + add title
This commit is contained in:
Sam Alba
GitHub
commit
ea441d9d6a
@ -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
|
||||
```
|
||||
|
||||
|
||||
@ -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/
|
||||
```
|
||||
|
||||
|
||||
@ -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 <<EOF | kind create cluster --config=-
|
||||
kind: Cluster
|
||||
apiVersion: kind.x-k8s.io/v1alpha4
|
||||
|
||||
@ -22,27 +22,25 @@ When developing a plan based on relays, the first thing to consider is to read t
|
||||
|
||||
### Setup
|
||||
|
||||
1. Initialize a new folder and a new workspace
|
||||
1.Initialize a new folder and a new workspace
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mkdir infra-provisioning
|
||||
cd ./infra-provisioning
|
||||
dagger init
|
||||
```
|
||||
|
||||
2. Create a new environment
|
||||
2.Create a new environment and create a `main.cue` file
|
||||
|
||||
```bash
|
||||
```shell
|
||||
dagger new s3-provisioning
|
||||
cd ./.dagger/env/s3-provisioning/plan/ #Personal preference to directly work inside the plan
|
||||
touch main.cue
|
||||
```
|
||||
|
||||
3. Create `main.cue` file with its corresponding `main` package
|
||||
3.Create corresponding `main` package
|
||||
|
||||
```bash
|
||||
touch main.cue
|
||||
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
```
|
||||
|
||||
@ -54,7 +52,7 @@ Now that a plan has been set, let's implement the Cloudformation template and co
|
||||
|
||||
The idea here is to follow best practices in [<u>S3 buckets</u>](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HostingWebsiteOnS3Setup.html) provisioning. Thanksfully, the AWS documentation contains a working [<u>Cloudformation template</u>](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 [<u>template</u>](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";
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
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
|
||||
}>
|
||||
<TabItem value="sv">
|
||||
|
||||
```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,8 +223,7 @@ data: #"""
|
||||
</TabItem>
|
||||
<TabItem value="fv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -301,8 +297,7 @@ data: #"""
|
||||
</TabItem>
|
||||
<TabItem value="yv">
|
||||
|
||||
```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: """
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
###### 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
|
||||
}>
|
||||
<TabItem value="fo">
|
||||
|
||||
```bash
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ --
|
||||
```shell
|
||||
dagger query point
|
||||
# Output:
|
||||
# {
|
||||
@ -396,8 +390,7 @@ dagger query point
|
||||
</TabItem>
|
||||
<TabItem value="sc">
|
||||
|
||||
```bash
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/ --
|
||||
```shell
|
||||
dagger query point
|
||||
# Output:
|
||||
# {
|
||||
@ -408,7 +401,7 @@ dagger query point
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
###### 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 [<u>Cloudformation's relay</u>](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,16 +458,14 @@ For the sake of the exercise, let's say that our company's policy is to mainly d
|
||||
}>
|
||||
<TabItem value="bv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="av">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -491,8 +481,7 @@ awsConfig: aws.#Config & {
|
||||
</TabItem>
|
||||
<TabItem value="dv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -512,7 +501,7 @@ awsConfig: aws.#Config & { // Assign an aws.#Config definition to a field named
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
_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
|
||||
|
||||
<Tabs
|
||||
defaultValue="fc"
|
||||
@ -524,8 +513,7 @@ _Pro tips: In order to check wether it worked or not, these two commands might h
|
||||
}>
|
||||
<TabItem value="fc">
|
||||
|
||||
```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
|
||||
</TabItem>
|
||||
<TabItem value="sc">
|
||||
|
||||
```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
|
||||
</TabItem>
|
||||
<TabItem value="fe">
|
||||
|
||||
```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,8 +568,7 @@ Now that we have the `config` definition properly configured, we can now import
|
||||
}>
|
||||
<TabItem value="bv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -599,8 +584,7 @@ awsConfig: aws.#Config & {
|
||||
</TabItem>
|
||||
<TabItem value="av">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -639,8 +623,7 @@ cfnStack: cloudformation.#Stack & {
|
||||
</TabItem>
|
||||
<TabItem value="dv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -690,8 +673,7 @@ cfnStackName: *"stack-\(suffix.out)" | string @dagger(input) // Has to be uniqu
|
||||
</TabItem>
|
||||
<TabItem value="fv">
|
||||
|
||||
```cue
|
||||
-- ~/infra-provisioning/.dagger/env/s3-provisioning/plan/main.cue --
|
||||
```cue title=".dagger/env/s3-provisioning/plan/main.cue"
|
||||
package main
|
||||
|
||||
import (
|
||||
@ -800,14 +782,11 @@ Finally ! We now have a working template ready to be used to provision S3 infras
|
||||
}>
|
||||
<TabItem value="nd">
|
||||
|
||||
```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
|
||||
</TabItem>
|
||||
<TabItem value="dd">
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user