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

https://www.gyrohosting.com/en/knowledgebase/article/gyro-containers-private-network-vpc

- **What you will learn**: how to connect your container environment to your Gyro Cloud Istanbul private network (VPC), so that containers reach VPC servers (database, cache, internal APIs) over private IPs and VPC servers reach the services you choose at a private endpoint.
- **Time**: 5 minutes

## 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.

|  |  |
| --- | --- |
| Subnets per environment | One at a time (/26 or larger) |
| Published services | Up to 20, each port once |
| Reserved ports | 22, 2200, 6443, 9100, 9750, 10250-10256, 30000-32767, 51820-51821 |
| Price | None |
| Serverless environments | Coming soon |

## 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:password@10.10.1.10: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](https://www.gyrohosting.com/developers/en/howto/container-vpc.html).

## 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](https://www.gyrohosting.com/en/knowledgebase/article/gyro-cloud-istanbul-vpc-gateway-nat)).

## 6. FAQ

**Why does the source range matter?**

Container nodes can change; instead of allowing node IPs one by one you allow a fixed /28 that never changes.

**Can I move the environment to another subnet?**

Detach first, then attach to the new subnet. The new attachment gets a new range.

**My subnet is smaller than /26.** Add a /26 or larger subnet to the VPC and attach the environment there.

**Is there a charge?**

No. The connection and VPC traffic are free; no VPC gateway is needed.

**Can I attach a Serverless environment?**

VPC for Serverless environments is coming soon. This version works with node environments.