I am currently enrolled in the GitOps for Terraform MiniCamp being run by Derek Morgan and Andrew Brown.
One of the tasks is to configure a GitHub Action that will run terraform and store the state file in Terraform Cloud.
This presumes you have already configured OIDC Authentication for AWS and Terraform. If not you can follow this video by Derek.
Pre-Requisites
To setup the action we require the following.
Request an API Token from Terraform Cloud
Login to Terraform in your GitHub Codespace
Storing the token in the repository with the name
TF_API_TOKEN
If using environments within the repository, the secret
TF_API_TOKEN
needs to be set in these environments too.Modify Terraform code to connect to the workspace
Reference the Terraform API Token within the action
Request API Token
Generate a User API token via https://app.terraform.io/app/settings/tokens
This will generate a Pop-Up Window
You can set the expiration for longer than 30 days but following best security practices it is better to have the token for a short period.
Store the generated token in a safe place as we will need it in the following steps.
Login to Terraform in your GitHub Codespace
From the terminal in your codespace use the following command terraform login
You will be prompted to type yes
, do so.
When you type yes, codespace will try to open another browser window. As Pop-Up windows are blocked by default you will only see a black screen as shown below.
Type q
to quit
Press y
to confirm
Paste the API Token we generated earlier here. If successful you will see the message below with your username.
Retrieved token for user your-username
---------------------------------------------------------------------------------
-
----- -
--------- --
--------- - -----
--------- ------ -------
------- --------- ----------
---- ---------- ----------
-- ---------- ----------
Welcome to HCP Terraform! - ---------- -------
--- ----- ---
Documentation: terraform.io/docs/cloud -------- -
----------
----------
---------
-----
-
New to HCP Terraform? Follow these steps to instantly apply an example configuration:
$ git clone https://github.com/hashicorp/tfc-getting-started.git
$ cd tfc-getting-started
$ scripts/setup.sh
Store the API token in the repository
We need to store the token in the repository with the name TF_API_TOKEN
. We will do using the GitHub CLI.
To add a secret using the GitHub client use the following command
gh secret set secret_name
To set our secret named TF_API_TOKEN
you will use the following command
gh secret set TF_API_TOKEN
Store the API Token in repository environments
To set the API token in an environment named Production
use the following formatgh secret set -e environment_name secret_name
So to set TF_API_TOKEN
in an environment named Production use the following command.
gh secret set -e Production TF_API_TOKEN
Modify Terraform code to connect to the workspace
Add the following code block to your Terraform configuration files to set up the cloud integration . I added this to a file called providers.tf
terraform {
cloud {
# The name of your Terraform Cloud organization.
organization = "organisation_name"
# The name of the Terraform Cloud workspace to store Terraform state files in.
workspaces {
name = "workspace_name"
}
}
required_providers {
aws = {
source = "hashicorp/aws"
version = "5.69.0"
}
}
}
Reference the Terraform API Token within the action
The Terraform API Token can then be referenced in an actions file with the following snippet:${{ secrets.TF_API_TOKEN }}
as shown in the snippet below where we modify the hashicorp/setup-terraform@v3 action to reference the TF_API_TOKEN
secret we stored earlier.
# Install the latest version of Terraform CLI and configure the Terraform CLI configuration file with a Terraform Cloud user API token
- name: Setup Terraform
uses: hashicorp/setup-terraform@v3
with:
cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}
Successful Output
If everything has been configured correctly you will see the following. This means that the action was able to connect successfully to the configured backend. The most important output is the coloured text.HCP Terraform has been successfully initialized!
Error Output
If any of the above settings are not configured properly you will see the following error.
To resolve these double-check the above steps to make sure you have not missed anything and most importantly committed and pushed your changes to the repository.
References
When troubleshooting this issue I found the below resources useful.
https://courses.morethancertified.com/p/gitops-with-terraform
https://developer.hashicorp.com/terraform/language/backend/remote
https://github.com/morethancertified/gitops-minicamp-2024-tf
https://developer.hashicorp.com/terraform/tutorials/cloud-get-started/cloud-login
https://dailystuff.nl/blog/2022/run-terraform-within-github-codespaces
https://developer.hashicorp.com/terraform/cli/config/config-file
https://developer.hashicorp.com/terraform/cli/config/config-file#credentials
https://developer.hashicorp.com/terraform/cli/config/config-file#environment-variable-credentials
https://developer.hashicorp.com/terraform/tutorials/cloud-get-started/cloud-create-variable-set
https://developer.hashicorp.com/terraform/tutorials/cloud-get-started/cloud-workspace-create
https://developer.hashicorp.com/terraform/cloud-docs/run/cli#remote-backend-configuration
https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables
https://developer.hashicorp.com/terraform/cli/config/config-file#credentials
https://www.reddit.com/r/Terraform/comments/16uau7d/how_to_authenticate_to_terraform_cloud_when/
https://registry.terraform.io/providers/integrations/github/latest/docs/resources/actions_secret
https://registry.terraform.io/providers/integrations/github/latest/docs
https://blog.gitguardian.com/how-to-handle-secrets-in-terraform/