How to Use AWS CLI SSM to Remotely Connect to Private Resources

Many people reading this will have experienced occasions when they need to connect to remote servers.  Maybe it’s a Windows “Remote Desktop Protocol” (RDP) instance to connect to your work computer, or perhaps it’s been a “Secure Shell” (SSH) connection to a “headless” Linux server.

In this article, we’ll go over how you might install and configure AWS SSM and connect to private resources in AWS (e.g. an EC2 or RDS instance in a private subnet) from an internet-connected location, such as a home or office.

The Evolution of Remote Server Access

In the past, admins have utilized bastion hosts or purpose-built appliances to provide remote users securable access to assets. These resources require their own management and upkeep and are by their very nature open to much of the Internet, providing an exposed surface for attackers to target.

In addition, RDP is not secure enough to expose to the Internet and configuring RD Gateway is expensive and requires significant upfront investment.

The Rise of AWS Systems Manager (SSM)

AWS Systems Manager (SSM) Session Manager in the management console provides versatile, secure, and auditable connectivity to EC2 instances in any account. Port forwarding is also allowed, further expanding on connectivity options.

In addition, SSM action history is fully auditable and action permissions are controlled by IAM.

Introducing the SSM Agent Plugin for AWS CLI

Back in 2018, AWS introduced the AWS SSM Session Manager plugin for the AWS CLI. Since then, the feature has been steadily improved and brings all that Session Manager goodness right to the terminal. 

The plugin is supported on Windows, macOS, and Linux. This CLI plugin is what we will be covering today.

When I first started looking at using the AWS SSM Session Manager plugin, I found that I had to pull information from multiple sources. Hopefully, by putting the pieces together with meaningful examples, your adoption of the tool will be easier. Links to the official documentation are included for those who want more information.

How to Install AWS CLI

1. Installation of the AWS CLI is very well documented, so I won’t rehash it here. Installation instructions will vary between operating systems, but you can always find the latest documentation in the “AWS CLI Getting Started”.

2. Once installed, you can check the version by using the command “aws --version”. Please verify that your AWS CLI profile is correctly configured and working. In addition, you may want to utilize a tool like “ awsume ” to improve efficiency while using AWS command-line tools.

3. Next, you’ll need the Session Manager plugin. You can access the installation instructions here.

Once the AWS CLI is installed and configured and the SSM agent plugin is installed, your workstation is properly configured to access an EC2 instance.

For the EC2 Instance:

1. First, ensure the EC2 instance has the necessary permissions attached to its instance profile. The quickstart guide here is a good starting point.

2. In addition, Session Manager has some prerequisites that must be satisfied prior to connecting.

3. According to the official documentation, the SSM agent will be pre-installed on the following images.

If you need to install the agent on your instance, the official instructions are here.

Here, we see details of a small EC2 instance created with only a private network connection:

1. Take note of the instance ID - it will be used to connect using the SSM agent plugin. If you are not using awsume (just standard aws cli), you’ll need to:

   aws ssm start-session --target i-01252901fedd3edcb --profile my-profile

2. Provided you are using the awsume utility, you can omit the profile flag:

   aws ssm start-session --target i-01252901fedd3edcb

   Once the connection is established, you will be logged in as “ssm-user” and presented with a classic “sh” shell:

   sh-4.2$

3. From here, it’s a simple matter of issuing standard *nix commands.  If you are going to be interacting with the shell for a moment, you may benefit by starting a “bash” shell by using the command “/bin/bash”.  This is, in a nutshell, the same behavior as the SSM Session Manager in the AWS Management Console.

Let’s take this one step further, and connect to the instance over ssh using the SSM agent.  To do so, you must first enable the functionality (instructions differ between operating systems).

Then, issue the ssh command to connect to the instance through the aws-ssm “proxy”:

This provides the additional security of SSH, the added convenience of user-specific context (shell, environment parameters, user rights, etc.), and powerful SSH capabilities such as port forwarding (“-L” command flag).

Practical Applications of SSM Agent Plugin

Local and remote port forwarding

Speaking of port forwarding, it’s possible to get that without the need for SSH. Useful for those Windows instances for which you need RDP access (they are in a private subnet isolated from the world, right?). When starting a session, add the “document-name” and “parameters” options to your aws ssm call, like this:

Another common scenario we have encountered recently is when there is the need to provide connectivity to a “development” PostgreSQL database which has been or is being migrated from on-premise to the cloud.

In our particular case, the database had been migrated to an Aurora cluster with PostgreSQL compatibility, and the cluster instances were located in an isolated subnet with no internet access.  The developers needed to run migration scripts and test queries against the development database cluster from their local machines. 

In the past, the developers would connect to a client VPN and run queries directly against the on-premise database server.

Utilizing SSM on a minimal EC2 instance spun up in a private subnet, we were able to simultaneously remove all SSH key management challenges while avoiding exposure of any cloud resource to the open internet. 

Once the EC2 instance was prepared for SSM and the security groups for the EC2 instance and Aurora instances were adjusted to allow connectivity, the following command allowed the developers to forward a local port on their local machine through the remote EC2 instance to the desired port (5432) on the database cluster endpoint.

Not only did we provide the developers with the connectivity they wanted, and removed administrative overhead and security risk by eliminating SSH keys, the developers also praised the removal of the client VPN as this simplified their workflow.

You can get more information on the official AWS blog post.

I hope this information helps give you a better understanding of the AWS SSM plugin for AWS CLI and how it can help in connecting to AWS resources in a more secure, manageable, and auditable way. 

Operations and Development both benefit from secure connectivity, and I think this is a tool that should be in every AWS professional’s toolkit.

Enhance Your Remote Server Access with StratusGrid's SSM Agent Plugin Expertise

Revolutionize your approach to remote server access with StratusGrid's expertise in the SSM Agent Plugin for AWS CLI. Embrace a new era of security, efficiency, and flexibility in connecting to your AWS resources. Whether you're managing EC2 instances, RDS databases, or any private AWS resource, our guidance ensures a seamless, secure, and auditable connection experience.

If you have any questions about your toolkit or would like to know more about the SSM plugin, reach out to us to speak with someone from our team. Unlock the full potential of the SSM Agent Plugin for your AWS environment.

BONUS: Download Your FinOps Guide to Effective Cloud Cost Optimization Here ⤵️