# Custom Workflows

Custom workflows can be defined to override the default commands that Atlantis runs.

# Usage

Custom workflows can be specified in the Server-Side Repo Config or in the Repo-Level atlantis.yaml files.

Notes

• If you want to allow repos to select their own workflows, they must have the allowed_overrides: [workflow] setting. See server-side repo config use cases for more details.
• If in addition you also want to allow repos to define their own workflows, they must have the allow_custom_workflows: true setting. See server-side repo config use cases for more details.

# Use Cases

# .tfvars files

Given the structure:

.
└── project1
    ├── main.tf
    ├── production.tfvars
    └── staging.tfvars

If you wanted Atlantis to automatically run plan with -var-file staging.tfvars and -var-file production.tfvars you could define two workflows:

# repos.yaml or atlantis.yaml
workflows:
  staging:
    plan:
      steps:
      - init
      - plan:
          extra_args: ["-var-file", "staging.tfvars"]
    # NOTE: no need to define the apply stage because it will default
    # to the normal apply stage.
    
  production:
    plan:
      steps:
      - init
      - plan:
          extra_args: ["-var-file", "production.tfvars"]

Then in your repo-level atlantis.yaml file, you would reference the workflows:

# atlantis.yaml
version: 3
projects:
# If two or more projects have the same dir and workspace, they must also have
# a 'name' key to differentiate them.
- name: project1-staging
  dir: project1
  workflow: staging
- name: project1-production
  dir: project1
  workflow: production

workflows:
  # If you didn't define the workflows in your server-side repos.yaml config,
  # you would define them here instead.

When you want to apply the plans, you can comment

atlantis apply -p project1-staging

and

atlantis apply -p project1-production

Where -p refers to the project name.

# Adding extra arguments to Terraform commands

If you need to append flags to terraform plan or apply temporarily, you can append flags on a comment following --, for example commenting:

atlantis plan -- -lock=false

If you always need to do this for a project's init, plan or apply commands then you must define a custom workflow and set the extra_args key for the command you need to modify.

# atlantis.yaml or repos.yaml
workflows:
  myworkflow:
    plan:
      steps:
      - init:
          extra_args: ["-lock=false"]
      - plan:
          extra_args: ["-lock=false"]
    apply:
      steps:
      - apply:
          extra_args: ["-lock=false"]

If policy checking is enabled, extra_args can also be used to change the default behaviour of conftest.

workflows:
  myworkflow:
    policy_check:
      steps:
      - show
      - policy_check:
          extra_args: ["--all-namespaces"]

# Custom init/plan/apply Commands

If you want to customize terraform init, plan or apply in ways that aren't supported by extra_args, you can completely override those commands.

In this example, we're not using any of the built-in commands and are instead using our own.

# atlantis.yaml or repos.yaml
workflows:
  myworkflow:
    plan:
      steps:
      - run: terraform init -input=false
      
      # If you're using workspaces you need to select the workspace using the
      # $WORKSPACE environment variable.
      - run: terraform workspace select $WORKSPACE
      
      # You MUST output the plan using -out $PLANFILE because Atlantis expects
      # plans to be in a specific location.
      - run: terraform plan -input=false -refresh -out $PLANFILE
    apply:
      steps:
      # Again, you must use the $PLANFILE environment variable.
      - run: terraform apply $PLANFILE

# cdktf

Here are the requirements to enable cdktf

• A custom image with cdktf installed
• The autoplan file updated to trigger off of **/cdk.tf.json
• The output of cdktf synth has to be committed to the pull request
• Optional: Use pre_workflow_hooks to run cdktf synth as a double check
• Optional: There isn't a requirement to use a repo atlantis.yaml but one can be leveraged if needed.

# custom image

# Dockerfile
FROM ghcr.io/runatlantis/atlantis:v0.19.7

RUN apk add npm && npm i -g cdktf-cli

# server config

# env variables
ATLANTIS_AUTOPLAN_FILE_LIST="**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json"

OR

atlantis server --config config.yaml

# config.yaml
autoplan-file-list: "**/*.tf,**/*.tfvars,**/*.tfvars.json,**/cdk.tf.json"

# server repo config

Use pre_workflow_hooks

atlantis server --repo-config="repos.yaml"

# repos.yaml
repos:
  - id: /.*cdktf.*/
    pre_workflow_hooks:
      - run: npm i && cdktf get && cdktf synth

# repo structure

This is the git repo structure after running cdktf synth. The cdk.tf.json files contain the HCL that atlantis can run.

$ tree --gitignore
.
├── cdktf.json
├── cdktf.out
│   ├── manifest.json
│   └── stacks
│       └── eks
│           └── cdk.tf.json

# workflow

