Gyro Containers: connect an environment to a private network (VPC)

1. How it works

• The environment gets a VPC source range in the subnet you choose: a fixed block of 16 addresses (/28). Connections from your containers to VPC servers come from this range.
• The range never changes: it stays the same when a node is renewed, scaled or the plan changes. Allow it once in your server firewall.
• The first address of the range is the VPC endpoint. When you "publish" a service, VPC servers reach it at endpoint:port. The endpoint is not reachable from the internet.
• The connection and VPC traffic are free; no VPC gateway (NAT) is needed. Containers keep reaching the internet from the nodes' public addresses.
• Your services are not redeployed; the connection is ready in about a minute.

2. From the panel

1. In your container service open Management and the Private network (VPC) tool.
2. Pick the VPC and the Subnet. If you have no VPC yet, create one in Gyro Console > Private networks (VPC).
3. With Add service, choose the services VPC servers should reach and give each a VPC port (e.g. api → 8080). If you only need outgoing connections, you do not have to add any.
4. Click Attach to VPC. The state goes Attaching → Attached; the VPC source range and VPC endpoint appear.
5. Allow the source range in your VPC server's firewall. For PostgreSQL, add host all all 10.10.1.16/28 scram-sha-256 to pg_hba.conf.
6. From the container, connect to the VPC server with its private IP: DATABASE_URL=postgres://app:[email protected]:5432/gyroproje.

To change the published services later, edit the list and click Save; the source range and endpoint stay. Detach releases the block: a new attachment may get a different range.

In Gyro Console the VPC detail page lists every attached environment with its source range and endpoint under Attached container environments.

3. With the CLI, API, Terraform and AI assistants

gyro vpc list                                            # VPC and subnet ids
gyro container vpc attach 12345 --vpc p0ab12cd --subnet sb34ef56 --expose api:8080 --wait
gyro container vpc get 12345                             # source_range, endpoint_ip, published services
gyro container vpc expose 12345 --expose api:8080 --expose web:80   # replaces the list (--clear = none)
gyro container vpc detach 12345 --wait

resource "gyro_container_vpc_attachment" "app" {
  environment_id = gyro_container_environment.gyro_proje.id
  vpc_id         = gyro_vpc.production.id
  subnet_id      = gyro_vpc.production.default_subnet_id
  expose {
    service = "api"
    port    = 8080
  }
}

output "source_range" { value = gyro_container_vpc_attachment.app.source_range }

API: PUT /cloud/containers/{id}/vpc with {"vpc_id": "...", "subnet_id": "...", "expose": [{"service": "api", "port": 8080}]}; state GET /cloud/containers/{id}/vpc (state: attaching → ready); the published list with PATCH, detach with DELETE and body {"confirm": true}. Gyro MCP tools: container_vpc_get, container_vpc_attach, container_vpc_expose, container_vpc_detach. Details: developer docs.

4. Reaching a service from a VPC server

With endpoint 10.10.1.16 and the api service published on port 8080, from a VPC server:

curl http://10.10.1.16:8080/health

The request goes to the service's internal address (api.<environment-namespace>.svc.cluster.local:80) and is spread over its replicas. When a node is replaced the endpoint moves to another node by itself.

5. Security

• The VPC source range belongs only to your environment; no other customer's environment can use the block. Still, allow only this range and the needed port in your server firewall.
• The endpoint is reachable only from inside the VPC; to publish a service on the internet use the service's own HTTPS address, not a gateway port forward.
• Port forwards on the VPC gateway can be limited with a Source IPs list (VPC gateway).

6. FAQ