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`
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:
```cue
dagger.#Plan & {
inputs: {
directories: app: path: "./"
client: {
filesystem: {
// ...
}
env: {
// ...
}
}
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
dagger up dev.cue
[✔] inputs.directories.app 0.1s
[✔] actions.build 0.6s
[✔] actions.test 0.6s
[✔] client.filesystem.".".read 0.0s
[✔] actions.deps 1.1s
[✔] actions.test.script 0.0s
[✔] 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.
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.
In the example above, the `build` action is an instance of the yarn package build definition.
This is written as `build: yarn.#Build`
In the example above, the `deps` action is an instance of the docker package build definition.
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
actions: {
build: yarn.#Build & {
deps: docker.#Build & {
// ...
}
```
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:
```cue
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
import (
"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.
This will enable us to configure plans just-in-time, which is something that typically happanes on every CI run.
:::tip
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.
:::