---
title: "IPAM handle"
description: "Reference for the IPAMHandle resource in Calico Open Source that records which IP address blocks hold the addresses assigned to one pod or tunnel."
product: "Calico Open Source"
version: "3.33 (latest)"
section: "Reference"
canonical_url: "https://docs.tigera.io/calico/latest/reference/resources/ipamhandle"
---

# 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>`](https://docs.tigera.io/calico/latest/reference/calicoctl/ipam/show.md).

This resource is in the `projectcalico.org/v3` API only when the cluster uses [native v3 CRDs](https://docs.tigera.io/calico/latest/operations/native-v3-crds.md). 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

| Field | Description                                                                           | Accepted Values                                                                                                          | Schema | Default |
| ----- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ------- |
| name  | The 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

| Field    | Description                                                                                                                                                         | Accepted Values | Schema                   | Default |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------ | ------- |
| handleID | The identifier of this handle. See [Handle IDs](#handle-ids). Required.                                                                                             |                 | string                   |         |
| block    | The 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 |         |
| deleted  | Calico IPAM sets this field to `true` immediately before it deletes the handle. Don't set it yourself.                                                              | `true`, `false` | boolean                  |         |

## Handle IDs

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

| Owner                            | Handle ID                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| A pod                            | `k8s-pod-network.<sandbox-id>`, where `<sandbox-id>` is the ID of the pod's sandbox in the container runtime |
| A node's VXLAN tunnel address    | `vxlan-tunnel-addr-<node-name>`, where `<node-name>` is the name of the node                                 |
| A `LoadBalancer` service address | `lb-<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

- [Block affinity](https://docs.tigera.io/calico/latest/reference/resources/blockaffinity.md)
- [IPAM configuration](https://docs.tigera.io/calico/latest/reference/resources/ipamconfig.md)
- [IP pool](https://docs.tigera.io/calico/latest/reference/resources/ippool.md)
