Terraforming Terraform
We all have one sitting around some where, a Jenkins Server under the IT departments control, not ever building code, but running things for the IT department. Things that used to run as a Cron Job, Reports. One of the the favorite tasks to relegate to Jenkins is our Terraform Jobs. We have Jenkins pull code from Git, run a plan or apply and store the state in S3 or similar.
We normally craft the Jenkins jobs by hand and duplicate one to another as we add more things for terraform to do. If we are really sophisticated, we create a script that creates the Jenkins job automatically like we do for big software development projects.
In my last project, we gave the butler, Jenkins, the pink slip for Terraforming tasks and moved to Terraform Cloud. Terraform Cloud is a service that is hosted by Hashicorp. It scans your git repos for changes (works very easy if you are github hosted) and when it see’s a change in git, it runs a ‘terraform plan’ automatically.
When Terraform Cloud determines that an Apply needs to occur, it puts the job in “Needs Confirmation” and waits for a person to Approve. It’s really cool and is a web site designed around implementing Terraform, and not a general purpose Jenkins.
Enough of the Terraform Cloud Pitch
I’m not here to sell Terraform cloud, it’s cool, you should at least take a look at it. What I am here to explain today is how to use Terraform itself to create jobs in Terraform Cloud.
There are several things you need to configure each Terraform cloud job.
- A git repository name
- Folders in the Repo that have your source
- Additional folders in the Repo to Watch for changes (your modules)
- Variables to put in the terraform.tfvars file
- Environment variables to set for the job
The last two were the trigger for me to say ‘we need to automate this’. Terraform cloud may or may not have access to Vault, AWS KVM, Azure Key Vault. So you need to figure out how to get secrets into Terraform Cloud. Even if your jobs have access to your secret store, you are going to need to pass some credentials for them to open your secret store.
Create an Organization
Create an account on app.terraform.io and then create an organization. Hashicorp has this all nicely documented. You will want to configure a VCS connection to github so that you can fetch my demo code from Terraform Cloud.
Process Flow
There are a few steps to creating jobs, since we have a totally blank Terraform Cloud organization.
Master-Workspace-Creator
This is a Terraform script that we will run locally on our machine. It bootstraps the process and creates the main job, the Workspace-Creator. This runs on a local machine.
Workspace-Creator
This is the job that creates all of the workspaces that go out and actually create infrastructure. This runs in Terraform Cloud.
Workspaces
Each Workspace is a set of Terraform scripts that goes out and creates infrastructure. In the old world, this would be a Jenkins Job that runs your terraform. These run in Terraform Cloud also.
Master-Workspace-Creator
This section will create our first workspace in Terraform Cloud. Once this workspace is created, it will produces as many workspaces as we need.
You will need to have Terraform installed locally (version 0.12.xx) and clone my demonstration repo:
git clone git@github.com:stvdilln/terraform-cloud-demo.gitIn the demo repository, cd to master-workspace-creator and edit tc-connection.auto.tfvars, filling in the blank variables.
# We need to connect to terraform cloud to create the job, and
# need these parameters#Go into terraform cloud site, Organization-> Settings-> VCS Providers and provide the Oauth Token ID"oauth_token_id = ""
#The organization you created
organization_name = ""
#Token to Log into Terraform Cloud.
#Goto https://app.terraform.io/app/settings/tokens and generate a token.
tfe_token = ""
Run the Master-Workspace-Creator which will create the Workspace-Creator in Terraform Cloud.
cd master-workspace-creator
terraform init
terraform applyWorkspace Creator
You can now go to the Terraform Cloud website and see the newly created Workspace-Creator workspace. Of interest is the Variables for the workspace. We have created a couple of demonstration secrets that can be used and passed down the the individual workspaces. The secret_bundle1 and the payg_subcription_client_secret will be passed on to the created workspace.
Run the Workspace-Creator
We have made the leap into the cloud, and we won’t be running terraform on the local machine anymore. In the UI: Workspace->Creator->Queue Plan. This will do a ‘terraform plan’ in the workspace-specs folder of our repo. Confirming and doing the apply will then create the demo1 workspace.
The specification for the workspace Demo1 is contained in workspace-specs/demo1/main.tf
There is a tfe_workspace resource that defines what source repository and directory therein that we should be running terraform in (in this case stvdilln/terraform-cloud-demo/workspaces/demo1). It also passes some secrets from the workspace creator, to the workspace itself.
The Demo1 Workspace
After you have run the workspace-creator, all of the workspaces in the directory workspace-specs will be created. In this case the workspace demo1 will have been created. It is hardly even a ‘Hello World’, but you can see how the secret variables have made it from your machine and made a secure journey down to the individual workspace. Secrets are better with a secret keeper around, but this can get you started.
Wrapping Up
Today we went through a brief introduction to Terraform Cloud, it’s pretty cool and much nicer than Jenkins to run terraform jobs. We created our first Terraform Cloud Job from Terraform on our local machine. We now have a Workspace-Creator job that will create any number of workspaces that are defined in the workspace-specs directory.
I hope you enjoyed this walk though,
Thanks,
Steve
