Skip to main content

Atlantis Integration

Atmos natively supports Atlantis for Terraform Pull Request Automation.

How it Works​

With Atmos, all your configurations are neatly defined in YAML. This makes transformations of that data very easy.

Atmos supports three commands that, when combined, make it easy to use Atlantis:

  1. Generate the atlantis.yaml repo-level configuration: atmos atlantis generate repo-config

  2. Generate the backend configuration for all components: atmos terraform generate backends --format=backend-config|hcl

  3. Generate the full deep-merged configurations of all stacks for each component: atmos terraform generate varfiles

Configuration​

Atlantis Integration can be configured in two different ways (or a combination of them):

  • In the integrations.atlantis section in atmos.yaml
  • In the settings.atlantis sections in the stack config files

Configure Atlantis Integration in integrations.atlantis section in atmos.yaml​

To configure Atmos to generate the Atlantis repo configurations, update the integrations.atlantis section in atmos.yaml.

Here's an example to get you started. As with everything in Atmos, it supports deep-merging at all levels. Anything under the integrations.atlantis section in atmos.yaml can be overridden in the stack config sections settings.atlantis at any level of the inheritance chain.

# atmos.yaml CLI config

# Integrations
integrations:

  # Atlantis integration
  # https://www.runatlantis.io/docs/repo-level-atlantis-yaml.html
  atlantis:
    # Path and name of the Atlantis config file `atlantis.yaml`
    # Supports absolute and relative paths
    # All the intermediate folders will be created automatically (e.g. `path: /config/atlantis/atlantis.yaml`)
    # Can be overridden on the command line by using `--output-path` command-line argument in `atmos atlantis generate repo-config` command
    # If not specified (set to an empty string/omitted here, and set to an empty string on the command line), the content of the file will be dumped to `stdout`
    # On Linux/macOS, you can also use `--output-path=/dev/stdout` to dump the content to `stdout` without setting it to an empty string in `atlantis.path`
    path: "atlantis.yaml"

    # Config templates
    # Select a template by using the `--config-template <config_template>` command-line argument in `atmos atlantis generate repo-config` command
    config_templates:
      config-1:
        version: 3
        automerge: true
        delete_source_branch_on_merge: true
        parallel_plan: true
        parallel_apply: true
        allowed_regexp_prefixes:
          - dev/
          - staging/
          - prod/

    # Project templates
    # Select a template by using the `--project-template <project_template>` command-line argument in `atmos atlantis generate repo-config` command
    project_templates:
      project-1:
        # generate a project entry for each component in every stack
        name: "{tenant}-{environment}-{stage}-{component}"
        workspace: "{workspace}"
        dir: "{component-path}"
        terraform_version: v1.8
        delete_source_branch_on_merge: true
        autoplan:
          enabled: true
          when_modified:
            - "**/*.tf"
            - "varfiles/$PROJECT_NAME.tfvars"
          apply_requirements:
            - "approved"

    # Workflow templates
    # https://www.runatlantis.io/docs/custom-workflows.html#custom-init-plan-apply-commands
    # https://www.runatlantis.io/docs/custom-workflows.html#custom-run-command
    workflow_templates:
      workflow-1:
        plan:
          steps:
            - run: terraform init -input=false
            # When 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 -var-file varfiles/$PROJECT_NAME.tfvars
        apply:
          steps:
            - run: terraform apply $PLANFILE

Using the config and project templates, Atmos generates a separate atlantis project for each Atmos component in every stack.

For example, by running this command:

atmos atlantis generate repo-config --config-template config-1 --project-template project-1

the following Atlantis repo-config would be generated:

version: 3
automerge: true
delete_source_branch_on_merge: true
parallel_plan: true
parallel_apply: true
allowed_regexp_prefixes:
  - dev/
  - staging/
  - prod/
projects:
  - name: tenant1-ue2-staging-test-test-component-override-3
    workspace: test-component-override-3-workspace
    workflow: workflow-1
    dir: tests/fixtures/scenarios/complete/components/terraform/test/test-component
    terraform_version: v1.8
    delete_source_branch_on_merge: true
    autoplan:
      enabled: true
      when_modified:
        - '**/*.tf'
        - varfiles/$PROJECT_NAME.tfvars
      apply_requirements:
        - approved
  - name: tenant1-ue2-staging-infra-vpc
    workspace: tenant1-ue2-staging
    workflow: workflow-1
    dir: tests/fixtures/scenarios/complete/components/terraform/infra/vpc
    terraform_version: v1.8
    delete_source_branch_on_merge: true
    autoplan:
      enabled: true
      when_modified:
        - '**/*.tf'
        - varfiles/$PROJECT_NAME.tfvars
      apply_requirements:
        - approved
workflows:
  workflow-1:
    apply:
      steps:
        - run: terraform apply $PLANFILE
    plan:
      steps:
        - run: terraform init -input=false
        - run: terraform workspace select $WORKSPACE
        - run: terraform plan -input=false -refresh -out $PLANFILE -var-file varfiles/$PROJECT_NAME.tfvars

NOTE: If Atlantis Integration is configured only in the integrations.atlantis section in atmos.yaml, the command-line flags --config-template and --project-template are required to specify a config template and a project template from the collection of templates defined in the integrations.atlantis.config_templates and integrations.atlantis.project_templates sections in atmos.yaml. You can change this behavior by using the settings.atlantis sections in stack config files.

Configure Atlantis Integration in settings.atlantis sections in stack configs​

The integrations.atlantis.config_templates, integrations.atlantis.project_templates and integrations.atlantis.workflow_templates sections in atmos.yaml can be overridden in the settings.atlantis sections in stack config files. In fact, you don't have to define the sections in atmos.yaml at all and instead use only the settings.atlantis sections in stack configs to configure work with the Atlantis Integration.

For more details on configuring Atlantis in stack configs and using workflows, see the complete Atlantis documentation.

Try It​

Explore a working example that demonstrates Atlantis integration in action.

demo-atlantisView full example

Example: Demo Atlantis

Generate Atlantis configuration for PR-based Terraform automation.

Learn more about Atlantis Integration.

What You'll See

Try It

cd examples/demo-atlantis

# Generate Atlantis repo configuration
atmos atlantis generate repo-config --config-template config-1 --project-template project-1

# Or use the custom command
atmos atlantis build-all

Key Files

FilePurpose
atmos.yamlAtlantis templates and custom commands
stacks/Stack definitions that become Atlantis projects
Browse all files

References​

For more information, refer to: