> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Networking

> The network Synthetiq provisions into, and what it builds vs. reuses

Synthetiq provisions into a VPC and public subnets you provide. By default the stack creates everything else it needs — three /24 private workload subnets, their route table, and a NAT gateway — all visible in the [changeset diff](/docs/platform-docs/deployments/byoi/provisioning) before anything is applied. The `overrides` block lets you reuse existing infrastructure instead.

We recommend deploying Synthetiq into its own AWS sub-account — isolated IAM, quotas, billing, and blast radius — and selectively granting access to services in your internal VPCs from your side, via VPC peering, Transit Gateway, or PrivateLink. You can equally provision into an existing VPC, or supply your own private subnets end to end.

## Required: a VPC and three public subnets

```yaml theme={null}
network:
  vpc: vpc-0abc123
  public_subnets: [subnet-a, subnet-b, subnet-c]
```

* Public subnets in at least 3 Availability Zones, each with an internet-gateway route.
* Room for three /24 workload subnets in the VPC CIDR. Synthetiq auto-allocates them from free space, skipping any range that overlaps an existing subnet, and fails the plan (not the apply) if there isn't room — or you can [pin the CIDRs](#choosing-your-own-private-subnet-cidrs) or supply [your own subnets](#deploying-into-existing-private-subnets).

## Reusing an existing NAT gateway

```yaml theme={null}
overrides:
  nat: nat-0xyz789
```

The stack still creates the workload subnets and their route table, but routes egress through this NAT instead of creating a NAT gateway and Elastic IP.

## Choosing your own private subnet CIDRs

```yaml theme={null}
overrides:
  private_subnet_cidrs: [10.0.128.0/24, 10.0.129.0/24, 10.0.130.0/24]
```

Synthetiq still creates the workload subnets, their route table, and the NAT gateway — this only pins the three CIDR blocks instead of auto-allocating them. Useful when you manage IP space centrally (IPAM, Terraform), or to force specific ranges after an auto-allocation didn't fit.

The blocks must sit inside your VPC CIDR, not overlap any existing subnet, and you supply three (one per AZ). They're validated at plan time, so a bad value fails [`generate`](/docs/platform-docs/deployments/byoi/provisioning) rather than rolling back the apply. Mutually exclusive with `private_subnets` below — `private_subnet_cidrs` has Synthetiq create the subnets, `private_subnets` deploys into ones you already created.

## Deploying into existing private subnets

```yaml theme={null}
overrides:
  private_subnets: [subnet-p, subnet-q, subnet-r]
```

Synthetiq creates no networking at all — workloads run in your subnets. `overrides.nat` cannot be combined with this: egress through your subnets is governed by your route tables.

What lands in your subnets:

| Resource                                       | Count                               | IP consumption              |
| ---------------------------------------------- | ----------------------------------- | --------------------------- |
| Fargate task ENIs                              | One per running app/worker instance | Variable — scales with load |
| Interface VPC endpoint ENIs (metrics delivery) | One per subnet                      | Fixed — 3 IPs               |

### Your responsibilities when supplying subnets

* **Egress** — each subnet needs a default route (0.0.0.0/0) to your NAT gateway, Transit Gateway, or egress stack, and it must stay in place after provisioning (removing it later breaks deployments and outbound calls). If you filter egress by destination, allow HTTPS to: ECR and S3 (image pulls at task launch), Secrets Manager (secret injection at container start), CloudWatch Logs (log shipping), `login.synthetiq.com` (user sign-in to apps), and any APIs your apps call.
* **IP capacity** — one IP per running task; size for the sum of autoscaling maxima across all services, plus 3 endpoint IPs (≥50 free IPs per subnet recommended). Exhaustion fails gracefully: new launches roll back, running apps are unaffected.
* **Subnet shape** — three subnets in three distinct AZs, with no internet-gateway default route (tasks launch without public IPs, so an IGW route means no working egress). Non-default NACLs must allow outbound 443, ephemeral return ports, and port 8080 from your public subnets' CIDRs.

The pre-flight verifies subnet shape, reports free-IP capacity, and warns (rather than blocks) on egress it can't statically verify, such as Transit Gateway or inspection architectures.