This blog is currently hosted on AWS EC2. Until recently I would always connect to my EC2 instance via SSH client. An alternative approach I learned of recently is to connect via Session Manager, a feature of AWS Systems Manager. A main benefit of Session Manager is that it removes the need to open inbound ports to the instance or manage SSH keys as Session Manager handles these security details for you.
Using Session Manager involves a few prerequisites, which can be reduced to the following three-step process:
- Provisioning the EC2 instance with the SSM* agent
- Provisioning the EC2 instance with an IAM role
- Restarting the SSM agent to detect the IAM role
* Simple Systems Manager
Detailed instructions follow. Note that these instructions are specific to Ubuntu 14.04, which I appreciate is quite outdated at time of writing. Steps 1 and 3 require you to be connected to an EC2 instance (for example via SSH client). Step 2 requires you to be logged in to the AWS Management Console.
Provisioning the EC2 instance with the SSM agent
The first main step toward connecting to an EC2 instance via Session Manager is to install the SSM agent on the EC2 instance. For my OS this involved running the following commands against the instance:
// Update the OS package index sudo apt-get update // Download the SSM agent package wget https://s3.amazonaws.com/amazon-ssm-us-east-1/latest/debian_amd64/amazon-ssm-agent.deb // Install the SSM agent package sudo dpkg -i amazon-ssm-agent.deb // Start the SSM agent sudo start amazon-ssm-agent // Verify the SSM agent status sudo status amazon-ssm-agent
This last command should produce output like the following:
amazon-ssm-agent start/running, process 4180
Provisioning the EC2 instance with an IAM role
The second main step toward connecting to an EC2 instance via Session Manager is to provision the EC2 instance with an IAM role granting permission to Session Manager to connect to the instance. This step involves (1) creating the IAM role and (2) attaching the role to the instance.
Create an IAM role for the EC2 instance
From the AWS Management Console go to IAM. From the left nav click Roles and from the top-right click “Create Role.” You should be taken to a three-step wizard for creating an IAM role.
The first step is to select the trusted entity for the role. For “Trusted Entity Type” choose “AWS Service.” For “Use Case” choose EC2 as Service and “EC2 Role for AWS Systems Manager” as “Use Case.” You can then proceed to the next step of the wizard.
The second step is to add permissions to the role. All you should need to do for this step is to verify that the relevant policy (AmazonSSMManagedInstanceCore) is attached to the role, which the use case chosen in the previous step should take care of automatically. You can then proceed to the next step of the wizard.
The last step is to name, review, and create the role. Under “Role details” add a name and description for the role. Then create the role and verify that it was created successfully.
Attach the IAM role to the EC2 instance
Still in the AWS Management Console go to EC2. From the left nav click Instances and from the Instances pane select the relevant instance. From the Security submenu of the Actions menu select “Modify IAM Role.” From the “IAM role” menu select the role you created in the previous step. Then click “Update IAM role.”
From the Instances pane select the relevant instance again (assuming it’s not already selected). Verify that the role is attached to the instance–it should be listed under the “IAM Role” heading in the Details tab of the Instances pane.
Still in the Instances pane and with the relevant instance still selected, click Connect. From the “Connect to instance” page select the “Session Manager” tab. You should be presented with a page that resembles the following screenshot:
Note (a) the disabled Connect button and (b) the warning about the instance not being connected to Session Manager–both would be expected at this stage since it’s necessary to restart the SSM agent in order for the instance to detect the updated IAM role.
Restarting the SSM agent to detect the IAM role
The last main step, then, toward connecting to an EC2 instance via Session Manager is to restart the SSM agent in order for EC2 to detect the updated IAM role. For my OS this involved running the following command against the instance:
sudo restart amazon-ssm-agent
Back in the AWS Management Console refreshing the “Connect to instance” page should result in a page that resembles the following screenshot:
Note that (a) the warning about the instance not being connected to Session Manager has disappeared and (b) the Connect button has been enabled. If you go ahead and click the Connect button you should be presented with a browser-based terminal from which you can run commands against the EC2 instance.
Congratulations! You’ve now successfully connected to an EC2 instance via Session Manager.