terraform-cloud-action

An action to run Terraform Cloud workspaces

This action submits a run to a Terraform Cloud workspace which performs a plan and apply. The action can be configured to return a success once the run is succesfully submitted, or it can wait for the plan to be applied by periodically polling Terraform Cloud for run status updates.

Table of Contents

• Usage
• Maintainers
• Contributing
• License

Usage

Terraform Cloud requires a .tar.gz archive containing the Terraform configuration, and build artifacts if required. The example shows a GitHub workflow archiving Lambda functions (in the build directory) alongside a Terraform configuration (in the infrastructure directory) for deployment. The archive is then passed to the action for deployment by Terraform Cloud.

- name: Create tar gz file
  run: tar --exclude *.terraform* -zcvf build.tar.gz build infrastructure

- name: Terraform Cloud
  uses: addresscloud/terraform-cloud-action@v1.0.0
  with:
    tfToken: ${{ secrets.TERRAFORM_TOKEN }}
    tfOrg: '<ORGANISATION>'
    tfWorkspace: 'my-lambda-service'
    filePath: './build.tar.gz'
    identifier: ${{ github.sha }}

If the awaitApply variable is set then once a run is confirmed the Action will poll Terraform Cloud and return success when the run status is either planned_and_finished or applied. In this example the Action will poll for updates every 60 seconds, for a maximum of 5 times. If the limit is reached before the run is complete the Action will return an error.

- name: Create tar gz file
  run: tar --exclude *.terraform* -zcvf build.tar.gz build infrastructure

- name: Terraform Cloud
  uses: addresscloud/terraform-cloud-action@v1.0.0
  with:
    tfToken: ${{ secrets.TERRAFORM_TOKEN }}
    tfOrg: '<ORGANISATION>'
    tfWorkspace: 'my-lambda-service'
    filePath: './build.tar.gz'
    identifier: ${{ github.sha }}
    awaitApply: true
    awaitInterval: 60
    retryLimit: 5

Inputs

The inputs below are required by the action to submit the run to Terraform Cloud. Additional workspace variables and settings should be configured using the Terraform Cloud UI.

tfToken

Required - Terraform Cloud access token.

tfOrganization

Required - Terraform Cloud Organization.

tfWorkspace

Required - Name of existing Terraform Cloud workspace.

filePath

Required - Path to .tar.gz archive with Terraform configuration.

identifier

Required - Unique identifier for the run (e.g. git commit sha). Reduced to 7 characters for brevity.

awaitApply

Wait for run to apply before completing.

Default: false

awaitInterval

Duration to wait (seconds) between sunsequent run status requests.

Default: 60

retryLimit

Number of times to retry Terraform Cloud API requests.

Default: 5

Outputs

runId

The identfier of the run in Terraform Cloud.

status

The status of the run in Terraform Cloud.

Note on Terraform Modules

If your repository contains multiple modules, upload the top-level directory and configure the root workspace path in the Terraform Cloud UI. For example, to deploy infrastructure/dev/services/lambda/main.tf which has references to modules in infrastructure/modules/services/lambda/module.tf upload the entire infrastructure directory and configure infrastructure/dev/services/lambda/ as the root of the workspace in the Terraform Cloud UI.

Maintainers

@tomasholderness

Contributing

PRs accepted with unit tests.

To run tests:

npm run test

To check code lint:

npm run lint

Small note: If editing the README, please conform to the standard-readme specification.

This Action was based on the example Terraform Enterprise script at: https://github.com/hashicorp/terraform-guides/tree/master/operations/automation-script

License

MPL-2.0 © 2020 Addresscloud Limited