How do I troubleshoot issues when I use EC2 Connect to connect to my EC2 instance?

5 minute read

I want to troubleshoot issues when I use Amazon Elastic Compute Cloud (Amazon EC2) Instance Connect to connect to my EC2 Linux instance.

Short description

The following are common reasons why you might receive an error when you use EC2 Instance Connect to connect to your instance:

EC2 Instance Connect doesn't support the operating system (OS) distribution.
The EC2 Instance Connect package isn't installed on the instance.
There are missing or incorrect AWS Identity and Access Management (IAM) policies or permissions.
Security groups that are associated with the instance don't list EC2 Instance Connect service IP addresses.
The network access or configuration is incorrect.

To determine the cause of the connection failure, you can use the AWSSupport-TroubleshootEC2InstanceConnect AWS Systems Manager automation runbook. For information about automation workflows, see AWS Support Automation Workflows (SAW) and Setting up Automation.

You can also manually troubleshoot your EC2 instance.

Resolution

Prerequisite: If your instance doesn't have a public IP address, then you must establish private network connectivity to your virtual private cloud (VPC). To establish private network connectivity to your VPC, use AWS Direct Connect, AWS Site-to-Site VPN, or VPC peering. If your instance doesn't have a public IPv4 address and your VPC doesn't have a private network connectivity configuration, then use EC2 Instance Connect Endpoint.

Note: If you turned on the EC2 serial console for Linux instances, then use the serial console to troubleshoot Nitro-based instance types. If you can't reach your instance and you didn't configure access to the serial console, then see Configure access to the EC2 serial console.

Use the runbook to troubleshoot your EC2 instance

Before you start the AWSSupport-TroubleshootEC2InstanceConnect runbook, make sure that your IAM user or role has the required permissions. For more information, see the Required IAM permissions section of AWSSupport-TroubleshootEC2InstanceConnect.

To run the runbook, complete the following steps:

Open the Systems Manager console.
In the navigation pane, choose Shared Resources, and then choose Documents.
Choose Automation documents.
In the search field, enter AWSSupport-TroubleshootEC2InstanceConnect, and then select the document.
Choose Execute automation.
Enter the following values for the input parameters:
For InstanceId, enter the ID of the instance that you can't connect to.
(Optional) For AutomationAssumeRole, enter ARN of the IAM role that allows Systems Manager Automation to perform the actions on your behalf. If you don't specify a role, then Systems Manager Automation uses the permissions of the user that runs the runbook.
For Username, enter the username that you use to connect to the instance. This parameter determines whether IAM access is granted for the user.
For EC2InstanceConnectRoleOrUser, enter the ARN of the IAM identity that's used for EC2 Instance Connect to push keys to the instance.
(Optional) For SSHPort, enter the SSH port that's configured on the instance. The default value is 22, and the port number must be between 1-65535.
(Optional) For SourceNetworkType, enter the network type that you use to connect to the instance.
(Optional) For SourceIpCIDR, enter the Classless Inter-Domain Routing (CIDR) range that includes the IP address of the device you use to connect to EC2 Instance Connect. If this field is empty, then the runbook can't determine whether the instance's security group and network access control list (ACL) rules allow SSH traffic.
Choose Execute.
Review the detailed results in the Outputs section.

Manually troubleshoot your EC2 instance

To troubleshoot issues when you connect to your EC2 instance, confirm the following configurations:

EC2 Instance Connect supports your instance's Linux distribution.
You installed the EC2 Instance Connect package on your supported instance.
The IAM user that wants to use EC2 Instance Connect has permission to push the public key to the instance.
The instance's security group rules list the EC2 Instance Connect IP addresses.
You have network access to your instance.

Use browser-based SSH connections

Browser-based SSH connections require that your instance's security group inbound rules allow EC2 Instance Connect access to SSH on TCP port 22.

EC2 Instance Connect uses specific IP address ranges for browser-based SSH connections to your instance. The AWS IP address ranges differ between AWS Regions. To find the IP address range for EC2 Instance Connect in a specific Region, run the following commands.

Note: In the following commands, replace us-east-1 with the Region that your instance is in. Be sure your instance is in a Region that EC2 Instance Connect supports.

Windows

Use Windows PowerShell to run the following command:

PS C:\> Get-AWSPublicIpAddressRange -Region us-east-1 -ServiceKey EC2_INSTANCE_CONNECT | select IpPrefix

Linux

Use curl and jq to run the following command:

$ curl -s https://ip-ranges.amazonaws.com/ip-ranges.json | jq -r '.prefixes[] | select(.region=="us-east-1") | select(.service=="EC2_INSTANCE_CONNECT") | .ip_prefix'

Update your security group inbound rules to allow TCP port 22 access from the IP address range that the previous commands return.

Use EC2 Instance Connect CLI connection

Update your security group inbound rules to allow TCP port 22 access from your IP address.