> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# IPPool

> IPPool is an allocatable address space. Root pools declare a CIDR directly; child pools carve a sub-prefix from a parent pool.

<Note>
  **Platform-provided resource.** Datum operates this resource; you typically reference or read it rather than create it. See [Platform resources](/api/platform/overview).
</Note>

<Note>
  API resource reference for **IPPool**. See [Platform resources](/api/platform/overview) for related platform-provided resources. An [IPClaim](/api/ipam/ipclaim) allocates addresses from a pool. To read or inspect, see [Reading resources](/datumctl/resources/reading).
</Note>

<Warning>
  This resource is part of the `v1alpha1` API and is subject to change. Fields and behavior may change in future releases.
</Warning>

## Identity

|         |                     |
| ------- | ------------------- |
| Group   | `ipam.miloapis.com` |
| Version | `v1alpha1`          |
| Kind    | `IPPool`            |
| Scope   | Platform            |

## Overview

An `IPPool` is an allocatable address space that IP address management (IPAM) draws from. A **root pool** declares its address range directly with a CIDR, while a **child pool** carves a smaller sub-prefix out of a parent pool by referencing it. Use an `IPPool` to define and hierarchically subdivide the address space that networking resources allocate addresses from, and read its status to track remaining headroom and utilization.

## Spec fields

| Field                             | Type    | Required | Description                                                                                                           |
| --------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `spec.cidr`                       | string  | No       | The address range for a root pool, in CIDR notation (for example, `10.0.0.0/16`). Root pools declare a CIDR directly. |
| `spec.ipFamily`                   | string  | No       | The address family of the pool (for example, IPv4 or IPv6).                                                           |
| `spec.prefixLength`               | integer | No       | The prefix length to carve when this pool is derived from a parent pool.                                              |
| `spec.parentPoolRef`              | Object  | No       | References the parent `IPPool` (in the same scope) that a child pool carves its sub-prefix from.                      |
| `spec.parentPoolRef.name`         | string  | Yes\*    | Name of the referenced parent pool. Required when `parentPoolRef` is set.                                             |
| `spec.visibility`                 | string  | No       | Controls the visibility of the pool.                                                                                  |
| `spec.allocation`                 | Object  | No       | Configures sub-allocation behavior for the pool.                                                                      |
| `spec.allocation.strategy`        | string  | No       | The strategy used when allocating sub-prefixes from this pool.                                                        |
| `spec.allocation.minPrefixLength` | integer | No       | The smallest prefix length (largest block) that may be allocated from this pool.                                      |
| `spec.allocation.maxPrefixLength` | integer | No       | The largest prefix length (smallest block) that may be allocated from this pool.                                      |

## Status fields (read-only)

| Field                       | Type      | Description                                                                                                                                                                                                                                 |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status.phase`              | string    | The current lifecycle phase of the pool.                                                                                                                                                                                                    |
| `status.conditions`         | \[]Object | Tracks state such as readiness for the pool.                                                                                                                                                                                                |
| `status.allocatedCIDR`      | string    | The CIDR carved for this pool. For child pools this is the sub-prefix allocated from the parent.                                                                                                                                            |
| `status.ipFamily`           | string    | The effective address family of the pool: taken from `spec.ipFamily` on root pools and derived from `status.allocatedCIDR` on child pools.                                                                                                  |
| `status.capacity`           | Object    | The address-count view of the pool. Counts are exact for IPv4; for address spaces larger than an int64 (wide IPv6 prefixes) `total` saturates to the maximum int64 and `allocated`/`available` are clamped to non-negative values.          |
| `status.capacity.total`     | integer   | Total number of addresses in the pool.                                                                                                                                                                                                      |
| `status.capacity.allocated` | integer   | Number of addresses currently allocated.                                                                                                                                                                                                    |
| `status.capacity.available` | integer   | Number of addresses currently available.                                                                                                                                                                                                    |
| `status.utilizationPercent` | integer   | The allocated share of the pool's address space, 0–100, computed with arbitrary-precision arithmetic so it is accurate for both IPv4 and IPv6.                                                                                              |
| `status.largestFreePrefix`  | integer   | The prefix length of the largest free aligned block currently available (for example, 45 for a free `/45`). Zero when the pool is exhausted or its capacity is not yet computed. This is the family-agnostic signal for remaining headroom. |

## Usage

```yaml theme={null}
apiVersion: ipam.miloapis.com/v1alpha1
kind: IPPool
metadata:
  name: primary-ipv4
spec:
  cidr: 10.0.0.0/16
  ipFamily: IPv4
```

```bash theme={null}
datumctl apply -f ippool.yaml
datumctl get ippools
datumctl describe ippool primary-ipv4
```

<Tip>
  Run `datumctl explain ippools --recursive` to see the full, live field tree for this resource.
</Tip>