Skip to content

docs: add port forwarding example #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+52 −0
Open

docs: add port forwarding example #61

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db30a45
docs: add port forwarding example
westonplatter Oct 31, 2025
4456f96
fix: update ref env var
westonplatter Nov 4, 2025
4dada07
Merge branch 'main' into feat/docs-add-port-fowarding-example
westonplatter Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ module "subnets" {

### Connecting to your new SSM Agent

Prereqs:

- Your IAM users/role needs: `ssm:StartSession`, `ec2:DescribeInstances`

```bash
INSTANCE_ID=$(aws autoscaling describe-auto-scaling-instances | jq --raw-output ".AutoScalingInstances | .[0] | .InstanceId")
aws ssm start-session --target $INSTANCE_ID
Expand All @@ -77,6 +81,54 @@ OR

Use [the awesome `gossm` project](https://github.com/gjbae1212/gossm).

### Set up port forwarding through your SSM Agent

For example, set up port forwarding on `localhost` to connect to an RDS Postgres instance on private subnets that is not publicly accessible.

Prereqs:

- Your IAM user/role needs the following permissions: `ssm:StartSession`, `ec2:DescribeInstances`, `rds:DescribeDBInstances`
- Ensure the network architecture and Security Group permissions allow inbound traffic from the SSM Agent EC2 host.

```bash
REGION=us-east-1
Copy link

@coderabbitai coderabbitai bot Oct 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix variable name mismatch in the port-forwarding script.

Line 94 sets REGION=us-east-1, but lines 104, 110, and 117 reference the undefined variable ${AWS_REGION}, which will result in malformed AWS CLI commands.

Apply this diff to fix the variable reference:

 REGION=us-east-1
 # Partial match for RDS instance name (e.g., "polygon" matches "acme-prod-polygon-data")
 DB_INSTANCE_SUBSTRING="polygon"
 LOCAL_PORT=15432
 
 # 1) Find the running SSM gateway instance ID by tag
 INSTANCE_ID="$(
   aws ec2 describe-instances \
   --filters "Name=tag:Name,Values=*ssm*" "Name=instance-state-name,Values=running" \
   --query 'Reservations[*].Instances[*].InstanceId' \
-  --region ${AWS_REGION} \
+  --region ${REGION} \
   --output text)"
 
 # 2) Find the RDS instance endpoint
 RDS_ENDPOINT="$(
 	aws rds describe-db-instances \
-  --region ${AWS_REGION} \
+  --region ${REGION} \
   --query "DBInstances[?contains(DBInstanceIdentifier, '${DB_INSTANCE_SUBSTRING}')].Endpoint.Address | [0]" \
   --output text)"
 
 # 3) Dynamically get the RDS port
 RDS_PORT="$(
 	aws rds describe-db-instances \
-  --region ${AWS_REGION} \
+  --region ${REGION} \
   --query "DBInstances[?contains(DBInstanceIdentifier, '${DB_INSTANCE_SUBSTRING}')].Endpoint.Port | [0]" \
   --output text)"

Also applies to: 104-104, 110-110, 117-117

🤖 Prompt for AI Agents 
In README.md around lines 94, 104, 110 and 117, the script defines
REGION=us-east-1 but later references the undefined variable ${AWS_REGION};
update the references at lines 104, 110 and 117 to use ${REGION} (or change the
definition to AWS_REGION=us-east-1 if you prefer that name) so the AWS CLI
commands use the defined variable consistently; ensure all occurrences in those
lines are corrected to the same variable name.

Copy link
Member Author

@westonplatter westonplatter Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed the env var. I'm using AWS_REGION in all places

Copy link

@coderabbitai coderabbitai bot Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@westonplatter, thank you for fixing the variable naming! Using AWS_REGION consistently throughout the script will ensure the AWS CLI commands execute correctly. This makes the script more robust and prevents the errors that would have occurred with undefined variables.

🐰✨
((
( -.-)
o_(")(")

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

# Partial match for RDS instance name (e.g., "polygon" matches "acme-prod-polygon-data")
DB_INSTANCE_SUBSTRING="polygon"
LOCAL_PORT=15432

# 1) Find the running SSM gateway instance ID by tag
INSTANCE_ID="$(
aws ec2 describe-instances \
--filters "Name=tag:Name,Values=*ssm*" "Name=instance-state-name,Values=running" \
--query 'Reservations[*].Instances[*].InstanceId' \
--region ${AWS_REGION} \
--output text)"

# 2) Find the RDS instance endpoint
RDS_ENDPOINT="$(
aws rds describe-db-instances \
--region ${AWS_REGION} \
--query "DBInstances[?contains(DBInstanceIdentifier, '${DB_INSTANCE_SUBSTRING}')].Endpoint.Address | [0]" \
--output text)"

# 3) Dynamically get the RDS port
RDS_PORT="$(
aws rds describe-db-instances \
--region ${AWS_REGION} \
--query "DBInstances[?contains(DBInstanceIdentifier, '${DB_INSTANCE_SUBSTRING}')].Endpoint.Port | [0]" \
--output text)"

echo "EC2 Instance ID: $INSTANCE_ID"
echo "RDS Endpoint: $RDS_ENDPOINT"
echo "Setting up port forwarding (ec2) ${RDS_PORT} -> (localhost) ${LOCAL_PORT}"

# 4) Start the port forwarding session
aws ssm start-session \
--target $INSTANCE_ID \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters "{\"host\":[\"$RDS_ENDPOINT\"],\"portNumber\":[\"$RDS_PORT\"],\"localPortNumber\":[\"$LOCAL_PORT\"]}"
```

<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
Expand Down