Network

Key concepts

VPC
An isolated network for your resources. Creating one automatically gives you a default security group, a default network ACL, a private IPv4 range, and a first subnet — but no Internet Gateway. A new VPC is private until you attach one. Every project also has a default VPC, provisioned automatically the first time it’s needed — see Launching without specifying a network.

Subnet
A slice of a VPC’s address space. Every instance’s network interface belongs to exactly one subnet. A VPC can have more than one. A subnet can be flagged to auto-assign a public IP to every instance launched into it, and the flag can be changed afterwards — see Launching without specifying a network.

Internet Gateway
What makes a VPC’s subnets reachable from outside. A VPC has at most one, attached or detached as a whole — there’s no per-subnet toggle. See Making a VPC reachable from the internet.

Network ACL
A set of rules applied to every instance in a subnet, regardless of which security groups any individual instance carries. Every VPC gets one default ACL automatically, and you can create additional ones for subnets that need different rules — a subnet is associated with exactly one ACL at a time, reassignable after creation. See Controlling traffic with network ACLs. For per-instance rules, see security groups in the Compute guide.

Floating IP
A public IPv4 address allocated from the platform’s public pool, held independently of any instance until you associate it with a network interface. See Floating IPs.

Network Interface
The thing that actually holds an instance’s private IPv4/IPv6 addresses within a subnet. Interfaces are created as part of instance launch (or explicitly via create-network-interface ahead of launch) and are released automatically on termination. A standalone interface that was never attached to anything can also be removed directly with delete-network-interface. Its status field (AVAILABLE or ATTACHED, plus attachedToUrn when attached) shows whether it’s free or already in use, and to what.

DNS Policy
Controls where a VPC’s DNS relays queries it can’t answer itself (see DNS). Unlike security groups and network ACLs, a DNS policy isn’t owned by one VPC — a project can hold several, and the same policy can back more than one VPC at once.

Creating a VPC

Creating a VPC gives you, automatically:

• A default security group (no rules — nothing gets in until you add some; see the Compute guide).
• A default network ACL (wide open — everything is allowed in and out).
• Attachment to your project’s default DNS policy (a public resolver — see DNS). The first VPC you create in a project creates that default; every VPC after it reuses the same one unless you attach a different policy.
• A private IPv4 range, and a private IPv6 range — a first subnet is carved out of both.

It does not give you an Internet Gateway. Until you attach one, nothing in this VPC — no subnet, no instance — is reachable from outside it.

You can create additional subnets in the same VPC at any time; each gets its own address range in both families.

By default the VPC’s private IPv4 range is picked for you at random, avoiding a collision with any other VPC you already have. You can supply your own instead — it has to be private address space (10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16), sized between a /16 and a /28. Unlike the IPv4 range, the IPv6 range is always assigned for you.

The default is drawn from a bounded set of ranges, so once enough VPCs in your organisation hold them, create-vpc without --ipv4-cidr is refused and tells you to pass one explicitly. It’s a refusal you can act on, reported as one — not as something having gone wrong on the platform — and supplying your own range is all it takes.

An instance’s IPv4 address is configured inside the guest and routed the same way IPv6 is — both address families work end to end.

Making a VPC reachable from the internet

Attach an Internet Gateway to make every subnet in a VPC reachable — this applies to the whole VPC at once, including subnets (and instances) created after you attach it. Detach it to make the VPC private again. Both operations are idempotent: attaching to a VPC that already has one just returns the existing gateway; detaching one that has none is a no-op.

Once a VPC has an Internet Gateway attached, whether a specific instance is actually reachable still depends on its subnet’s network ACL and its own security group — attaching the gateway only makes reachability possible, it doesn’t bypass either of those.

A practical caveat today: the address space handed out to new subnets isn’t yet drawn from a real, publicly-routable block. Attaching an Internet Gateway makes an instance reachable from other resources on the platform’s own network, but not necessarily from the public internet — don’t assume the latter without checking.

Launching without specifying a network

