Skip to content

Port Forwarding

How to access internal services (ClickHouse, Grafana, etc.) from your local machine using AWS SSM port forwarding.

Prerequisites

brew install --cask session-manager-plugin

Download and install from: SessionManagerPluginSetup.exe

Verify SSM Access

Check that you can see the EC2 instances:

aws ssm describe-instance-information --output table

ClickHouse (Production)

Forward the ClickHouse HTTP port to your local machine:

aws ssm start-session \
  --target i-0ffcdef60ae0df81e \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{
    "host": ["clickhouse.vault.prod.internal.cookiehub.net"],
    "portNumber": ["8123"],
    "localPortNumber": ["8123"]
  }'

Then access ClickHouse at http://localhost:8123.

Grafana (Production)

aws ssm start-session \
  --target i-054aac40f26525fe3 \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{
    "host": ["172.31.76.88"],
    "portNumber": ["3000"],
    "localPortNumber": ["3000"]
  }'

Then access Grafana at http://localhost:3000.

How It Works

SSM port forwarding creates an encrypted tunnel through the SSM agent running on an EC2 instance in the VPC. Traffic flows: your machine → SSM service → EC2 instance → target host. No SSH keys or open inbound ports required.

sequenceDiagram
    participant Local as Your Machine
    participant SSM as AWS SSM
    participant EC2 as EC2 Instance
    participant Target as Internal Service

    Local->>SSM: Start port forwarding session
    SSM->>EC2: Establish tunnel via SSM agent
    Local->>EC2: localhost:port → tunnel
    EC2->>Target: Forward to host:port
    Target-->>EC2: Response
    EC2-->>Local: Response via tunnel

Finding instance IDs

If the instance IDs above are outdated, find the current ones with:

aws ssm describe-instance-information \
  --query 'InstanceInformationList[*].[InstanceId,ComputerName]' \
  --output table