Table of contents

AWS accounts

SSH into AWS machines

This document explains how to SSH into machines in AWS, as it’s markedly different than for Carrenza.

In AWS, there are no static hostnames, so we can’t have backend-1.backend.integration to SSH to like in Carrenza. EC2 instances have dynamically assigned IPs, which means hostnames like 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.


Ensure you have cloned the govuk-aws repository:

cd ~/govuk
git clone

Add a symlink to ensure you use the current version:

ln -s ~/govuk/govuk-aws/tools/govukcli /usr/local/bin/govukcli

Connecting to instances

The tool uses the idea of “contexts”, where a “context” is a specific environment.

To view the contexts run:

govukcli list-contexts

Set a context to interact with that environment:

govukcli set-context integration


In AWS you must specify a node class only. You must use _ rather than - when specifying the class.

govukcli ssh calculators_frontend

This will take you to a random instance of that class.

If you wish to go to a specific node, you can log into the jumpbox:

govukcli ssh jumpbox

Return a list of available instances:

govuk_node_list -c calculators_frontend

Use the SSH command to connect to a specific hostname.


If the environment you’re using is in Carrenza, you can connect to instances in the traditional way:

govukcli ssh backend-1

You may also use the node class to select a random node:

govukcli ssh calculators_frontend


Sometimes you might try to ssh into a server and nothing happens, double check that you added the key into the keychain like so: ssh-add -K ~/.ssh/id_rsa.

If that doesn’t work run GOVUKCLI_OUTPUT=debug govukcli ssh backend

This page was last reviewed on 17 March 2019. It needs to be reviewed again on 17 September 2019 by the page owner #govuk-2ndline .
This page was set to be reviewed before 17 September 2019 by the page owner #govuk-2ndline. This might mean the content is out of date.