Skip to main content
Calico Open Source 3.33 (latest) documentation

IPAM handle

An IPAM handle resource (IPAMHandle) represents one group of IP addresses that Calico IP address management (IPAM) assigned to the same owner, such as a pod. Each handle lists the IPAM blocks that hold its addresses, and how many addresses it holds in each block. IPAMHandle is a cluster-scoped resource.

Calico IPAM creates and manages these resources. You don't normally create or change them yourself. To see the handle that holds an IP address, use calicoctl ipam show --ip=<ip-address>.

This resource is in the projectcalico.org/v3 API only when the cluster uses native v3 CRDs. The Calico API server doesn't serve it. In API server mode, read the ipamhandles.crd.projectcalico.org resource instead. It has the same fields.

For kubectl commands, you can use the aliases ipamhandle.projectcalico.org, ipamhandles.projectcalico.org, ipamhandle.p, and ipamhandles.p. The calicoctl get command doesn't support this resource.

Definition​

Metadata​

FieldDescriptionAccepted ValuesSchemaDefault
nameThe name of this IPAM handle. Calico sets it to the handle ID in lowercase. Required.Lowercase alphanumeric characters, -, or .. Must start and end with an alphanumeric character. Up to 253 characters.string

Spec​

FieldDescriptionAccepted ValuesSchemaDefault
handleIDThe identifier of this handle. See Handle IDs. Required.string
blockThe IPAM blocks that hold this handle's addresses. Each key is the CIDR of a block. Each value is the number of addresses the handle holds in that block. Required.map of string to integer
deletedCalico IPAM sets this field to true immediately before it deletes the handle. Don't set it yourself.true, falseboolean

Handle IDs​

Calico builds each handle ID from the owner of the addresses. For example:

OwnerHandle ID
A podk8s-pod-network.<sandbox-id>, where <sandbox-id> is the ID of the pod's sandbox in the container runtime
A node's VXLAN tunnel addressvxlan-tunnel-addr-<node-name>, where <node-name> is the name of the node
A LoadBalancer service addresslb-<hash>, where <hash> is a string of letters and digits that Calico generates

Calico creates the handle when it assigns the addresses, and deletes the handle when it releases them. For a pod, that is when the container runtime creates the pod's sandbox and when it stops the sandbox, for example when the pod is deleted or runs to completion. A pod that uses the host network has no handle.

Additional resources​