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