Set up EC2 Instance Connect
To use EC2 Instance Connect to connect to an instance, you need to configure every instance that will support 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.
Tasks to set up Instance Connect
For more information about setting up EC2 Instance Connect, see Securing your bastion hosts with Amazon EC2 Instance Connect
Limitations
-
The following Linux distributions are supported:
-
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 General prerequisites for connecting to your instance.
-
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 AWS CLI on your local computer.
To configure the IAM permissions, you must use the AWS CLI. For more information about installing the AWS CLI, see Installing the AWS CLI in the AWS Command Line Interface User Guide.
-
[Ubuntu] Install the AWS CLI on your instance.
To install EC2 Instance Connect on an Ubuntu instance, you must use the AWS CLI on the instance. For more information about installing the AWS CLI, see Installing the AWS CLI in the AWS 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. For more information, see Public IPv4 addresses and external DNS hostnames.
-
If your users will access your instance via the instance's private IP address, then you must establish private network connectivity to your VPC, such as by using AWS Direct Connect, AWS 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 browser-based client) We recommend that your instance allows inbound SSH traffic from the recommended IP block published for the service
. Use the EC2_INSTANCE_CONNECT
filter for theservice
parameter to get the IP address ranges in the EC2 Instance Connect subset. For more information, see AWS IP address ranges in the Amazon Web Services General Reference.
Task 2: (Conditional) Install EC2 Instance Connect on an instance
Amazon Linux 2 2.0.20190618 or later and Ubuntu 20.04 or later are preconfigured with EC2 Instance Connect. If you launched your instance using one of these AMIs, you can skip this task. For other supported Linux distributions, 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
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 (browser-based client) 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 an IAM user using the AWS CLI. The same policy could be applied to other IAM principals, such as IAM roles. For instructions that use the AWS 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 (AWS 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:ec2:
region
:account-id
:instance/i-1234567890abcdef0
", "arn:aws: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 AWS resources. For example, the following policy allows an IAM 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 AWS resources, see Controlling access to AWS resources in the IAM User Guide.{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"ec2-instance-connect:SendSSHPublicKey", "Resource": "arn:aws: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 IAM user. For the
--user-name
parameter, specify the friendly name (not the ARN) of the IAM user.$
aws iam attach-user-policy --policy-arn arn:aws:iam::
account-id
:policy/my-policy
--user-nameIAM-friendly-name