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 level of access you have to our AWS environments.
govuk-users
can't deploy anything.*-powerusers
can deploy anything except IAM.*-administrators
can deploy anything.
You can find which class of user you are infra-security project in govuk-aws-data.
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.