1. Container orchestrator (k8s/fargate/ecs/etc) uses the custom docker image of atlantis with cdktf installed with the --autoplan-file-list to trigger on json files
2. PR branch is pushed up containing cdktf changes and generated hcl json
3. Atlantis checks out the branch in the repo
4. Atlantis runs the npm i && cdktf get && cdktf synth command in the repo root as a step in pre_workflow_hooks (as a double check described above)
5. Atlantis detects the change to the generated hcl json files in a number of dirs
6. Atlantis then runs terraform workflows in the respective dirs as usual

# Terragrunt

Atlantis supports running custom commands in place of the default Atlantis commands. We can use this functionality to enable Terragrunt.

You can either use your repo's atlantis.yaml file or the Atlantis server's repos.yaml file.

Given a directory structure:

.
└── live
    ├── prod
    │   └── terragrunt.hcl
    └── staging
        └── terragrunt.hcl

If using the server repos.yaml file, you would use the following config:

# repos.yaml
# Specify TERRAGRUNT_TFPATH environment variable to accommodate setting --default-tf-version
# Generate json plan via terragrunt for policy checks
repos:
- id: "/.*/"
  workflow: terragrunt
workflows:
  terragrunt:
    plan:
      steps:
      - env:
          name: TERRAGRUNT_TFPATH
          command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
      - run: terragrunt plan -input=false -out=$PLANFILE
      - run: terragrunt show -json $PLANFILE > $SHOWFILE
    apply:
      steps:
      - env:
          name: TERRAGRUNT_TFPATH
          command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
      - run: terragrunt apply -input=false $PLANFILE

If using the repo's atlantis.yaml file you would use the following config:

version: 3
projects:
- dir: live/staging
  workflow: terragrunt
- dir: live/prod
  workflow: terragrunt
workflows:
  terragrunt:
    plan:
      steps:
      - env:
          name: TERRAGRUNT_TFPATH
          command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
      - run: terragrunt plan -out $PLANFILE
    apply:
      steps:
      - env:
          name: TERRAGRUNT_TFPATH
          command: 'echo "terraform${ATLANTIS_TERRAFORM_VERSION}"'
      - run: terragrunt apply $PLANFILE

NOTE: If using the repo's atlantis.yaml file, you will need to specify each directory that is a Terragrunt project.

If you don't want to create/manage the repo's atlantis.yaml file yourself, you can use the tool terragrunt-atlantis-config to generate it.

The terragrunt-atlantis-config tool is a community project and not maintained by the Atlantis team.

# Running custom commands

Atlantis supports running completely custom commands. In this example, we want to run a script after every apply:

# repos.yaml or atlantis.yaml
workflows:
  myworkflow:
    apply:
      steps:
      - apply
      - run: ./my-custom-script.sh

# Custom Backend Config

If you need to specify the -backend-config flag to terraform init you'll need to use a custom workflow. In this example, we're using custom backend files to configure two remote states, one for each environment. We're then using .tfvars files to load different variables for each environment.

# repos.yaml or atlantis.yaml
workflows:
  staging:
    plan:
      steps:
      - run: rm -rf .terraform
      - init:
          extra_args: [-backend-config=staging.backend.tfvars]
      - plan:
          extra_args: [-var-file=staging.tfvars]
  production:
    plan:
      steps:
      - run: rm -rf .terraform
      - init:
          extra_args: [-backend-config=production.backend.tfvars]
      - plan:
          extra_args: [-var-file=production.tfvars]

You would then reference the workflows in your repo-level atlantis.yaml:

version: 3
projects:
- name: staging
  dir: .
  workflow: staging
- name: production
  dir: .
  workflow: production

# Reference

# Workflow

plan:
apply:

# Stage

steps:
- run: custom-command
- init
- plan:
    extra_args: [-lock=false]

# Step

# Built-In Commands: init, plan, apply

Steps can be a single string for a built-in command.

- init
- plan
- apply

# Built-In Command With Extra Args

A map from string to extra_args for a built-in command with extra arguments.

- init:
    extra_args: [arg1, arg2]
- plan:
    extra_args: [arg1, arg2]
- apply:
    extra_args: [arg1, arg2]

# Custom run Command

Or a custom command

- run: custom-command

# Environment Variable env Command

The env command allows you to set environment variables that will be available to all steps defined below the env step.

You can set hard coded values via the value key, or set dynamic values via the command key which allows you to run any command and uses the output as the environment variable value.

- env:
    name: ENV_NAME
    value: hard-coded-value
- env:
    name: ENV_NAME_2
    command: 'echo "dynamic-value-$(date)"'

# Multiple Environment Variables multienv Command

The multienv command allows you to set dynamic number of multiple environment variables that will be available to all steps defined below the multienv step.

- multienv: custom-command

The result of the executed command must have a fixed format: EnvVar1Name=value1,EnvVar2Name=value2,EnvVar3Name=value3

The name-value pairs in the result are added as environment variables if success is true otherwise the workflow execution stops with error and the errorMessage is getting displayed.