How do I troubleshoot errors that I receive when I use EC2 Instance Connect to connect to my EC2 instance?

Short description

When you try to use EC2 Instance Connect to connect to your instance, you might receive an error for the following reasons:

• EC2 Instance Connect doesn't support the operating system (OS) distribution.
• You didn't install the EC2 Instance Connect package to 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 troubleshoot, use the AWSSupport-TroubleshootEC2InstanceConnect for AWS Systems Manager automation runbook. Or, you can manually troubleshoot your EC2 instance.

Resolution

Prerequisite: If your instance doesn't have a public IP address, then 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 AWSSupport-TroubleshootEC2InstanceConnect runbook

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:

1. Open the Systems Manager console.
2. In the navigation pane, choose Shared Resources, and then choose Documents.
3. Choose Automation documents.
4. In the search field, enter AWSSupport-TroubleshootEC2InstanceConnect, and then select the document.
5. Choose Execute automation.
6. 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 the Amazon Resource Name (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 you use for EC2 Instance Connect to push keys to the instance.
   (Optional) For SSHPort, enter the SSH port that's configured on the instance. The port number must be between 1-65535, and the default value is 22.
   (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.
7. Choose Execute.
8. Review the detailed results in the Outputs section.

For information about automation workflows, see AWS Support Automation Workflows (SAW) and Setting up Automation.

Manually troubleshoot your EC2 instance

To manually find your issues when you try to connect to your EC2 instance, confirm the following configurations:

• Verify that EC2 Instance Connect supports your instance's Linux distribution.
• Confirm that you installed the EC2 Instance Connect package on your supported instance.
• Verify that the IAM user that you want to use EC2 Instance Connect has the permissions to push the public key to the instance.
• Check that the instance's security group rules list the EC2 Instance Connect IP addresses.
• Confirm that you have network access to your instance.

To manually troubleshoot your EC2 instance, use a browser based SSH connection or an EC2 Instance Connect CLI connection.

Browser based SSH connection

Browser based SSH connections require that your instance's security group inbound rules give 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 command for your OS.

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

Windows

Use 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.

EC2 Instance Connect CLI connection

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

Related information

Run an automated operation powered by Systems Manager Automation

Connect to your Linux instance using EC2 Instance Connect

How do I connect to my Amazon EC2 instance if I lose my SSH key pair after the initial instance launch?

How do I resolve SSH connection issues to my Amazon EC2 Linux instance?