Set up EC2 Instance Connect
To use EC2 Instance Connect to connect to an instance, you need to configure every instance that will support a connection using Instance Connect (this is a one-time requirement for each instance), and you need to grant permission to every IAM principal that will use Instance Connect. After completing the following setup tasks, you can connect to your instance using EC2 Instance Connect.
Tasks to set up EC2 Instance Connect
For more information about setting up EC2 Instance Connect, see Securing your bastion hosts with Amazon EC2 Instance Connect
Limitations
-
You can install EC2 Instance Connect on the following supported Linux distributions:
Amazon Linux 2 (any version)
Ubuntu 16.04 or later
-
If you configured the
AuthorizedKeysCommand
andAuthorizedKeysCommandUser
settings for SSH authentication, the EC2 Instance Connect installation will not update them. As a result, you cannot use Instance Connect.
Prerequisites for installing EC2 Instance Connect
-
Verify the general prerequisites for connecting to your instance using SSH.
For more information, see Set up to connect to your instance.
-
Get the ID of the instance.
You can get the ID of your instance using the Amazon EC2 console (from the Instance ID column). If you prefer, you can use the describe-instances (Amazon CLI) or Get-EC2Instance (Amazon Tools for Windows PowerShell) command.
-
Install an SSH client on your local computer.
Your local computer most likely has an SSH client installed by default. You can check for an SSH client by typing ssh at the command line. If your local computer doesn't recognize the command, you can install an SSH client. For information about installing an SSH client on Linux or macOS X, see http://www.openssh.com
. For information about installing an SSH client on Windows 10, see OpenSSH in Windows . -
Install the Amazon CLI on your local computer.
To configure the IAM permissions, you must use the Amazon CLI. For more information about installing the Amazon CLI, see Installing the Amazon CLI in the Amazon Command Line Interface User Guide.
-
(Ubuntu) Install the Amazon CLI on your instance.
To install EC2 Instance Connect on an Ubuntu instance, you must use the Amazon CLI on the instance. For more information about installing the Amazon CLI, see Installing the Amazon CLI in the Amazon Command Line Interface User Guide.
Task 1: Configure network access to an instance
You must configure the following network access so that your users can connect to your instance using EC2 Instance Connect:
-
If your users will access your instance over the internet, then your instance must have a public IP address and be in a public subnet. For more information, see Enable internet access in the Amazon VPC User Guide.
-
If your users will access your instance through the instance's private IP address, then you must establish private network connectivity to your VPC, such as by using Amazon Direct Connect, Amazon Site-to-Site VPN, or VPC peering, so that your users can reach the instance's private IP address.
-
Ensure that the security group associated with your instance allows inbound SSH traffic on port 22 from your IP address or from your network. The default security group for the VPC does not allow incoming SSH traffic by default. The security group created by the launch wizard allows incoming SSH traffic by default. For more information, see Authorize inbound traffic for your Linux instances.
-
(Amazon EC2 console) Ensure that the security group associated with your instance allows inbound SSH traffic from the IP address range for this service. To identify the address range, download the JSON file provided by Amazon and filter for the subset for EC2 Instance Connect, using
EC2_INSTANCE_CONNECT
as the service value. For more information about downloading the JSON file and filtering by service, see Amazon IP address ranges in the Amazon Web Services General Reference.
Task 2: (Conditional) Install EC2 Instance Connect on an instance
You can skip this task if you used one of the following AMIs to launch your instance because they come preinstalled with EC2 Instance Connect:
-
Amazon Linux 2 2.0.20190618 or later
-
Ubuntu 20.04 or later
For earlier versions of these AMIs, you must install Instance Connect on every instance that will support connecting using Instance Connect.
Installing Instance Connect configures the SSH daemon on the instance. The procedure for installing Instance Connect is different for instances launched using Amazon Linux 2 and Ubuntu.
For more information about the EC2 Instance Connect package, see aws/aws-ec2-instance-connect-config
Task 3: (Optional) Install the EC2 Instance Connect CLI on your computer
The EC2 Instance Connect CLI provides a simplified experience to connect to EC2 instances
through a single command, mssh
. For more information, see
Connect using the
EC2 Instance Connect CLI.instance_id
There is no need to install the EC2 Instance Connect CLI if users will only use the Amazon EC2 console or an SSH client to connect to an instance.
To install the EC2 Instance Connect CLI package
Use pip
to install the ec2instanceconnectcli
package. For more information, see aws/aws-ec2-instance-connect-cli
$
pip install ec2instanceconnectcli
Task 4: Configure IAM permissions for EC2 Instance Connect
For your IAM principals to connect to an instance using EC2 Instance Connect, you must grant them permission to push the public key to the instance. You grant them the permission by creating an IAM policy and attaching the policy to the IAM principals that require the permission. For more information, see Actions, resources, and condition keys for Amazon EC2 Instance Connect.
The following instructions explain how to create the policy and attach it to a user using the Amazon CLI. The same policy could be applied to other IAM principals, such as IAM roles. For instructions that use the Amazon Web Services Management Console, see Creating IAM policies (console), Adding permissions by attaching policies directly to the user, and Creating IAM roles in the IAM User Guide.
To grant an IAM principal permission for EC2 Instance Connect (Amazon CLI)
-
Create a JSON policy document that includes the following:
-
The
ec2-instance-connect:SendSSHPublicKey
action. This grants an IAM principal permission to push the public key to an instance. Withec2-instance-connect:SendSSHPublicKey
, consider restricting access to specific EC2 instances. Otherwise, all IAM principals with this permission can connect to all EC2 instances. You can also restrict access by specifying resource ARNs or by using resource tags as condition keys. -
The
ec2:osuser
condition. This specifies the name of the OS user that can push the public key to an instance. Use the default user name for the AMI that you used to launch the instance. The default user name for Amazon Linux 2 isec2-user
, and for Ubuntu it'subuntu
. -
The
ec2:DescribeInstances
action. This is required when using the EC2 Instance Connect CLI because the wrapper calls this action. IAM principals might already have permission to call this action from another policy.
The following is an example policy document. You can omit the statement for the
ec2:DescribeInstances
action if your users will only use an SSH client to connect to your instances. You can replace the specified instances inResource
with the wildcard*
to grant users access to all EC2 instances using EC2 Instance Connect.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ec2-instance-connect:SendSSHPublicKey", "Resource": [ "arn:aws-cn:ec2:
region
:account-id
:instance/i-1234567890abcdef0
", "arn:aws-cn:ec2:region
:account-id
:instance/i-0598c7d356eba48d7
" ], "Condition": { "StringEquals": { "ec2:osuser": "ami-username
" } } }, { "Effect": "Allow", "Action": "ec2:DescribeInstances", "Resource": "*" } ] }The preceding policy allows access to specific instances, identified by their instance ID. Alternatively, you can use resource tags to control access to an instance. Attribute-based access control is an authorization strategy that defines permissions based on tags that can be attached to users and Amazon resources. For example, the following policy allows a user to access an instance only if that instance has a resource tag with key=
tag-key
and value=tag-value
. For more information about using tags to control access to your Amazon resources, see Controlling access to Amazon resources in the IAM User Guide.{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ec2-instance-connect:SendSSHPublicKey", "Resource": "arn:aws-cn:ec2:
region
:account-id
:instance/*
", "Condition":{ "StringEquals":{ "aws:ResourceTag/tag-key
":"tag-value
" } } }, { "Effect": "Allow", "Action": "ec2:DescribeInstances", "Resource": "*" } ] } -
-
Use the create-policy command to create a new managed policy, and specify the JSON document that you created to use as the content for the new policy.
$
aws iam create-policy --policy-name
my-policy
--policy-document file://JSON-file-name
-
Use the attach-user-policy command to attach the managed policy to the specified user. For the
--user-name
parameter, specify the friendly name (not the ARN) of the user.$
aws iam attach-user-policy --policy-arn arn:aws:iam::
account-id
:policy/my-policy
--user-nameIAM-friendly-name