From 259a4a394b11875df907f41b7515d154041a1418 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Wed, 17 Jun 2020 10:36:14 +0100 Subject: [PATCH] guides: Modernize guides for environment provisioning - I don't like individual `brew install` commands littered across a doc. - Some of the markdown was incorrect. - These probably need more tweaks, but we can make them once we've done the thing for the first time in years. --- docs/guides/bootstrap-aws.md | 19 ++++++------- docs/guides/environment-provisioning.md | 36 +++++++++++-------------- 2 files changed, 24 insertions(+), 31 deletions(-) diff --git a/docs/guides/bootstrap-aws.md b/docs/guides/bootstrap-aws.md index 12af9c377..8b4d898ff 100644 --- a/docs/guides/bootstrap-aws.md +++ b/docs/guides/bootstrap-aws.md @@ -8,7 +8,7 @@ The new account has a bootstrap role that you should be able to assume to start There are several ways to do this -###### AWS-CLI +###### AWS CLI Make sure your laptop is configured with credentials to access the gds-users account. If you can login in gds-users from the command line, you should be able to get the credentials of an assumed role with the following command: @@ -23,13 +23,13 @@ aws sts assume-role \ ###### AWS-VAULT -Download and install a copy of AWS Vault from the official repo: -https://github.com/99designs/aws-vault +`brew cask install aws-vault` on macOS, or `brew install aws-vault` on Linux. Follow the instructions to set up your initial profile. A good tutorial that explains this step by step can be found here: https://medium.com/devopslinks/step-by-step-aws-iam-assumerole-with-aws-vault-configuration-9d5986373c33 -After following the tutorial you should have a ``` ~/.aws/config ``` file similar to the example below. You may have more or less profile entries depending on how many environments you have access to: +After following the tutorial you should have an `~/.aws/config` file similar to the example below. + ``` [profile readonly] region=eu-west-1 @@ -42,14 +42,12 @@ mfa_serial = arn:aws:iam::11111111111:mfa/your.name@email.provider ``` After setting up aws-vault you can generate a token by running the following: + ``` aws-vault exec environmentname -- env ``` -For Example: -``` -aws-vault exec staging -- env -``` -Some temporary credentials will be outputted to screen, copy the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and the AWS_SESSION_TOKEN + +Some temporary credentials will be shown in the terminal - copy the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and the AWS_SESSION_TOKEN. Create a new file (e.g. aws_temp_cred) somewhere on your local machine and paste the credentials into it, so it looks similar to the example below @@ -58,9 +56,8 @@ export AWS_ACCESS_KEY_ID=YOURACCESSKEY export AWS_SECRET_ACCESS_KEY=YOURSECRETKEY export AWS_SESSION_TOKEN=YOURLONGSESSIONTOKEN ``` -Now run the source command on the file to make the credentials available for Terraform, for example: -``` source ./aws_temp_cred ``` +Then, `source ./aws_temp_cred`. ## Setting up Terraform work environment diff --git a/docs/guides/environment-provisioning.md b/docs/guides/environment-provisioning.md index c349b4ad5..851ae7805 100644 --- a/docs/guides/environment-provisioning.md +++ b/docs/guides/environment-provisioning.md @@ -3,6 +3,7 @@ This document discusses how to create a new environment in AWS. Discussion as to the decisions taken can be found in the [architecture/decisions](architecture/decisions) directory, of particular note is [the environment bootstrapping process](architecture/decisions/0009-environment-bootstrapping-process.md). To clarify terms used here there is a [glossary](#glossary). Throughout this document `` indicates a value you supply (e.g. a stack name) and: + ``` bar ``` @@ -23,30 +24,21 @@ The general steps for provisioning a new environment are: ## Requirements -* [Git](https://git-scm.com/) installed via [Xcode cli tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)/[brew](https://brew.sh/) -* [Terraform = 0.11.14](https://www.terraform.io/downloads.html) installed via that link -* [ssh-copy-id](https://www.ssh.com/ssh/copy-id) installed via `brew install ssh-copy-id` -* [aws-cli](https://aws.amazon.com/cli) installed via `brew install awscli` or `pip install awscli` +* Install [Homebrew](https://brew.sh) on macOS or Linux. +* Install necessary packages: -If you've not used the aws-cli before run -``` -aws configure +```shell +brew install git tfenv ssh-copy-id awscli ``` -to set your access id, secret and the region to use. - -## Cloning the repositories -You will need to have cloned the following repositories to your local machine +* Install the version of Terraform specified in `.terraform-version` with `tfenv install`. -* [govuk-puppet](https://github.com/alphagov/govuk-puppet) -* [govuk-secrets](https://github.com/alphagov/govuk-secrets) -* [govuk-aws-data](https://github.com/alphagov/govuk-aws-data) -* [govuk-aws (this one)](https://github.com/alphagov/govuk-aws) +* Clone the following repositories to your local machine -e.g. -``` -git clone git@github.com:alphagov/govuk-secrets.git -``` + * [govuk-puppet](https://github.com/alphagov/govuk-puppet) + * [govuk-secrets](https://github.com/alphagov/govuk-secrets) + * [govuk-aws-data](https://github.com/alphagov/govuk-aws-data) + * [govuk-aws (this one)](https://github.com/alphagov/govuk-aws) > **NOTE: Ensure Puppet has all dependencies installed** > @@ -67,10 +59,13 @@ aws s3 ls $TERRAFORM_BUCKET ``` If the bucket is missing you'll see an error: + ``` An error occurred (NoSuchBucket) when calling the ListObjects operation: The specified bucket does not exist ``` + otherwise you'll see the bucket's contents, one directory per existing stack: + ``` PRE blue/ PRE green/ @@ -78,7 +73,8 @@ PRE govuk/ ... ``` -To create an S3 bucket run the following in order to create a bucket and enable versioning on it: +Create an S3 bucket and enable versioning on it: + ``` aws s3 mb "s3://${TERRAFORM_BUCKET}" aws s3api put-bucket-versioning \