Terrateam Configuration

Terrateam behavior can be configured via a config.yml. This file is located in a directory named .terrateam at the root of your Terraform repository: .terrateam/config.yml.

See Configuration documentation for details.

Apply Outside Terrateam

In some cases one might want to propose changes through a Pull Request, for visibility, however apply them locally for compliance reasons. By default, Terrateam requires any change that is merged to be applied inside of Terrateam. To ensure this, a lock is acquired on the changed directory until it is applied.

To support a directory being applied outside of Terrateam, the lock_policy option in a workflow supports configuring when a lock is acquired.

Example

For security reasons, the credentials for making IAM changes are not allowed on third-party infrastructure. However, for visibility, pull requests are created for IAM changes. With this workflow, we do not want to acquire a lock on the IAM directory. The IAM directory is environments/prod/iam. To prevent a lock from being acquired:

workflows:
  - tag_query: environments/prod/iam in dir
    lock_policy: apply

This configures Terrateam to acquire a lock only if an apply for the directory has been performed in Terrateam. Otherwise, no lock will be acquired.

Autoapply on Merge

Automatically apply Terraform changes after a pull request is merged.

All Changes

Automatically run Apply after all merge commits:

when_modified:
  autoapply: true

Target Directory

Automatically run Apply after a merge commit against a pull request with a When Modified file pattern match in the ec2 directory:

dirs:
  ec2:
    when_modified:
      autoapply: true

Automerge and Delete Branch

Upon successfully applying all changes in a pull request, automatically merge the pull request and delete the branch.

automerge:
  enabled: true
  delete_branch: true

Custom Commands

Run a custom command during a Terrateam operation:

• Pre workflow: one time per operation
• Post workflow: one time per operation
• Part of a workflow: one time per workflow in an operation

Hooks are executed a single time pre and post a Plan or Apply operation. Workflows can replace the default workflow steps Terrateam executes during an operation.

In the following example:

• Echo statements are written to the console pre and post Plan and Apply operations.
• Environment variables are echoed to the console using the cmd parameter for Plan and Apply workflow steps that run against each targeted Dirspace in the operation.
• $TERRATEAM_DIR: Current working directory for the Dirspace.
• $TERRATEAM_WORKSPACE: Workspace that is currently being executed against the Dirspace.

hooks:
  plan:
    pre:
      - type: run
        cmd: ['echo', 'pre-plan-hook']
    post:
      - type: run
        cmd: ['echo', 'post-plan-hook']
  apply:
    pre:
      - type: run
        cmd: ['echo', 'pre-apply-hook']
    post:
      - type: run
        cmd: ['echo', 'post-apply-hook']
workflows:
  - tag_query: ""
    plan:
      - type: init
      - type: run
        cmd: ['echo', 'pre-plan-workflow', '$TERRATEAM_DIR', '$TERRATEAM_WORKSPACE']
      - type: plan
      - type: run
        cmd: ['echo', 'post-plan-workflow', '$TERRATEAM_DIR', '$TERRATEAM_WORKSPACE']
    apply:
      - type: init
      - type: run
        cmd: ['echo', 'pre-apply-workflow', '$TERRATEAM_DIR', '$TERRATEAM_WORKSPACE']
      - type: apply
      - type: run
        cmd: ['echo', 'post-apply-workflow', '$TERRATEAM_DIR', '$TERRATEAM_WORKSPACE']

Disable Autoplanning

Do not automatically run a Plan operation on changes in a pull request. This is a global setting and can be overriden for specific directories with Dirs.

All Changes

when_modified:
  autoplan: false

Target Directory

Do not automatically run a Plan for changes in the ec2 directory.

dirs:
  ec2:
    when_modified:
      autoplan: false

Disable Plan and Apply

The When Modified file_patterns configuration is used to determine if a directory has a Terraform change. If a change exists then Terrateam will trigger an operation against the directory.

In the case of module directories, users usually do not want to run a Terrateam operation. Typically, module directories do not contain underlying Terraform resources. The code found in module directories are usually used as dependencies for other Terraform directories with underlying Terraform resources.

Setting the file_patterns configuration for a module directory to an empty list [], will instruct Terrateam to not trigger Terrateam operations against the directory.

Changes found in the modules directory can still be used to trigger Terrateam operations against other directories that have a dependency on the modules directory.

dirs:
  ec2/modules:
    when_modified:
      file_patterns: []

See Trigger on Terraform Modules documentation for an example on how to trigger a Terrateam operation based on a modules directory update.

Gitflow Workflow

A Gitflow-style workflow can be accomplished with Destination Branches.

The following example will trigger a Terrateam operation when performing a pull request against any release branch. It also triggers a Terrateam operation on pull requests against main, but only with a hotfix source branch.

destination_branches:
  - branch: main
    source_branches: ['hotfix/*']
  - branch: 'release/*'

Terraform Modules Directory Dependency

Create a source modules directory dependency that triggers an operation for another directory.

dirs:
  modules:
    when_modified:
      file_patterns: []
  ec2:
    when_modified:
      file_patterns: ["ec2/*.tf", "modules"]

Trigger on Modules Update

Create a directory dependency with the following rules:

• Do not automatically run a Plan operation when the modules directory is updated.
• Automatically run a Plan operation against the iam directory when the iam or modules directory is updated.

The following configuration creates a modules directory dependency for the iam directory:

dirs:
  modules:
    when_modified:
      file_patterns: []
  iam:
    when_modified:
      file_patterns: ["iam/*.tf", "iam/*.tfvars", "modules/*.tf"]