In the previous post – Using SSM Session Manager for interactive instance access – I showed you how to access EC2 instances through AWS Systems Manager (SSM) Sessions without having to open Security Groups or firewall ports, maintain SSH keys, VPNs, Jump Hosts, and so on.

The native way for starting a SSM Session with aws ssm start-session requires the knowledge of the exact Instance ID, e.g. i-01234567890abcdef. That’s not very user friendly unfortunately. I know what my “pet” instances Host Names or Instance Names are. And I can often see the IP addresses of a misbehaving auto-scaling instances in the logs. However I don’t always know the corresponding Instance ID.

ssm-session for your convenience

That’s why I decided to develop ssm-session, an utility that can do {anything}-to-{instance-id} resolution and then call aws ssm start-session.

IMPORTANT: ssm-session only recognises the instances registered in AWS Systems Manager (SSM)!

Instances that are not registered in SSM Inventory will not be resolved by ssm-session nor will they show up in --list output.

The ssm-session currently understands these instance identifiers:

  • Instance ID – For example i-01234567890abcdef. Just use it, nothing else to do here.
  • Instance Name – Resolved from the EC2 Instance Name Tag, e.g. test1
  • Host Name – That’s what the `hostname` command on the instance says and what’s reported by the SSM Agent to the SSM Inventory, e.g. test1.aws.nz. This is not the registered DNS name! That can be different and is not resolved here!
  • Private or Public IP address – Taken from the EC2 details.

ssm-session examples

Here are a few simple usage examples.

1) List instances registered in SSM Inventory

mludvig@aws.nz ~ $ ssm-session --list
i-01234567890abcdef   test1.aws.nz                                      test1   192.168.145.158
i-09876543210fedcba   ip-172-31-1-178.ap-southeast-2.compute.internal   test2   172.31.1.178  52.123.12.3

As mentioned above the hostname displayed in the second column is as reported by the SSM Agent. It may not correspond with the registered DNS name!

If you don’t see the instances you expect you

2) Open a session by Instance ID

(mylaptop) ~ $ ssm-session i-01234567890abcdef
Starting session with SessionId: michael.ludvig-047de6a9be69e73f9
sh-4.2$ hostname
test1.aws.nz
sh-4.2$ exit
Exiting session with sessionId: michael.ludvig-047de6a9be69e73f9.

3) Open a session by Instance Name using a specified credentials profile

Here the name test1 automatically resolves to the matching instance id i-01234…def. The credentials profile (and / or region) is used both for the name resolution as well as for starting the actual connection.

(mylaptop) ~ $ ssm-session --profile aws-nz --verbose test1
{ssm-session} INFO: Running command: aws --profile aws-nz ssm start-session --target i-01234567890abcdef
Starting session with SessionId: michael.ludvig-06193ef348f19afe7
sh-4.2$ hostname
test1.aws.nz

Download

ssm-session script is part of my aws-utils collection. Clone the whole repo from GitHub or download just the ssm-session script.

Troubleshooting

If some of your instances do not show up in the `–list` output or you’re unable to start a session make sure that:

  1. The instance IAM Role has AmazonEC2RoleforSSM managed IAM Policy attached.
  2. Up to date amazon-ssm-agent process is running on the instance.
  3. The instance can connect to ssm.{region}.amazonaws.com either directly with Public IP or through NAT or through a Proxy.

Common error messages

  • An error occurred (TargetNotConnected) when calling the StartSession operation: i-07c186e0429021bc5 is not connected.
    • Most likely your amazon-ssm-agent is outdated. Update it and restart it.
  • [ssm-session] ERROR: An error occurred (AccessDeniedException) when calling the GetInventory operation: User: arn:aws:iam::123456789012:user/someone is not authorized to perform: ssm:GetInventory on resource: arn:aws:ssm:ap-southeast-2:123456789012:*
    • Your credentials profile doesn’t have SSM permissions.
  • [ssm-session] WARNING: Could not resolve Instance ID for 'instance123'
    • The instance is not registered in SSM Inventory. Perhaps it doesn’t have the agent running, or has incorrect IAM Policy, insufficient network access, etc. See above.

Enjoy and report any problems 🙂