You don’t have to create a VPC and subnet before launching your first instance. If you launch without specifying a subnet, the platform provisions your project’s default VPC the first time it’s needed: a VPC with an Internet Gateway already attached, and one subnet flagged to auto-assign a public IP. Your instance’s network interface gets a Floating IP allocated and associated automatically — no separate allocate-floating-ip/associate-floating-ip call needed.

This only happens the first time; every launch after that reuses the same default VPC and subnet unless you specify a different one explicitly. If you want private-only placement, or your own network layout, create and specify a VPC/subnet yourself the same way as always — nothing about explicit VPC/subnet creation changes.

You can also flag a subnet you create yourself to auto-assign public IPs the same way, via create-subnet --vpc-urn <urn> --auto-assign-public-ip true|false. The value is required and spelled out, exactly as on update-subnet-auto-assign-public-ip, so the two commands read the same way; false is the setting you want if you don’t need it. It behaves identically to the default subnet’s flag: every instance launched into that subnet gets a Floating IP automatically. If the project/org’s public-IP pool happens to be exhausted when an instance launches, the launch still succeeds — just without a public IP, rather than failing outright.

You can change the flag on an existing subnet at any time with update-subnet-auto-assign-public-ip --subnet-urn <urn> --auto-assign-public-ip true|false — you don’t have to recreate the subnet to change your mind. It applies to instances launched from that point on only. Turning it on doesn’t give a Floating IP to instances that are already running, and turning it off doesn’t take one away from them; use associate-floating-ip/disassociate-floating-ip per interface if you want to change an instance that already exists. The setting lives on the subnet and nowhere else — there is no VPC-wide default to inherit from.

Deleting a VPC or subnet

You can delete a subnet on its own, or delete a whole VPC (which deletes every subnet in it, along with its security groups, network ACLs, and Internet Gateway if one is attached). Its DNS policy is not deleted — a policy is independent of any one VPC and may back others; delete it separately with delete-dns-policy if you no longer need it (only possible once no VPC is attached to it, and never for a project’s default).

Either operation refuses if a network interface anywhere in what you’re deleting is still attached to something — detach or terminate whatever’s using it first. A network interface that was created but never attached to anything doesn’t block deletion; it’s removed automatically.

The refusal names which subnet and which network interface is blocking, so you don’t have to work it out yourself — which matters most for delete-vpc, where the blocking interface can be in any of the VPC’s subnets. Like the pool-exhaustion refusals below, it’s a refusal you can act on and is reported as one, not as something having gone wrong on the platform. The same holds for every “still in use” refusal in this section: deleting a network interface that’s still attached, a network ACL a subnet still has assigned, a security group an interface still references, a DNS policy a VPC is still attached to, and releasing or re-associating a Floating IP that’s still associated.

Deleting a subnet on its own does not give back any of the VPC’s address space, even if it was the VPC’s last subnet — that only happens when you delete the VPC itself. Deleting a VPC releases its address ranges back to the pool they came from once every resource that depended on it is gone.

Because of that, a VPC’s address space can run out: create-subnet is refused once the VPC has no room left for another subnet, and creating a network interface (or launching an instance) is refused once its subnet has no addresses left. Both name the VPC or subnet that ran out and what gets you space — a different or new VPC in the first case, since deleting a subnet gives none back; a different subnet or deleting network interfaces you no longer need in the second, which does. Like the pool-exhaustion refusals below, running out of address space is not the same as something having gone wrong on the platform, and it isn’t reported as though it were.

Controlling traffic with network ACLs

A network ACL is a list of rules — allow or deny, by protocol, port, and source or destination address range — applied to an entire subnet at once. Every instance in the subnet is subject to the same rules, on top of whatever its own security group allows or denies.

Unlike security groups, network ACLs are stateless: a rule only describes one direction, so a connection that needs to work both ways needs a rule for each direction explicitly. Rules are evaluated in order, and a packet that matches nothing is denied.

