For developers working on AWS EC2 instances, secure SSH access is essential. Traditionally, this involved managing SSH keys and open ports, which can increase security risks. Instead, using AWS Systems Manager (SSM) with an SSH Proxy Command enables secure, private access to instances. Coupling this with Granted simplifies role management and session handling.

This guide will cover how to set up SSH to EC2 instances via SSM, use Granted for role management, and integrate everything with Visual Studio Code (VS Code) for remote development.

What You’ll Need

  • AWS CLI: To interact with AWS and enable SSM.
  • SSM Agent: Installed on the target EC2 instance (usually pre-installed on Amazon Linux and Ubuntu images).
  • IAM Role with SSM Permissions: Attach required policies to the EC2 instance’s IAM role.
  • Granted CLI: To streamline AWS credential management and multi-profile support.
  • Visual Studio Code: With the Remote - SSH extension installed.

Step 1: Enable SSM on Your EC2 Instances

Ensure that your EC2 instance has:

  1. The SSM Agent installed and running.

  2. An IAM role attached with permissions like AmazonSSMManagedInstanceCore.

  3. Your SSH public key added to the instance. You can do this when launching the instance by selecting an existing key pair or by manually adding your public key to the ~/.ssh/authorized_keys file of the instance’s default user.

    To add your public key manually, connect to the instance using SSM or another method and run:

    echo "your-public-key-content" >> ~/.ssh/authorized_keys

    Replace your-public-key-content with your actual public key (e.g., from ~/.ssh/id_rsa.pub).

Step 2: Set Up the SSH Proxy Command

To configure SSH to use SSM as a proxy, you need to edit your SSH configuration file (~/.ssh/config). Here’s how to do it:

  1. Open the terminal.

  2. Use a text editor to open the SSH configuration file:

    vi ~/.ssh/config

  3. Add the following entry to enable the SSM Proxy Command:

    Host i-* mi-*
    User ec2-user
    ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

    Replace ec2-user with the appropriate username for your instance if needed.

  4. Save and exit the text editor.

Step 3: Use Granted for Secure, Role-Based Access

  1. Install Granted if you haven’t already:

    brew tap common-fate/granted
brew install granted

  2. Configure AWS CLI Profiles in your ~/.aws/config file for different roles or accounts.

  3. Assume Roles with Granted: Use the command below to assume a specific profile:

    assume <profile_name>

    This command will set the appropriate environment variables for the assumed profile.

  4. Access Your EC2 Instance: To SSH into your instance, run:

    ssh i-0123456789abcdef0

    This uses the SSM Proxy Command to connect securely.

Step 4: Open VS Code from the Command Line

Since the SSH target for VS Code is already configured, you can connect directly from the terminal. Use the following command:

code --remote ssh-remote+i-0123456789abcdef0

This command launches VS Code and connects directly to the specified EC2 instance using the SSH configuration.

Start Coding

Once connected, you can edit files, open folders, and run commands directly on the remote EC2 instance from within VS Code.

Benefits of Using SSM and Granted with VS Code

  • Security: Eliminates the need for open ports on instances; access is managed through AWS IAM roles and SSM.
  • Convenience: Quickly switch between roles and accounts using Granted.
  • Remote Development: Work directly on EC2 instances within VS Code using SSH.
  • Audibility: AWS CloudTrail logs SSM session activity for auditing.

Troubleshooting Tips

  1. IAM Permissions: Ensure the user and instance roles have the necessary SSM permissions.
  2. SSH Public Key Issues: If you cannot connect, verify that your public key is correctly added to the ~/.ssh/authorized_keys file on the instance.
  3. Granted Session Expiry: If your session expires, re-run assume <profile_name> to refresh credentials.
  4. SSH Config Issues: Double-check your ~/.ssh/config file to ensure the Proxy Command is correctly set up.

Wrapping Up

Using SSH with SSM and Granted in conjunction with VS Code’s command-line capabilities provides a secure and efficient method for accessing AWS EC2 instances. This approach minimizes security risks and streamlines the development workflow, allowing developers to work directly on remote instances with ease.