Accessing Private Services

Private resources (internal load balancers, private RDS instances, ElastiCache clusters, EFS mount targets) do not publish ports to the Docker host. They are only reachable from containers on the same VPC Docker network. There are four ways to access them from your host.

Prerequisites

  • SIMFRA_DOCKER=true
  • SIMFRA_VPC_ISOLATION=true (default when Docker is enabled)
  • At least one private resource created (internal ALB, private RDS instance, etc.)

Port Forwarding

Port forwarding creates a temporary host-accessible tunnel to a private resource. This is the recommended approach for database clients and CLI tools.

List available targets

curl http://localhost:4599/_simfra/port-forwards/targets

This returns all private resources that can be forwarded to, with their ARNs, ports, and service types.

Create a port forward

curl -X POST http://localhost:4599/_simfra/port-forwards \
  -H "Content-Type: application/json" \
  -d '{
    "targetArn": "arn:aws:rds:us-east-1:000000000000:db:mydb",
    "targetPort": 5432,
    "service": "rds",
    "resourceId": "mydb",
    "accountId": "000000000000",
    "region": "us-east-1"
  }'

The response includes the assigned local port:

{
  "id": "pf-1",
  "localPort": 11800,
  "targetArn": "arn:aws:rds:us-east-1:000000000000:db:mydb",
  "targetPort": 5432,
  "status": "active"
}

Connect through the forward

# PostgreSQL (private RDS)
psql -h localhost -p 11800 -U admin mydb

# MySQL (private RDS)
mysql -h localhost -P 11800 -u admin -p mydb

# Redis (ElastiCache)
redis-cli -h localhost -p 11801

# NFS (EFS)
sudo mount -t nfs -o port=11802 localhost:/ /mnt/efs

Clean up

curl -X DELETE http://localhost:4599/_simfra/port-forwards/pf-1

Port forwards are allocated from the SIMFRA_PORT_FORWARD_PORT_RANGE (default 11800-11899). Idle forwards are automatically cleaned up after SIMFRA_PORT_FORWARD_IDLE_TIMEOUT seconds (default 7200 / 2 hours).

Embedded Browser

The web console includes an embedded Chromium browser that runs inside Docker. It has Simfra's DNS and root CA pre-configured, so it can reach all private services without any host-side setup.

To use it:

  1. Open the Simfra web console at http://localhost:4599
  2. Navigate to the resource you want to access
  3. Click the globe icon to open the embedded browser
  4. Enter the resource's internal URL (e.g., http://internal-my-alb-123.elb.us-east-1.simfra.dev/)

This is the best option for browsing internal web UIs served by private load balancers or API Gateway endpoints.

CloudShell

CloudShell provides a terminal that runs inside Docker on the VPC network, with the AWS CLI pre-configured to use Simfra.

To use it:

  1. Open the Simfra web console at http://localhost:4599
  2. Click the terminal icon to open CloudShell
  3. Run AWS CLI commands or use standard tools (curl, psql, mysql, redis-cli) to reach private resources

CloudShell containers have DNS and CA trust pre-configured. They can resolve service DNS names and connect to private resources directly.

From Another Container

Any Docker container attached to the same VPC network can reach private resources directly by their Docker network IP or DNS name. This is how ECS tasks, Lambda functions, and other compute containers access private services - the same as in AWS.

If you are running your own application container and want it to reach Simfra private resources:

# Find the VPC Docker network name
docker network ls --filter "label=simfra.managed=true"

# Attach your container to the VPC network
docker network connect simfra-vpc-000000000000-us-east-1-vpc-abc123 my-app-container

Once attached, your container can connect to private endpoints using the Docker network IPs returned by Simfra's DNS.

Next Steps