Some titbits around Terraform Cloud

I thought I would share some of the little things I have learned when getting started with terraform cloud, the reason being I struggled to find some of these little bits of info even after spending a good few sessions of googling so I wanted to share what I have learned and also highlight some of the differences between terraform cloud and other terraform pipelines you may have used. I’ll start by giving just a brief overview then jump into my titbits.

I assume you know a bit about terraform, if not check out this page as its a fantastic tool.

What is terraform cloud?

Terraform Cloud is an application that helps teams use Terraform together. It manages Terraform runs in a consistent and reliable environment, and includes easy access to shared state and secret data, access controls for approving changes to infrastructure, a private registry for sharing Terraform modules, detailed policy controls for governing the contents of Terraform configurations, and more.

Terraform Cloud is available as a hosted service at https://app.terraform.io. We offer free accounts for small teams (What this blog is about), and paid plans with additional feature sets for medium-sized businesses.

Large enterprises can purchase Terraform Enterprise, our self-hosted distribution of Terraform Cloud. It offers enterprises a private instance of the Terraform Cloud application, with no resource limits and with additional enterprise-grade architectural features like audit logging and SAML single sign-on.

Taken from.

Terraform Cloud Structure

A the time of writing terraform cloud operates with a user, organization then workspace structure. Ive done a little diagram to show what I mean:

Note: This workspace structure is not the same as local workspaces.

User

A user is global and can be invited to multiple organizations or a user can create multiple organizations and invite other users to those orgs.

Organization

The organization is the team or company, its where you manage members, billing if you're above the free tier, you can also manage VCS, API tokens and SSH keys here.

Workspaces

The workspace is where all the good stuff happens. Here you can manage your terraform version and working directory any input variables and states. Its also where your plan and apply is visualised and controlled. VCS connection and what branches to run from is also managed at this level.

Setting Up

I have personally tested terraform cloud with GitHub, GitLab and Azure DevOps and the setup for these codebases was very easy, you can find detailed guides for each here.

One of the big things I struggled with when first starting with terraform cloud was understanding how it expected you to structure your terraform. You will see from the above structure that it uses a workspace as its concept of running terraform. A workspace is specifically linked to a single terraform working directory and aws access keys.

How you set up the workspaces in relation to your own infrastructure will depend on your own organization. As I work primarily with AWS I think of a terraform workspace as an AWS account when I work with many many AWS accounts workspaces would become environments that contain X AWS accounts and we use workspace prefixes to individualise the terraform state of each account. I also do include the occasional application-specific workspace, again depends on how you setup your terraform.

Titbits

How permissions work

In each workspace, you can set some environment variable, in here you need to set your aws credentials:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION

These should be self-explanatory but if you need any help on these keys have a read of this guide.

Your providers.tf should then just be empty

provider "aws" {
}

You can if you want to still use assume role:

provider "aws" {
  assume_role {
    role_arn = "arn:aws:iam::123456789/OrganizationAccountAccessRole"
    session_name = "infra"
  }
}

The state

You can still use s3 as a remote state backend if your keys have access and you want to but terraform cloud does have its own remote state you can use. You can read more about that state here, this is what it looks like in your providers.tf:

terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "YourOrgName"

    workspaces {
      prefix = "PrefixName"
    }
  }
}

You can work with this state locally if you want to and instructions for that are in the link above.

Destroying

Terraform destroy works a little differently, to allow a destroy you need to add a special environment variable called CONFIRM_DESTROY and set it to 1.

You can then go to settings > destruction and destroy in your workspace and queue a destroy plan.

What it looks like

please excuse the poor obfuscation :)

Summary

Terraform Cloud is great, it's easy to get set up and running terraform remotely with next to no setup time or maintenance and for a small team of under five would be very beneficial cost-wise.

Its main drawbacks for me are its lack of feedback to your VCS, Terraform Cloud is a mix up of Terraform Enterprise and Atlantis https://www.runatlantis.io so its a shame there isn't a more seamless integration on your pull requests.

I will try my best to keep this post updated with anything else I come across. Feel free to reach out yourself if you want me to add anything or have questions.