Skip to main content
  1. Home
  2. Deployment
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 18 May 2022

Deploy Terraform

We use Terraform for configuring GOV.UK infrastructure in AWS.

One-time setup

1. Check that you have sufficient access

Which changes you can deploy depends on the role you have assumed in our AWS environments.

  • govuk-users can only assume readonly roles, so cannot apply terraform
  • people with production access can assume poweruser roles, which can deploy anything except IAM
  • people with production access can assume administrator roles, which can deploy anything

You should always use the least privileged role that will let you accomplish your task.

Unless your terraform plan needs to make changes to IAM resources, use a poweruser role.

2. Install gds-cli

gds-cli is the preferred way of obtaining AWS credentials.

Deploy Terraform via Jenkins

Always plan first, check that the output is what you expect, then apply.

Before you begin, run the following command using gds-cli:

gds aws govuk-integration-admin -e

This will allow you to retrieve several AWS access keys that the Jenkins job requires to run.

In the ‘Deploy_Terraform_GOVUK_AWS’ Jenkins job, click “Build with Parameters” and enter the following for each field:

  • AWS_ACCESS_KEY_ID: can be retrieved from the above command
  • AWS_SECRET_ACCESS_KEY: can be retrieved from the above command
  • AWS_SESSION_TOKEN: can be retrieved from the above command
  • COMMAND: the terraform action you want to perform. E.g. plan, apply
  • ENVIRONMENT: the govuk environment you want to deploy to. E.g. integration,staging
  • STACKNAME: the govuk stack you want to deploy to. E.g. blue (which is usually for app- projects), govuk (which is usually for infra- projects)
  • PROJECT: the terraform project that you want to deploy. E.g. app-gatling, infra-security

All other fields can be left as they are.

Click “build” and terraform should deploy as expected. Remember to deploy to staging and/or production as required.

Other ways of invoking Jenkins

As of version v2.15.0 of gds-cli, you can use it to deploy terraform via Jenkins. Note that you should use at least v5.25.0 of gds-cli, otherwise you will need to manually specify the branches of govuk-aws and govuk-aws-data (see below).

GITHUB_USERNAME=<your GitHub username> \
  GITHUB_TOKEN=<your GitHub personal access token> \
  gds govuk terraform -r <your role e.g. govuk-integration-admin> \
  -e <environment, eg integration> \
  -p <project to deploy> \
  -s <stack to deploy to, eg blue for projects, govuk for infrastructure> \
  -a <action, eg plan or apply>
  -b <(optional) branch of govuk-aws>
  -d <(optional) branch of govuk-aws-data>

This command takes care of requesting temporary AWS credentials with an assumed role and queue the deployment Jenkins job, and is a little less awkward than copying and pasting your credentials into Jenkins repeatedly. You’ll still need to view the job progress in Jenkins.

For more details, run gds govuk terraform --help.

More in the Deployment section

Learn

How to...