Custom Flows
You can create custom flows for a template, that allows you to run whatever you want (bash, python, gcloud, Ansible, CloudFormation, etc.), whenever you want in the deployment process (before or after Terraform init/plan/apply, and even destroy/error).
For specific custom flow per template:
Create a file named env0.yml under the template folder. env0 will use this file when is defined.
For sharing custom flow for all templates:
Create a file named env0.yml under the root folder. env0 will use this file when it is defined and the template folder doesn't define this file.
We support the suffixes env0.yml and env0.yaml in the same way.
Working Directory for env0.yml
env0 will run custom flow commands with a working directory based on where the file was taken.
Based on that you can reference your commands to other scripts/commands by using "./script.sh"
Below is an example of a custom flow which creates a more "dynamic" Terraform file, based on an environment variable value, and uses Python and Jinja before the Terraform Init (the full example of this template git repo (including the env0.yml file) is here):
version: 1
deploy:
steps:
terraformInit:
before:
- pip install --user j2cli
- 'echo Generating "stage.auto.tfvars" for "$STAGE"'
- j2 stage.auto.tfvars.j2 > stage.auto.tfvars
- 'echo -e "Generated \"stage.auto.tfvars\": \n$(cat stage.auto.tfvars)"'
- 'echo Generating "elb.tf" for "$STAGE"'
- j2 elb.tf.j2 > elb.tf
- 'echo -e "Generated \"elb.tf\": \n$(cat elb.tf)"'
You can include the following possible hooks in an env0.yml file.
Terraform
version:
type: number
deploy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
terraformInit:
before:
- type: string
after:
- type: string
terraformPlan:
before:
- type: string
after:
- type: string
terraformApply:
before:
- type: string
after:
- type: string
storeState:
before:
- type: string
after:
- type: string
terraformOutput:
before:
- type: string
after:
- type: string
destroy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
terraformInit:
before:
- type: string
after:
- type: string
terraformPlan:
before:
- type: string
after:
- type: string
terraformDestroy:
before:
- type: string
after:
- type: string
Pulumi
version:
type: number
deploy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
pulumiLogin:
before:
- type: string
after:
- type: string
pulumiPreview:
before:
- type: string
after:
- type: string
pulumiUp:
before:
- type: string
after:
- type: string
storeState:
before:
- type: string
after:
- type: string
pulumiOutput:
before:
- type: string
after:
- type: string
destroy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
pulumiLogin:
before:
- type: string
after:
- type: string
pulumiPreview:
before:
- type: string
after:
- type: string
pulumiDestroy:
before:
- type: string
after:
- type: string
Kubernetes
version:
type: number
deploy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
k8sDiff:
before:
- type: string
after:
- type: string
k8sApply:
before:
- type: string
after:
- type: string
storeState:
before:
- type: string
after:
- type: string
destroy:
onCompletion:
- type: string
onSuccess:
- type: string
onFailure:
- type: string
steps:
setupVariables:
after:
- type: string
k8sDiff:
before:
- type: string
after:
- type: string
k8sDelete:
before:
- type: string
after:
- type: string
Handling errors
If any command in your custom flow returns a non-zero exit code, the env0 deployment will stop on a 'Failed' status. You can leverage this to perform validation - for example - asserting a certain environment variable was supplied.
In such a case, env0 will display any output from stderr
as the deployment error. If no output is found in stderr
, it will be shown as an "Unknown Error".
Error Message Handling
Use the following notation
1>&2
to redirect stdout messages to stderr. This allows env0 to display the message in its UI. (see I/O Redirection)
Here is an example -
version: 1
deploy:
steps:
setupVariables:
after:
- if [ -z "$MY_VAR" ]; then echo "MY_VAR must be supplied" 1>&2 && exit 1; fi
Exposed env0 System Environment Variables
env0 exposes the following environment variables for you to use:
Variable Name | Value Description |
---|---|
| The deployed Environment ID |
| The Project ID of the deployed Environment |
| The deployment ID |
| The deployment type. |
| The revision.
|
| The Terraform Workspace name used in the Environment |
| The root repository path |
| Your env0 organization ID |
| The deployed Template ID |
| The deployed Template path |
| The deployed Template name |
| The deployed Environment name |
| The name of the environment creator |
| The email of the environment creator |
| The name of the deployer |
| The email of the deployer |
| The name of the reviewer.
|
| The email of the reviewer.
|
| GitHub- the username PR author
|
| The source branch of the PR
|
| The target branch of the PR
|
| The commit hash of deployed Environment
|
See this sample of using these variables in our public templates repo.
The Deployment Container
Our deployment container is based on node:14.16.0-alpine and includes the following:
Includes | Version |
---|---|
Bash | 5.0.11(1)-release |
NodeJS | 12.18.3 |
NPM | 6.14.6 |
YARN | 1.22.4 |
GIT | 2.24.3 |
Python2 | 2.7.18 |
Python3 | 3.8.2 |
pip3 | 20.2 |
pip2 | 18.1 |
AWS CLI v1 (aws command) | 1.18.115 |
AWS CLI v2(awsv2 command) | 2.4.7 |
Google Cloud SDK | 304.0.0 |
Azure CLI | 2.28.1 |
kubectl | 1.15.11 |
tfenv | 1.0.1 |
Terraform default version | 0.12.24 |
jq | jq-master-v20191114-85-g260888d269 |
OpenSSL | 1.1.1g |
Powershell | 7.0.3 |
infracost | 0.9.0 |
Note
You can bring your own docker image, extending env0's default image (which is based on node:14.16.0-alpine), in case you are using our Self-Hosted Agent.
In order to learn more about custom docker images, please contact our support team.
Adding additional binaries to the container on the fly
You can easily download any binary needed using the curl
command in all steps. You can also place that new binary under opt
folder in case you need it within your PATH. Additionality, Using apk add
, pip install
and npm install
commands are accessible via sudo
.
Exporting your own environment variables
In order to export your own Environment Variable to use in any downstream custom flow you should write a shell command in the format: echo KEY=VALUE >> $ENV0_ENV
.
In later steps of the same deployment, you will be able to use $KEY
to access the stored value.
FAQ
Q. How can I use Custom Flows to add new Terraform Variables?
The recommended approach to adding terraform variables is to use variable definitions files, specifically the *.auto.tfvars
or *.auto.tfvars.json
files to pass additional variables to your Terraform code. Note: Please be aware of the Terraform Variable Definition Precedence order as defined here: https://www.terraform.io/docs/language/values/variables.html#variable-definition-precedence.
Another way is to create new Environment Variables inside the custom flow in the form TF_VAR_key=value
. To do that please follow Exporting your own environment variables.
Updated 14 days ago