Network ACLs and security groups don’t overlap as much as you might expect. Traffic between two instances in the same subnet that happen to be running on the same underlying host never reaches network ACL enforcement at all — only the instances’ own security groups apply to it. If you need to restrict instance-to-instance traffic and can’t be sure they’ll end up on different hosts, use a security group, not a network ACL.

Every VPC gets one default network ACL automatically, and you can create additional ones if you want different rule sets for different subnets rather than editing the one default to fit everyone. A newly created ACL starts with no rules (deny-by-default) — add some with update-acl-rules --acl-urn <urn> --rule …, then point a subnet at it with update-subnet-acl. update-acl-rules replaces the whole rule list, so it requires you to state what the new list is: one or more --rule, or --no-rules to say the ACL should end up with none. Running it with neither is refused rather than quietly emptying the ACL (see Replacing a whole set below). A subnet is associated with exactly one ACL at a time; reassigning it takes effect for that subnet’s traffic without needing to recreate anything. A VPC’s default ACL can’t be deleted on its own — it goes away only when the VPC itself is deleted — and a non-default ACL can’t be deleted while any subnet still has it assigned.

Floating IPs

A Floating IP is a public IPv4 address you allocate from the platform’s public pool ahead of time, independent of any specific instance. It stays yours — and keeps its address — until you release it, even while unassociated.

Allocate one against a project, then associate it with a network interface to enable static 1:1 NAT for that interface’s private address. A Floating IP can only be associated with one interface at a time; associating it elsewhere first requires disassociating it. Releasing a Floating IP requires it to be disassociated first, and gives the address back to the pool for good.

The public pool is a finite, platform-wide resource, so an explicit allocate-floating-ip can be refused because the zone has no address left to give — separately from your project’s or organisation’s own public-IP quota, which is refused with the limit you hit. Both are refusals you can act on, and both name the reason: address exhaustion is not the same as something having gone wrong on the platform, and it isn’t reported as though it were. Releasing a Floating IP you no longer need frees its address for the next allocation. The same applies to create-vpc, which claims the VPC’s IPv6 range from the same kind of pool.

DNS

Instances in the same VPC can resolve each other by hostname automatically — no configuration needed. A query for anything else (a public internet hostname, or your own corporate DNS zone) is relayed per the DNS policy the VPC is currently attached to, or refused outright if that policy has relaying turned off.

A DNS policy is a project-level resource, not something owned by one VPC. A project can hold more than one — e.g. one per corporate DNS zone you need to resolve — and the same policy can be attached to several VPCs at once. Exactly one policy per project is always the default: it’s created automatically (pointed at a public resolver, relaying on) the first time you create a VPC in a project, and every VPC you create after that attaches to it unless you say otherwise.

• Create additional policies with create-dns-policy — a list of upstream servers (--upstream-server, or --no-upstream-servers for none), and whether relaying is even enabled (--relay-enabled false means a clean refusal for anything outside the VPC, matching the platform’s behavior before this feature existed).
• Edit a policy’s own settings with update-dns-policy — the full server list you pass replaces the existing one, same convention as ACL and security group rules. This takes effect for every VPC currently attached to that policy, live, no restart needed.
• Attach a different policy to a specific VPC with attach-dns-policy — e.g. to point just that VPC at your own corporate DNS instead of the project default. The policy must belong to the same project as the VPC.
• Reassign the project default with set-default-dns-policy — this only changes what a future create-vpc in the project attaches to; it does not move any existing VPC off its current policy.
• Delete a policy with delete-dns-policy — refused while it’s the project’s default, or while any VPC is still attached to it.

Replacing a whole set

Network ACL rules, security group rules and DNS upstream servers are all replaced as a whole set — there is no “add one rule” or “remove one server” operation, and no “leave this part as it is” spelling. Every one of these commands writes out the complete new state of the resource, so it makes you state that state in full, and refuses to run if you left part of it out:

The empty set is a perfectly legitimate state — an ACL with no rules denies everything, a security group with no egress rules lets nothing out, a non-relaying DNS policy needs no upstream servers — so it stays available. It just has to be asked for by name. Two rules follow from that:

