kjuulh/dagger
Archived
1
0
Fork 0
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

Merge pull request #1735 from gerhard/europa-docs-plan-client-api

Browse Source 
Europa docs plan updates after Client API & dagger do
This commit is contained in:
Gerhard Lazu 2022-03-09 18:35:23 +00:00 committed by GitHub
commit a35419b45f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/core-concepts/1202-plan.md
View File

@ -7,62 +7,80 @@ displayed_sidebar: europa
A CI/CD pipeline declared in Dagger starts with a plan, specifically `dagger.#Plan` A CI/CD pipeline declared in Dagger starts with a plan, specifically `dagger.#Plan`
This plan is the entrypoint for everything that runs within a pipeline. This plan is the entrypoint for everything that runs within a pipeline. The simplest plan will usually:
- interact with the client filesystem to read (e.g. source code) or write files (e.g. build output)
- read environment variables
- declare a few actions, e.g. deps, test & build
The simplest plan will have at least one input - the source code - and a few actions, usually build, test & deploy.
This is our **Getting Started** example app plan structure: This is our **Getting Started** example app plan structure:
```cue ```cue
dagger.#Plan & { dagger.#Plan & {
inputs: { client: {
directories: app: path: "./" filesystem: {
// ... // ...
} }
env: {
// ...
}
}
actions: { actions: {
build: yarn.#Build & { deps: docker.#Build & {
// ... // ...
} }
test: yarn.#Run & { test: bash.#Run & {
// ... // ...
} }
build: {
run: bash.#Run & {
// ... // ...
} }
contents: dagger.#Subdir & {
// ...
}
}
}
} }
``` ```
When the above plan gets executed via `dagger up`, it produces the following output: When the above plan gets executed via `dagger do build`, it produces the following output:
```shell ```shell
dagger up dev.cue [✔] client.filesystem.".".read 0.0s
[✔] inputs.directories.app 0.1s [✔] actions.deps 1.1s
[✔] actions.build 0.6s [✔] actions.test.script 0.0s
[✔] actions.test 0.6s [✔] actions.test 0.0s
[✔] actions.build.run.script 0.0s
[✔] actions.build.run 0.0s
[✔] actions.build.contents 0.0s
[✔] client.filesystem.build.write 0.1s
``` ```
Since these actions have run before, they are cached and take less than 1 second to complete. Since these actions have run before, they are cached and take less than 1 second to complete.
While the names used for the actions above - `build`, `test` - are short & descriptive, While the names used for the actions above - `deps`, `test` & `build` - are short & descriptive,
any other names would have worked. Put differently, action naming does not affect plan execution. any other names would have worked. Put differently, action naming does not affect plan execution.
In the example above, the `build` action is an instance of the yarn package build definition. In the example above, the `deps` action is an instance of the docker package build definition.
This is written as `build: yarn.#Build`
Default definition configuration can be modified via curly brackets, e.g. This is written as `deps: docker.#Build`
Default definition configuration - `docker.#Build` in this case - can be modified via curly brackets, e.g.
```cue ```cue
actions: { deps: docker.#Build & {
build: yarn.#Build & {
// ... // ...
} }
``` ```
We can build complex pipelines efficiently by referencing any definition, from any package in our actions. We can build complex pipelines efficiently by referencing any definition, from any package in our actions.
This is one of the fundamental concepts that makes Dagger a powerful devkit for CI/CD. This is one of the fundamental concepts that makes Dagger a powerful language for CI/CD.
Before we can use a package in a plan, we need to declare it at the top of the pipeline configuration, like this: Before we can use a package in a plan, we need to declare it at the top of the pipeline configuration, like this:
```cue ```cue
import ( import (
"universe.dagger.io/yarn" "universe.dagger.io/docker"
) )
``` ```
@ -71,9 +89,11 @@ Since we are using the plan definition from the dagger package - `dagger.#Plan`
```cue ```cue
import ( import (
"dagger.io/dagger" "dagger.io/dagger"
"universe.dagger.io/yarn" "universe.dagger.io/docker"
) )
``` ```
Now that we understand the basics of a Dagger plan, we are ready to learn more about inputs and how to configure them. :::tip
This will enable us to configure plans just-in-time, which is something that typically happanes on every CI run. Now that we understand the basics of a Dagger plan, we are ready to learn more about how to interact with the client environment.
This will enable us to configure plans just-in-time, save build artefacts, and perform other interactions with the environment within which Dagger runs.
:::