VPCs and subnets

A network begins with a VPC (Virtual Private Cloud), the top-level isolation boundary. A VPC owns a private IP address space and is the parent of every subnet and firewall policy beneath it. The model is engine-agnostic: you describe VPCs and subnets, and the platform provisions them on the underlying network fabric.

Addressing

VPCs and subnets describe their address space in CIDR notation, an IP address plus a prefix length:

• Address: an IPv4 or IPv6 address.
• Prefix length: how many leading bits are fixed. The range is 0 to 32 for IPv4 and 0 to 128 for IPv6. A single host, such as a subnet gateway, uses 32 or 128.

A VPC’s CIDR defines its full address space; a subnet’s CIDR carves out a slice of it.

VPCs

A VPC is scoped to two containers:

• Workspace: the workspace that owns the VPC, derived from the request path.
• Zone: the zone the VPC is deployed into.

It carries a name (1 to 63 characters), an optional description, and its CIDR. A few fields are set by the platform, not the client: the VPC’s id, its creation and update timestamps, and a provider-assigned id that is filled in once the underlying network fabric provisions the VPC.

VPC invariants

• The CIDR is immutable. Updating a VPC can change its name and description, but not its address space. Choose the CIDR deliberately at creation time.
• Deletion is guarded. Deleting a VPC fails while it still has subnets or firewall policies. Tear the children down first.

Subnets

A subnet subdivides its parent VPC’s address space. It references its parent VPC and carries:

• A name (1 to 63 characters) and an optional description.
• A CIDR, the subnet’s address range.
• A gateway IP, the subnet gateway. If you omit it on creation, the platform derives it automatically from the CIDR.

As with a VPC, the id, timestamps, and provider-assigned id are set by the platform.

Subnet invariants

• Containment. A subnet’s CIDR must be a subset of the parent VPC’s CIDR.
• No overlap. A subnet’s CIDR must not overlap any sibling subnet in the same VPC.
• CIDR and gateway are immutable. Updating a subnet can change its name and description only; the address range and gateway IP are fixed at creation.

The hierarchy

A VPC owns an address space, and each subnet is a non-overlapping slice of it:

flowchart TD
  classDef accent fill:#e2faec,stroke:#00e64d,stroke-width:2px,color:#0e0d1a

  subgraph vpc["VPC (10.0.0.0/16)"]
    web["Subnet web-tier<br/>10.0.1.0/24"]:::accent
    data["Subnet data-tier<br/>10.0.2.0/24"]:::accent
  end

  style vpc fill:#e8e8ff,stroke:#1100ff,stroke-width:2px,color:#0e0d1a

Because the CIDR fields are immutable, address planning is a one-time, upfront decision. Pick a VPC CIDR large enough for every subnet you expect, and size subnets so they neither overlap nor exceed the VPC range.

To put this model into practice, follow Create a VPC and subnet.