From 90d91bfb3590655d6c69b60ea629dd34cf62ebe2 Mon Sep 17 00:00:00 2001 From: Easton Crupper <65553218+ecrupper@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:21:48 -0500 Subject: [PATCH] chore(pipeline/exec): expanded docs for v0.22 exec pipeline improvements (#382) * chore(pipeline/exec): expanded docs for v0.22 exec pipeline improvements * add more examples --- content/reference/cli/pipeline/exec.md | 173 +++++++++++++++++++++++-- 1 file changed, 164 insertions(+), 9 deletions(-) diff --git a/content/reference/cli/pipeline/exec.md b/content/reference/cli/pipeline/exec.md index 26773a006..3ba54fe0e 100644 --- a/content/reference/cli/pipeline/exec.md +++ b/content/reference/cli/pipeline/exec.md @@ -19,28 +19,66 @@ For more information, you can run `vela exec pipeline --help`. The following parameters are used to configure the command: +### Ruleset Parameters + +| Name | Description | Environment Variables | +| ---------------- | --------------------------------------------- | -------------------------------------- | +| `branch` | the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH` | +| `comment` | the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT` | +| `event` | the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT` | +| `tag` | the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG` | +| `target` | the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET` | +| `file-changeset` | the build file changeset for the pipeline | `VELA_FILE_CHANGESET`, `FILE_CHANGESET`| + +### Repo Settings Parameters + +| Name | Description | Environment Variables | +| --------------- | --------------------------------------------- | -------------------------------------- | +| `org` | provide the organization for the pipeline | `VELA_ORG`, `PIPELINE_ORG` | +| `repo` | provide the repository for the pipeline | `VELA_REPO`, `PIPELINE_REPO` | +| `pipeline-type` | provide the repository pipeline type | `VELA_PIPELINE_TYPE`, `PIPELINE_TYPE` | + +### Template Parameters + +| Name | Description | Environment Variables | +| ----------------------- | ------------------------------------------------ | ----------------------------------------------------- | +| `compiler.github.token` | PAT for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_TOKEN`, `COMPILER_GITHUB_TOKEN` | +| `compiler.github.url` | URL for accessing GitHub sourced templates | `VELA_COMPILER_GITHUB_URL`, `COMPILER_GITHUB_URL` | +| `template-file` | list of local templates in form of : | `VELA_TEMPLATE_FILE`, `PIPELINE_TEMPLATE_FILE` | +| `max-template-depth` | maximum depth for requesting nested templates | `VELA_MAX_TEMPLATE_DEPTH`, `MAX_TEMPLATE_DEPTH` | + +### Environment Parameters + +| Name | Description | Environment Variables | +| --------------- | ------------------------------------------------------------------------- | ------------------------------------- | +| `env-file` | Bool value for whether or not to source from an env file (default `.env`) | `VELA_ENV_FILE`, `ENV_FILE` | +| `env-file-path` | Path to override default `.env` sourcing of environment | `VELA_ENV_FILE_PATH`, `ENV_FILE_PATH` | +| `local-env` | Bool value for whether or not to onboard your local environment | `ONBOARD_LOCAL_ENV`, `LOCAL_ENV` | +| `env-vars` | list of environment variables to include in form of = | `VELA_ENV_VARS` | + +### Other Parameters + | Name | Description | Environment Variables | | -------- | --------------------------------------------- | --------------------------------- | -| `branch` | the build branch for the pipeline | `VELA_BRANCH`, `PIPELINE_BRANCH` | -| `comment`| the build comment for the pipeline | `VELA_COMMENT`, `PIPELINE_COMMENT`| -| `event` | the build event for the pipeline | `VELA_EVENT`, `PIPELINE_EVENT` | -| `tag` | the build tag for the pipeline | `VELA_TAG`, `PIPELINE_TAG` | -| `target` | the build target for the pipeline | `VELA_TARGET`, `PIPELINE_TARGET` | | `output` | format the output in json, spew or yaml | `VELA_OUTPUT`, `PIPELINE_OUTPUT` | | `file` | name of the file for the pipeline | `VELA_FILE`, `PIPELINE_FILE` | | `path` | path to the file for the pipeline | `VELA_PATH`, `PIPELINE_PATH` | | `local` | enables mounting local directory to pipeline | `VELA_LOCAL`, `PIPELINE_LOCAL` | | `volume` | provide list of local volumes to mount | `VELA_VOLUMES`, `PIPELINE_VOLUMES`| -| `org` | provide the organization for the pipeline | `VELA_ORG`, `PIPELINE_ORG` | -| `repo` | provide the repository for the pipeline | `VELA_REPO`, `PIPELINE_REPO` | + +## Environment + +Unless the `local-env` flag is supplied, the `vela exec pipeline` command will execute without any set environment. Instead, users are encouraged to supply their own environment variables in the form of an env file (e.g. `--env-file` OR `--env-file-path custom.env`). + +Many plugins, Starlark/Go templates, and other build resources depend on Vela-injected environment variables, such as `VELA_BUILD_COMMIT`. These variables will have to be supplied by the user, as there is no way for the compiler to determine these values locally. ## Secrets The Vela Exec command does not have access to any secret you have stored in Vela or any other attached secret store. -You can set environment variables for the command by putting them before the command, ie `MY_SECRET=foo vela exec pipeline`. +Environment variables can be set for the command by using the `env-vars` flag, ie `vela exec pipeline --env-vars MY_SECRET=foo`. They can also be set with the `env-file` or `local-env` flags. -So if our pipeline is using the [kaniko plugin](https://go-vela.github.io/docs/plugins/registry/pipeline/kaniko/), it may require the secret `kaniko_password`, which we can provide with `KANIKO_PASSWORD=mypass vela exec pipeline` +For example, if a pipeline is using the [kaniko plugin](https://go-vela.github.io/docs/plugins/registry/pipeline/kaniko/), it may require the secret `kaniko_password`, which can be provided with `vela exec pipeline --env-vars KANIKO_PASSWORD=mypass`. ## Sample @@ -114,3 +152,120 @@ sha256:6dbb9cc54074106d46d4ccb330f2a40a682d49dda5f4844962b7dce9fe44aaec [step: hello Vela] $ echo "hello Vela!" [step: hello Vela] hello Vela! ``` + +## Complex Samples + +Below are several examples using the following Vela pipeline + template + +### .vela.yml +```yaml +version: "1" + +templates: + - name: tmpl + source: git.company.com/cloud/vela-templates/kaniko.yml@main + type: github + +steps: + - name: testing + image: alpine:latest + commands: + - echo hello + + - name: file path ruleset + image: alpine:latest + ruleset: + matcher: regexp + path: [ src/* ] + commands: + - echo ran + + - name: docker build + template: + name: tmpl + vars: + repo: docker.company.com/octocat/hello-world +``` + +### kaniko.yml Template +```yaml +version: "1" + +metadata: + template: true + +environment: + REPO: {{ .repo }} + +secrets: + - name: docker_username + key: octocat/docker_username + engine: native + type: org + + - name: docker_password + key: octocat/docker_password + engine: native + type: org + +steps: + - name: Build and Publish + image: target/vela-kaniko:latest + secrets: [ docker_username, docker_password ] + parameters: + registry: docker.company.com + repo: ${REPO} +``` + +### Remote Template + Local Environment Onboarding + +```sh +$ DOCKER_USERNAME=octocat DOCKER_PASSWORD=abc123 VELA_BUILD_COMMIT=1a2b3c vela exec pipeline --ct --cgu https://git.company.com --local-env +``` + +Note: `--local-env` onboards the entire bash environment. To load specific environment variables, use `--env-vars`: + +```sh +$ vela exec pipeline --ct --cgu https://git.company.com --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c +``` + +### Template Override + +```sh +$ vela exec pipeline --template-file tmpl:path/to/template.yml --env-vars DOCKER_USERNAME=octocat,DOCKER_PASSWORD=abc123,VELA_BUILD_COMMIT=1a2b3c +``` + +### Environment File + +`.env` +``` +DOCKER_USERNAME=octocat +DOCKER_PASSWORD=abc123 +VELA_BUILD_COMMIT=1a2b3c +``` + +```sh +$ vela exec pipeline --ct --cgu https://git.company.com --env-file +``` + +`vela_exec.env` +``` +DOCKER_USERNAME=octocat +DOCKER_PASSWORD=abc123 +VELA_BUILD_COMMIT=1a2b3c +``` + +```sh +$ vela exec pipeline --ct --cgu https://git.company.com --env-file-path vela_exec.env +``` + +### Path Ruleset Inclusion + +In order to execute steps with rulesets, be sure to include all necessary flags that match the rules + +```sh +$ vela exec pipeline --ct --cgu https://git.company.com --env-file --file-changeset src/main.go +``` + +Other rules: `--branch`, `--event`, `--comment`, `--tag`, `--target` +