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.
As of version v2.15.0
of gds-cli
, you can use it to deploy terraform via Jenkins.
3. Get GitHub Credentials
You need to obtain your GitHub credentials by creating a read-only GitHub personal access token. This GitHub personal access token should be
created with the read:org
scope only.
Take care to store and handle the token securely. If you accidentally share your token, revoke it immediately and follow the instructions for reporting a potential data security incident.
Deploying Terraform
Always plan
first, check that the output is what you expect, then apply
.
There are 2 ways of deploying terraform:
1. gds-cli
To deploy terraform using gds-cli
, you should run:
GITHUB_USERNAME=<github_username> GITHUB_TOKEN=<github_token> \
gds govuk terraform -e <environment> -p <project> -s <stack> -a <action> -r <aws_role>
Where:
<github_username>
is the name of your GitHub account<github_token>
is the GitHub token that you created as described above<environment>
is the govuk environment you want to deploy to. E.g.integration
,staging
<project>
is the terraform project that you want to deploy. E.g.app-gatling
<stack>
is the govuk stack you want to deploy to. E.g.blue
(which is usually forapp-
projects),govuk
(which is usually forinfra-
projects)<action>
is the terraform action you want to perform. E.g.plan
,apply
<aws_role>
is the govuk aws role you want to use for terraforming. E.g.govuk-integration-admin
After you deploy, you can visit the deploy
Jenkins job to see the job running or queued.
2. deploy.rb
script in govuk-aws
The Ruby script tools/deploy.rb
in the govuk-aws
repository takes care of requesting temporary
AWS credentials with an assumed role and queuing the deployment Jenkins job.
You can use it by running:
GITHUB_USERNAME=<your GitHub username> \
GITHUB_TOKEN=<your GitHub personal access token> \
gds aws <your role e.g. govuk-integration-admin> -- \
~/govuk/govuk-aws/tools/deploy.rb blue app-backend integration plan
You will need to change the arguments to the deploy.rb
script. E.g.
app-backend
should be the name of the project you want to deployblue
is forapp-
projects,govuk
is forinfra-
projects usuallyintegration
is the starting point, thenstaging
, etc.
Once the script has run, visit the deploy
Jenkins job to see the job running or queued.