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-userscan't deploy anything.*-poweruserscan deploy anything except IAM.*-administratorscan 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,govuk<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-backendshould be the name of the project you want to deployblueis forapp-projects,govukis forinfra-projects usuallyintegrationis the starting point, thenstaging, etc.
Once the script has run, visit the deploy Jenkins job to see the job running or queued.