Skip to main content
A VM’s pod address is volatile — it changes on restart and on migration. A VM identity pool hands out routable claim addresses that stay with a VM as it live-migrates between nodes, so its network identity never moves even when the VM does. This page covers the pool side — creating, sizing, and repairing pools. For how a VM claims an address and what identity means from the VM’s perspective, see VM networking.

​
How a pool works

An identity pool is a Cilium LoadBalancer IP pool that is deliberately disabled and labelled as an identity pool:
  • Disabled guarantees Cilium’s LB-IPAM never assigns its addresses to Services — the pool exists only for VM claims.
  • The BGP engine still advertises the pool’s aggregate prefix to the fabric, from every node.
  • The per-VM addresses stay node-internal, which is exactly what lets a VM keep its address after landing on a different node.
In the Pools & IPAM table, identity pools carry a live-migration capable badge so they are never mistaken for ordinary LoadBalancer pools. A healthy pool reads disabled (by design) and advertised, and expands into its claims — one row per VM: Every claim in range and a stale count of zero is the steady state; anything else means the pool was resized under its claims — see re-addressing.
Do not enable an identity pool or strip its identity role to “reuse” the range for Services. The moment LB-IPAM can allocate from it, Service addresses and VM claims collide.

​
Create a pool

1

Open Pools & IPAM

Go to Supervisors → your supervisor → Networking → Pools & IPAM and click Add pool.
2

Choose the VM identity kind

Give the pool a name and a CIDR that your fabric routes — for example 10.0.20.0/24. The network and broadcast addresses are always reserved; a /24 yields 254 claimable addresses.
3

Create

The pool is created disabled and identity-labelled, and its aggregate begins advertising. VMs can claim from it immediately — the claim itself happens at VM creation.
A project can also be given a VM identity range at creation — the resulting pool is identical, just owned by the project’s lifecycle.

​
Next-IP preview

Each identity pool can show the next address it would hand out: the first free address in the CIDR, skipping the network and broadcast addresses and every address already claimed by a VM. The create-VM flow uses the same computation, so the preview is exactly what the next VM will get.
Allocation is claim-scan based — the annotation on the VM is the record, there is no separate allocation store. Two VMs created in the same instant can theoretically race for the same address; for operator-driven creation this does not happen in practice.

​
Re-addressing

Resizing a pool can leave claims stale — an address outside the pool’s current CIDR is no longer advertised, and the VM is unreachable on it. The pool’s Re-address action repairs this: Re-addressing updates the claim on the VM and on its live instance, so the new address takes effect without recreating the VM. If the pool runs out of free addresses mid-operation, the action stops with a conflict — grow the pool and run it again.
Shrinking a pool strands every claim outside the new range. Check the IP allocations view before resizing, and plan to re-address immediately after — a stale claim means a VM that is silently unreachable on its identity address.

​
Permissions

Both are scoped to krn:vks:supervisor:<supervisor>:cilium:*.

VM networking

Claims, stale-claim symptoms, and everything else from the VM’s side.

Create a VM

Where a VM claims its identity address.

Pools & IPAM

The unified pool table this pool kind lives in.

BGP & Egress

Where the pool’s aggregate shows up in the advertise table.