VPCs
This page explains what the VPC resource means in the kopernik.us API and how a subnet describes its internet connectivity.
For endpoint and schema details, see the VPC API reference. For console workflow guidance, see the VPCs console guide.
What a VPC is
A VPC is the provider-agnostic representation of an isolated network inside a single region.
Provider equivalents include:
- Akamai VPC
- AWS VPC
- DigitalOcean VPC
A VPC carries subnets, each with its own IP range, and resources such as machines and Kubernetes clusters are placed in one of those subnets.
How a subnet reports its connectivity
Each subnet carries two fields that together describe how it reaches the internet:
access— the connectivity observed from the provider’s own routing.enforcement— who guarantees that connectivity.
Both are derived on every read rather than stored, so they reflect routing changes made outside this service. A
subnet whose routing cannot be read reports no access at all rather than a guess.
States a subnet can report
access |
enforcement |
What it means | A machine requesting networkAccess: public |
Where it comes from |
|---|---|---|---|---|
public |
network |
Instances may hold a public address and are reachable from the internet. | Permitted. | AWS, where the subnet’s default route leads to an internet gateway. |
private |
network |
Not reachable from the internet; outbound access through the provider’s NAT. | Rejected. | AWS, where the default route leads to a NAT gateway. |
isolated |
network |
No internet access in either direction; traffic stays within the VPC. | Rejected. | AWS, where the subnet has no default route. |
custom |
network |
A default route this service cannot classify, such as one to an instance or an appliance you manage. | Permitted; the machine decides, because the destination is unknown. | AWS, where the default route leads anywhere else. |
| (absent) | network |
Connectivity is unknown because the routing behind the subnet could not be read. | Permitted; the machine decides. | AWS without ec2:DescribeRouteTables. |
unsupported |
none |
The provider has no subnet-level boundary, so connectivity is configured per machine instead. | Permitted; the machine decides. | Akamai and DigitalOcean. |
These are the pairs the providers report today. Rather than matching on them, read any pair by the rule behind the
table: enforcement: network means the provider’s routing holds instances to access, so a subnet whose access is
private or isolated cannot hold a public machine. Any other enforcement makes access a description rather
than a boundary, and the machine’s own networkAccess decides.
The rule sets a ceiling rather than a floor: a subnet always takes a machine with less connectivity than it offers.
A public subnet enforced by the network holds both a public machine and a private one, so two machines in one
subnet may well differ in reachability whatever the enforcement says. What enforcement: none removes is the
ceiling, not the subnet’s uniformity.
Whether that variation is available at all is a question about the provider rather than about the subnet, and
limits.service.machine.supportedNetworkAccess answers it. A provider reporting both public and private lets
one subnet hold each kind; a provider reporting only public gives every machine a public address even where no
subnet enforces it.
Requesting access when creating a VPC
Each subnet in a create request may ask for public, private or isolated. The values a provider accepts are
reported in staticdata under limits.service.vpc.subnet.supportedAccess; where that list is empty the provider
does not model connectivity at subnet level and the field is rejected rather than ignored. A subnet that does not
ask defaults to public.
A private subnet reaches the internet through a NAT gateway, which has to sit in a public subnet of the same VPC, so
a request for a private subnet without a public one is rejected rather than having a public subnet added to it
silently. One gateway serves all private subnets of the VPC and is charged by the provider for as long as it
exists; staticdata reports the rate.
How a machine uses it
A machine’s networkAccess asks whether the instance gets a public address of its own, within the values in
limits.service.machine.supportedNetworkAccess. A request for public is rejected when the machine’s subnet does
not permit one, so the stronger of the two always wins. When networkAccess is omitted, the subnet decides where
it can, and the provider’s default applies otherwise.
A machine without a public address of its own has no inbound reachability, and no outbound access either unless something in its path translates addresses for it: neither an instance in a public subnet that was given no address nor a VPC interface without one-to-one NAT reaches the internet. A private subnet is the arrangement that keeps outbound access, because the NAT gateway it routes through provides it.
See the Machines API guide for the rest of what machine creation controls, and the API overview for the provider permissions each VPC operation needs.