GitHub Action: atmos-terraform-plan
This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.
Introduction
This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.
After running this action, apply Terraform with the companion action, github-action-atmos-terraform-apply
Usage
Prerequisites
This GitHub Action requires AWS access for two different purposes. This action will attempt to first run terraform plan
against a given component and
then will use another role to save that given Terraform Plan to an S3 Bucket with metadata in a DynamoDB table. We recommend configuring
OpenID Connect with AWS
to allow GitHub to assume roles in AWS and then deploying both a Terraform Plan role and a Terraform State role.
For Cloud Posse documentation on setting up GitHub OIDC, see our github-oidc-provider
component.
In order to store Terraform State, we configure an S3 Bucket to store plan files and a DynamoDB table to track plan metadata. Both will need to be deployed before running
this action. For more on setting up those components, see the gitops
component (documentation pending). This action will then use the github-action-terraform-plan-storage action to update these resources.
Workflow example
name: github-action-atmos-terraform-plan
on:
workflow_dispatch: {}
pull_request:
types:
- opened
- synchronize
- reopened
branches:
- main
# These permissions are required for GitHub to assume roles in AWS
permissions:
id-token: write
contents: read
jobs:
plan:
runs-on: ubuntu-latest
steps:
- name: github-action-atmos-terraform-plan
uses: cloudposse/github-action-atmos-terraform-plan@v1
with:
component: "foobar"
stack: "plat-ue2-sandbox"
component-path: "components/terraform/s3-bucket"
terraform-plan-role: "arn:aws:iam::111111111111:role/acme-core-gbl-identity-gitops"
terraform-state-bucket: "acme-core-ue2-auto-gitops"
terraform-state-role: "arn:aws:iam::999999999999:role/acme-core-ue2-auto-gitops-gha"
terraform-state-table: "acme-core-ue2-auto-gitops"
aws-region: "us-east-2"
Inputs
Name | Description | Default | Required |
---|---|---|---|
atmos-config-path | The path to the atmos.yaml file | atmos.yaml | false |
atmos-version | Atmos version to use for vendoring. Default 'latest' | latest | false |
aws-region | AWS region for assuming identity. | us-east-1 | false |
branding-logo-image | Branding logo image url | https://cloudposse.com/logo-300x69.svg | false |
branding-logo-url | Branding logo url | https://cloudposse.com/ | false |
component | The name of the component to plan. | N/A | true |
component-path | The path to the base component. Atmos defines this value as component_path. | N/A | true |
debug | Enable action debug mode. Default: 'false' | false | false |
drift-detection-mode-enabled | Indicate whether this action is used in drift detection workflow. | false | true |
enable-infracost | Whether to enable infracost summary. Requires secret infracost-api-key to be specified. Default: 'false | false | false |
infracost-api-key | Infracost API key | N/A | false |
metadata-retention-days | Infracost API key | 1 | false |
sha | SHA to use | ${{ github.event.pull_request.head.sha }} | true |
stack | The stack name for the given component. | N/A | true |
terraform-plan-role | The AWS role to be used to plan Terraform. | N/A | true |
terraform-state-bucket | The S3 Bucket where the planfiles are stored. | N/A | true |
terraform-state-role | The AWS role to be used to retrieve the planfile from AWS. | N/A | true |
terraform-state-table | The DynamoDB table where planfile metadata is stored. | N/A | true |
terraform-version | The version of Terraform CLI to install. Instead of full version string you can also specify constraint string starting with "<" (for example <1.13.0 ) to install the latest version satisfying the constraint. A value of latest will install the latest version of Terraform CLI. Defaults to latest . | latest | false |
token | Used to pull node distributions for Atmos from Cloud Posse's GitHub repository. Since there's a default, this is typically not supplied by the user. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting. | ${{ github.server_url == 'https://github.com' && github.token || '' }} | false |
Outputs
Name | Description |
---|---|
summary | Summary |