> For the complete documentation index, see [llms.txt](https://nso-docs.cisco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nso-docs.cisco.com/resources/platform-tools/resource-manager/ip-allocator.md).

# IP Address Allocator

Manage IP address allocation in NSO.

The NSO Resource Manager IP Address Allocator allocates IP prefixes or individual addresses. It supports IPv4 and IPv6 resources.

## Pool Definition

Each IP address pool is a named configuration item under `/resource-pools/ip-address-pool` and contains a list of subnets used for resource allocation.

```
admin@ncs(config)# resource-pools ip-address-pool some-pool subnet 192.0.2.0 24
admin@ncs(config)# resource-pools ip-address-pool some-pool subnet 2001:db8:: 32
admin@ncs(config)# commit
```

Additionally, non-overlapping exclusion ranges may be defined for a pool. The values from the exclusion ranges are not available for allocation.

```
admin@ncs(config)# resource-pools ip-address-pool some-pool exclude 192.0.2.4 30
admin@ncs(config)# commit
```

```
resource-pools ip-address-pool some-pool
 subnet 192.0.2.0 24
 subnet 2001:db8:: 32
 exclude 192.0.2.4 30
!
```

From RM 5.2.2, a **new** IP address or prefix selected from an existing pool respects excludes changed earlier in the same NSO transaction. An IP request names one IP address pool. See [Resource Manager 5.2 updates](https://nso-docs.cisco.com/resources/platform-tools/resource-manager/updates-5.2.md) for the scope and compatibility notes.

## Excludes and Quarantine

From RM 5.2.3, an IP exclude cannot overlap an address or prefix held by an active quarantine entry. Expired quarantine entries do not block the exclude.

Resource Manager ignores expired quarantine entries when it rebuilds pool availability. If an expired quarantined address or prefix has since been excluded, Resource Manager does not restore it from quarantine.

## Allocate Action

Manual allocation or pre-allocation is possible with the use of the `/resource-pools/find-ip` action. If `allocate` parameter is specified, the allocation is persisted right away. Otherwise, a free resource is returned if found, however, it is **not** allocated.

The request must specify either a specific resource or requested prefix length:

```shell
admin@ncs# resource-pools find-ip allocation-name my-value pool some-pool resource 192.0.2.1/32
```

```shell
admin@ncs# resource-pools find-ip allocation-name my-value pool some-pool prefix-length 30
```

The action shares the allocation engine with the programmatic API but is primarily designed for manual use, e.g. through the CLI. In the service code, use programmatic API instead.

See [Resource Manager (5.2.3)](https://nso-docs.cisco.com/resources/platform-tools/resource-manager.md#allocation-options) for more options.

## Allocate by API

{% tabs %}
{% tab title="Python" %}
For service use, Resource Manager exposes the `resource_manager.service.Allocator` class.

First, import and create an instance of the `Allocator`, supplying the `service` object as provided by the service callback (e.g. `cb_create`):

```python
from resource_manager.service import Allocator
```

```python
rm_allocator = Allocator(service)
```

Then, create a new IP address allocator request by calling `Allocator.ip()` and configuring a requested prefix length:

```python
my_value_request = rm_allocator.ip().prefix_length(30)
```

If you wish to allocate a specific value (if it is still available), you need to call the `ip()` function with the `request_ip` parameter instead:

```python
my_value_request = rm_allocator.ip(request_ip='192.0.2.1/32')
```

You must also select a resource pool to assign the value from:

```python
my_value_request = rm_allocator.ip().pool('some-pool')
```

Finally, allocate an actual value by calling `allocate()` with the allocation name:

```python
my_value = my_value_request.allocate('my-value') # Returns e.g. '192.0.2.1/32'
```

{% endtab %}

{% tab title="Java" %}
For service use, Resource Manager exposes the `com.tailf.resourcemanager.Allocator` class.

First, import and create an instance of the `Allocator`, supplying the `context` object as provided by the service callback (e.g. `create`):

```java
import com.tailf.resourcemanager.*;
```

```java
Allocator rm_allocator = Allocator(context);
```

Then, create a new IP address allocator request by calling `Allocator.ip()` and configuring a requested prefix length:

```java
IpAllocation my_value_request = rm_allocator.ip().prefixLength(30);
```

If you wish to allocate a specific value (if it is still available), you need to call the `ip()` function with the desired value as a parameter instead:

```java
IpAllocation my_value_request = rm_allocator.ip("192.0.2.1/32");
```

You must also select a resource pool to assign the value from:

```java
IpAllocation my_value_request = rm_allocator.ip().pool("some-pool");
```

Finally, allocate an actual value by calling `allocate()` with the allocation name:

```java
ConfObject my_value = my_value_request.allocate("my-value");
// Returns e.g. '192.0.2.1/32'
```

{% endtab %}
{% endtabs %}

## Pool Metrics

The per-pool `get-metrics` action calculates total, available, and available percentage on demand. It was already available in RM 5.1.0; it is not a new 5.2.2 feature.

```
admin@ncs# resource-pools ip-address-pool <pool-name> get-metrics
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://nso-docs.cisco.com/resources/platform-tools/resource-manager/ip-allocator.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
