IPAM
Guest networks, prefixes, reserved addresses, and static IP assignment for customer VMs
NodeRings IP address management (IPAM) lets you register your public (or routable) address space inside the platform. When a customer orders a virtual machine, NodeRings picks free addresses from your pools, records the assignment, and injects them into the VM through cloud-init network-data with static IPv4 and IPv6, gateway, and DNS.
Manage networks at /infrastructure/ipam.
NodeRings requires dual-stack guest networking. Every customer VM receives a static IPv4 and IPv6 address. IPv4-only or IPv6-only guest networks are not supported today.
What IPAM does
| Concept | Detail |
|---|---|
| Network | Logical guest pool: name, DNS resolvers, assigned nodes, and one or more prefixes |
| Prefix | IPv4 or IPv6 CIDR carved from your space; each prefix has its own gateway and optional reserved addresses |
| Shared pool | All nodes on the same network draw from the same assignable addresses |
| Allocation | On VM create, NodeRings assigns the next free address (or your chosen strategy) and passes it to cloud-init |
When a VM is provisioned on a node attached to a network, the operator compiles your linked cloud-init template with vm_network.* variables populated from IPAM. Customer addressing is static; NodeRings does not use DHCP inside the guest.
Setup workflow
Open IPAM
Go to /infrastructure/ipam. If you have no networks yet, click Create Network.
Create a network
Give the network a name, add DNS servers (up to four) that customer VMs should use, and assign the nodes that will sell VMs from this address space. A node can belong to one guest network at a time.
Add IPv4 and IPv6 prefixes
Under the network, click Add Prefix for each CIDR you delegate to NodeRings, typically one IPv4 prefix and one IPv6 prefix per network. Each prefix has:
- CIDR: the range NodeRings may assign from
- Gateway IP: default gateway for addresses in that prefix
- Allocation strategy: e.g. first available
- Reserved IPs (optional): addresses NodeRings must never auto-assign
Mark the gateway and any infrastructure addresses as reserved so they stay out of the customer pool.
Verify utilization
The prefix table shows allocated, reserved, and available counts. Expand a prefix to see the address grid (gateway, reserved, available). When a plan’s sell-path node is attached and pools are healthy, preflight IP Avail. can pass.
Reserved addresses
Use Reserved IPs on a prefix when part of the CIDR is already in use outside NodeRings, for example addresses handed to your own internal customers, hypervisor management, or upstream routers. Reserved addresses are excluded from automatic VM assignment but still count toward prefix utilization in the dashboard.
You can add or remove reserved addresses in the UI when editing a prefix, or through the API (see below).
Marketplace IP requirements
For a plan to pass preflight and appear as a discoverable listing on the marketplace, the network attached to its sell-path nodes must have enough free assignable addresses in the shared pool (summed across all prefixes on that network):
| Family | Minimum free assignable addresses |
|---|---|
| IPv4 | 5 |
| IPv6 | 10 |
If either pool falls short, the IP Avail. check fails and the plan stays off the marketplace until you add prefix capacity, free reserved addresses, or reduce allocations. See Preflight Check for the full preflight matrix.
Sync with your DHCP or external IPAM
If you run a separate DHCP server or external IPAM for part of the same prefix, keep NodeRings in sync by reserving addresses when they are taken upstream and unreserving them when they are free again. Use a service account API key and small automation (for example Python scripts) that call:
IPAMService_AddReservedIP: mark an address reserved so NodeRings will not assign itIPAMService_RemoveReservedIP: release a reservation when the address is available again
That way your DHCP leases and NodeRings’ assignable pool stay aligned without manual dashboard edits.