• Omitting an argument is never how you ask for the empty set. update-acl-rules --acl-urn <urn> on its own used to read like a no-op and silently drop every rule on the ACL; it now exits with an error and sends nothing. Say --no-rules if that is what you meant.
• Both of a security group’s lists are replaced on every call. update-security-group-rules --security-group-urn <urn> --ingress-rule … does not leave the egress rules alone — it replaces them too. State them: repeat --egress-rule for the ones you want to keep, or --no-egress-rules if the answer really is none.

Booleans follow the same principle: --relay-enabled and --auto-assign-public-ip take an explicit true/false rather than being bare presence flags, so leaving one off an update can’t quietly turn a setting off on a resource that currently has it on. The create command for a resource is always spelled like its update, so a habit learned on one isn’t punished by the other.

Contradicting yourself is refused too — --rule … --no-rules in the same invocation is an error, not a coin flip — and --relay-enabled true with no upstream servers is rejected as an empty relay list.

Using Network

• The GraphQL API — the primary interface. Look under the network namespace for VPCs, subnets, network interfaces, Internet Gateways, network ACLs, security groups, DNS policies, and Floating IPs.
• The origin CLI — covers VPCs, subnets, network interfaces, Internet Gateways, network ACLs, security groups, DNS policies, and Floating IPs: create-vpc, list-vpcs, get-vpc, delete-vpc, create-subnet, list-subnets, get-subnet, delete-subnet, update-subnet-acl, update-subnet-auto-assign-public-ip, create-network-interface, get-network-interface, delete-network-interface, list-network-interfaces, attach-internet-gateway, detach-internet-gateway, get-internet-gateway, get-acl, list-acls, create-acl, delete-acl, update-acl-rules, get-security-group, list-security-groups, create-security-group, delete-security-group, update-security-group-rules, list-dns-policies, get-dns-policy, create-dns-policy, update-dns-policy, set-default-dns-policy, delete-dns-policy, attach-dns-policy, allocate-floating-ip, list-floating-ips, get-floating-ip, associate-floating-ip, disassociate-floating-ip, release-floating-ip. A network ACL’s, security group’s, or DNS policy’s rules/servers are always replaced as a whole set, not added to or removed individually — pass everything you want to keep along with whatever’s new, and see Replacing a whole set for how each command makes you state that.

Creating a VPC

mutation CreateVpc($input: NetworkCreateVpcInput!) {
  network {
    createVpc(input: $input) {
      urn
      ipv4Network {
        networkCidr
        totalSubnets
        availableSubnets
        subnetPrefixLength
      }
      createdAt
      createdBy
    }
  }
}

{
  "input": {
    "projectUrn": "urn:origin:cloud:admin::7a07d9ec7ba2::proj-4f21c9a03b17",
    "ipv4Cidr": "10.0.0.0/16"
  }
}

origin network create-vpc \
  --project-urn urn:origin:cloud:admin::7a07d9ec7ba2::proj-4f21c9a03b17 \
  --ipv4-cidr 10.0.0.0/16

Replacing an ACL’s rules

update-acl-rules replaces the whole list every time, so it makes you state what the new list is — one or more --rule, or --no-rules for an empty (deny-everything) ACL. Passing neither is refused rather than silently emptying it.

origin network update-acl-rules \
  --acl-urn urn:origin:cloud:network:eu-central1:7a07d9ec7ba2:proj-4f21c9a03b17:acl-9d3b17c04f21 \
  --rule priority=100,direction=ingress,protocol=tcp,port=22,source=10.0.0.0/16,policy=accept \
  --rule priority=110,direction=ingress,protocol=tcp,port=443,source=0.0.0.0/0,policy=accept \
  --rule priority=200,direction=egress,protocol=any,port=any,source=0.0.0.0/0,policy=accept

mutation UpdateAclRules($input: NetworkUpdateAclRulesInput!) {
  network {
    updateAclRules(input: $input) {
      urn
      vpcId
      isDefault
      rules {
        priority
        direction
        protocol
        port
        source
        policy
      }
    }
  }
}