AWS EC2 / ECS With SSM (Session Manager)

The AWS Systems Manager Agent (SSM Agent) is Amazon software that runs on compute instances (e.g. EC2 or ECS clusters) and enables getting a shell without needing to manage keys or shared credentials.

The Border0 connector integrates natively with AWS SSM, allowing the Border0 connector to use SSM-target EC2 instances or ECS container clusters as upstream targets.

🚧

Heads-up!

The following documentation assumes that you already have an AWS EC2 instance successfully associated with AWS SSM.

If you need help setting up your EC2 instance for access via SSM, see the additional resources at the bottom of this page.

Creating a new Border0 SSH socket

To make an EC2 Instance available over SSH and use SSM as the upstream protocol, follow the following steps

• In the Sockets page, click on new SSH socket
• Set a name and, optionally, a description
• From Upstream connection type select AWS SSM
• For the example we will leave AWS Authentication Strategy as default but AWS Static credentials or AWS Profile can be supplied.
• Our SSM Target Type is EC2 but we can also select ECS to make your containers avalable.
• The instance ID is our example AWS EC2 instance i-06335d997221f33d4
• We need to specify the region for our target EC2 instance, the example is using us-east-1
• Lastly, we select our target connector
• Final step is to click create socket at the bottom of the page

🚧

Heads-up!

The Border0 Connector will use your local system's AWS Standardized Credential Providers Chain to determine how to authenticate against AWS in order to connect to the SSM target.

AWS Credentials for Border0 Connector

The instance running the Border0 connector must have the appropriate AWS IAM permissions in order to connect to the SSM target and expose it over the Border0 Service, as well as a few read-only operations against ECS.

Your AWS credentials will require at a minimum the following AWS policy:

Replace AWS_REGION, AWS_ACCOUNT_ID, and EC2_INSTANCE_ID with the AWS region where your SSM target instance is running, AWS account ID, and EC2 instance ID of the SSM target instance respectively. All of these can also be replaced with a wildcard *.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": [
                "arn:aws:ec2:${AWS_REGION}:${AWS_ACCOUNT_ID}:instance/${EC2_INSTANCE_ID}",
                "arn:aws:ssm:${AWS_REGION}:${AWS_ACCOUNT_ID}:document/AWS-StartSSHSession"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:TerminateSession"
            ],
            "Resource": [
                "arn:aws:ssm:${AWS_REGION}:${AWS_ACCOUNT_ID}:session/*"
            ],
            "Condition": {
                "StringLike": {
                    "ssm:resourceTag/aws:ssmmessages:target-id": [
                        "${EC2_INSTANCE_ID}"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DescribeClusters",
                "ecs:DescribeContainerInstances",
                "ecs:DescribeServices",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeTasks",
              	"ecs:ListClusters",
              	"ecs:ListContainerInstances",
              	"ecs:ListServices",
              	"ecs:ListTaskDefinitionFamilies",
              	"ecs:ListTaskDefinitions",
              	"ecs:ListTasks"
            ],
            "Resource": [
                "arn:aws:ecs:${AWS_REGION}:${AWS_ACCOUNT_ID}:*"
            ]
        }
    ]
}

Click below to see a fully populated example. This policy allows access to Start and Terminate SSM sessions against any EC2 instance in any region and account, as well as various read-only operations against ECS (required to connect to ECS targets).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:instance/*",
                "arn:aws:ssm:*:*:document/AWS-StartSSHSession"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:TerminateSession"
            ],
            "Resource": [
                "arn:aws:ssm:*:*:session/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
								"ecs:DescribeClusters",
								"ecs:DescribeContainerInstances",
              	"ecs:DescribeServices",
              	"ecs:DescribeTaskDefinition",
              	"ecs:DescribeTasks",
              	"ecs:ListClusters",
              	"ecs:ListContainerInstances",
              	"ecs:ListServices",
              	"ecs:ListTaskDefinitionFamilies",
              	"ecs:ListTaskDefinitions",
              	"ecs:ListTasks"
            ],
            "Resource": [
                "arn:aws:ecs:*:*:*"
            ]
        }
    ]
}

Help Getting EC2 + SSM Set Up

Below we briefly go over the requirements for an EC2 instance to be associated with AWS SSM. For comprehensive documentation on how to set-up an EC2 Instance with the SSM Agent, refer to the official AWS documentation "Session Manager Getting Started".

We recommend watching the video below, for a step by step walkthrough.

There are three independent requirements for an EC2 instance to be associated with AWS SSM.

1) The AWS SSM Agent must be installed on the instance

Some EC2 Amazon Machine Images (AMIs) come out-of-the-box with the AWS SSM Agent pre-installed. You may want to choose one of those AMIs if you wish to skip the installation process. The list of AMIs with the Agent pre-installed can be found here: "AMIs with SSM Agent Pre-Instaled". TL;DR: latest Amazon Linux and Ubuntu come with the Agent pre-installed.

Otherwise to install the SSM Agent yourself, you may want to refer to the official AWS documentation here: "SSM Agent Manual Installation".

2) The AWS SSM Agent must be running on the instance

Even if an AMI comes with the SSM Agent pre-installed, the boot process on the AMI might not be configured to start the SSM agent. For instructions on how to verify the status and start or restart the agent, refer to the official AWS documentation here: "SSM Agent Status and Restart".

3) The AWS EC2 instance must have certain required IAM permissions for AWS SSM

Even if your EC2 instance has the SSM Agent installed and running, the IAM Role of the EC2 instance must have certain permissions in order for the SSM Agent to successfully register the instance with the SSM service.

The easiest way to ensure that the EC2 instance's IAM Role has such permissions is to add the AWS-managed IAM policy AmazonSSMManagedEC2InstanceDefaultPolicy to the instance's IAM Role.

For more help with instance permissions, you may refer to the official AWS documentation here: "Session Manager Permissions"

Troubleshooting
Should you see any issues with your new socket, it's typically because it can't connect to the upstream SSH server. Common use-cases are, connector not being able to communicate with the provided hostname and port number, or, invalid credentials. To troubleshoot that take a look at the connector logs as described here