DocumentationAPI Reference

Custom Flows

Suggest Edits

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

CloudFormation

version:
  type: number

deploy:
  onCompletion:
    - type: string
  onSuccess:
    - type: string
  onFailure:
    - type: string

  steps:
    setupVariables:
      after:
        - type: string

    cfCreateChangeSet:
      before:
        - type: string
      after:
        - type: string

    cfDeploy:
      before:
        - type: string
      after:
        - type: string

    cfOutput:
      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

    cfListStackResources:
      before:
        - type: string
      after:
        - type: string

    cfDeleteStack:
      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

ENV0_ENVIRONMENT_ID

The deployed Environment ID

ENV0_PROJECT_ID

The Project ID of the deployed Environment

ENV0_DEPLOYMENT_LOG_ID

The deployment ID

ENV0_DEPLOYMENT_TYPE

The deployment type.
One of deploy / destroy / prPlan

ENV0_DEPLOYMENT_REVISION

The revision.

  • Available only when deployment revision defined

ENV0_WORKSPACE_NAME

The Terraform Workspace name used in the Environment

ENV0_ROOT_DIR

The root repository path

ENV0_ORGANIZATION_ID

Your env0 organization ID

ENV0_TEMPLATE_ID

The deployed Template ID

ENV0_TEMPLATE_DIR

The deployed Template path

ENV0_TEMPLATE_NAME

The deployed Template name

ENV0_ENVIRONMENT_NAME

The deployed Environment name

ENV0_ENVIRONMENT_CREATOR_NAME

The name of the environment creator

ENV0_ENVIRONMENT_CREATOR_EMAIL

The email of the environment creator

ENV0_DEPLOYER_NAME

The name of the deployer

ENV0_DEPLOYER_EMAIL

The email of the deployer

ENV0_REVIEWER_NAME

The name of the reviewer.

  • Available only after approve was clicked.

ENV0_REVIEWER_EMAIL

The email of the reviewer.

  • Available only after approve was clicked.

ENV0_PR_AUTHOR

GitHub- the username PR author
GitLab- the username commit author

  • Available only in PR plan

ENV0_PR_SOURCE_BRANCH

The source branch of the PR

  • Available only in PR plan

ENV0_PR_TARGET_BRANCH

The target branch of the PR

  • Available only in PR plan

ENV0_COMMIT_HASH

The commit hash of deployed Environment

  • Available only in PR plan

See this sample of using these variables in our public templates repo.

The Deployment Container

Our deployment container is based on node:16.10.0-alpine3.11 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.1188.0

Google Cloud SDK

392.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.10.11

📘

Note

You can bring your own docker image, extending env0's default image (which is based on node:16.10.0-alpine3.11), 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.

Forcing Manual Approvals

Whenever ENV0_REQUIRES_APPROVAL=true env0 will force a deployment to be approved regardless of the "Auto Approval" setting in the environment. For example, instead of failing a deployment based on some policies, we can use this field to help ensure that someone can still review and proceed with the deployment.

Usage:
- echo ENV0_REQUIRES_APPROVAL=true >> $ENV0_ENV

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 about 1 month ago

Did this page help you?