SSH into AWS machines
This document explains how to SSH into machines in AWS, and what commands exist to navigate machines and applications quickly.
In AWS, there are no static hostnames, so we can’t have
to SSH to like in Carrenza. EC2 instances have dynamically assigned IPs, which means
ip-10-1-5-53.eu-west-1.compute.internal. Each Puppeted instance has a
“node class” (backend, frontend, …) and the list of instances belonging to these
classes is accessible via
govuk_node_list when logged onto the environment.
To help connecting to the environments, there is a wrapper tool called
govukcli. The tool
uses the idea of “contexts”, where a “context” is a specific environment. By setting a
context, any subsequent
govukcli commands will be tied to the environment you chose.
govuk-aws repository and add a symlink to make
govukcli executable globally:
cd ~/govuk git clone https://github.com/alphagov/govuk-aws ln -s ~/govuk/govuk-aws/tools/govukcli /usr/local/bin/govukcli
You will also need to have followed the Get SSH access to integration instructions.
Local dev machine
To view all possible contexts, run:
local$ govukcli list-contexts
To set a persistent context:
local$ govukcli set-context integration
Now when you SSH into an instance, it will be to one running on the specified environment:
# SSH into a 'calculators_frontend' node in current context (Integration) local$ govukcli ssh calculators_frontend
Alternatively, you can set a context for the current command only by passing a CLI parameter:
# SSH into a 'calculators_frontend' node in Staging, ignoring local context local$ govukcli ssh --context staging calculators_frontend
Note that the SSH examples above will SSH you into a random machine of the right node class. You can find out which class you need by finding the corresponding app page.
govukcli finds a matching machine via the ‘jumpbox’, which you can also SSH into directly:
local$ govukcli ssh jumpbox
The jumpbox is a special node that knows about all of the other nodes in its environment.
List the IP addresses of every node in the environment:
This long list of IPs is not very useful on its own, but you can filter it by node class:
jumpbox$ govuk_node_list -c backend
And if you can’t remember the names of the node classes, there’s a built-in helper:
jumpbox$ govuk_node_list --classes
Once you have found the IP of the machine you want to SSH into, you can manually SSH directly from the jumpbox machine:
jumpbox$ ssh ip-10-1-5-22.eu-west-1.compute.internal
You can also do this from your local machine by appending the environment to the address:
local$ ssh ip-10-1-5-22.eu-west-1.compute.internal.integration
Note that in Carrenza, there are no dynamic IPs, so you can SSH into a specific node by name.
There are no Carrenza machines on Integration anymore, so these examples assume you’ve set
# SSH into the `backend-1.backend.staging` node local$ govukcli ssh backend-1
…or as with AWS, you can SSH into a random machine of the right node class:
# This may SSH into `backend-1.backend.staging` or into a different node local$ govukcli ssh backend
Now you’re on the node running the application you want to explore. There are two main ways of interacting with the running application.
You can start up an application console (typically Rails):
…or you can start up a database console (typically PostgreSQL):
These common commands, along with
govuk_node_list, live in
Sometimes you might try to ssh into a server and nothing happens. Double-check that you
have added the key into the keychain like so:
ssh-add -K ~/.ssh/id_rsa.
Make sure you have been granted access. For example, if you have yet to be granted access to production, your attempt to SSH into a production node will fail silently.
If in doubt, run
GOVUKCLI_OUTPUT=debug govukcli ssh backend to help you to debug.