VPC Isolation

Simfra simulates AWS VPC network isolation using Docker bridge networks. Each VPC gets its own isolated Docker network, and whether a service is reachable from the host depends on its public/private classification - the same way AWS controls internet accessibility.

Prerequisites

  • SIMFRA_DOCKER=true
  • Docker running on the host
  • A VPC created (via Terraform, AWS CLI, or SIMFRA_BOOTSTRAP=standard)

Enabling VPC Isolation

VPC isolation is controlled by SIMFRA_VPC_ISOLATION. It defaults to true when Docker is enabled:

export SIMFRA_DOCKER=true
# SIMFRA_VPC_ISOLATION=true is implied

To disable isolation and publish all container ports to the host (useful for simple setups):

export SIMFRA_VPC_ISOLATION=false

How It Works

When VPC isolation is enabled:

  1. VPC creation creates a Docker bridge network named simfra-vpc-{accountID}-{region}-{vpcID}.
  2. Public resources (internet-facing load balancers, publicly accessible databases) publish ports to the host (127.0.0.1:PORT) AND attach to the VPC network.
  3. Private resources (internal load balancers, private databases, ElastiCache clusters) attach to the VPC network only - no host ports are published.
  4. The Docker host represents the public internet. If a resource is not reachable from the host, it is not "internet-accessible."

Service Classification

Each Docker-backed service follows the same public/private rules as AWS:

Service Public When Private When
ELBv2 Scheme == "internet-facing" Scheme == "internal"
RDS PubliclyAccessible == true Default (false)
ElastiCache Never Always
CloudFront Always Never
API Gateway V2 Always Never
API Gateway V1 Non-PRIVATE endpoint types EndpointType == "PRIVATE"
DSQL Always Never
Amazon MQ PubliclyAccessible == true Default
MSK (Kafka) PublicAccessEnabled == true Default (false)
Redshift PubliclyAccessible == true Default (false)
ECS AssignPublicIp == "ENABLED" Default ("DISABLED")
EFS Never Always

What This Means for Workloads

Containers in the same VPC can communicate directly

All containers attached to the same VPC Docker network can reach each other by their Docker network IPs. An ECS task in a VPC can connect to a private RDS instance or ElastiCache cluster in the same VPC, just like in AWS.

Public services are accessible from the host AND containers

Internet-facing resources publish a port to 127.0.0.1 (the host). They are reachable both from your host machine and from other containers on the same VPC network. The assigned host port appears in API responses (e.g., the ALB DNS name, the RDS endpoint).

Private services are only accessible from containers on the same VPC network

Private resources do not publish any ports to the host. You cannot reach them directly from your machine using localhost. To access private resources from your host, use port forwarding, the embedded browser, or CloudShell.

Private services do not consume host ports

Because private resources have no host port mapping, they do not consume ports from the configured port ranges. Only public resources use port range allocations.

Disabling VPC Isolation

When SIMFRA_VPC_ISOLATION=false, all containers publish ports to the host regardless of their public/private classification. VPC Docker networks are still created, but every container gets a host port. This simplifies access at the cost of not simulating network isolation.

export SIMFRA_DOCKER=true
export SIMFRA_VPC_ISOLATION=false

Next Steps