Resource Manager (4.2.11)
Manage resource allocation in NSO.
The NSO Resource Manager package contains both an API for generic resource pool handling called the resource allocator, and the two applications (id-allocator andipaddress-allocator) utilizing the API. The applications are explained separately in the following sections below:
Background
NSO is often used to provision services in the networking layer. It is not unusual that these services require network-level information that is not (or cannot be) part of the instance data provided by the northbound system, so it needs to be fetched from, and eventually released back to a separate system. A common example of this is IP addresses used for layer-3 VPN services. The orchestrator tool is not aware of the blocks of IP addresses assigned to the network but relies on lower layers to fulfill this need.
Some customers have software systems to manage these types of temporary assets. E.g., for IP-addresses, they are usually known as IP Address Management (IPAM) systems. There is a whole industry of solutions for such systems, ranging from simple open-source solutions to entire suites integrated with DNS management. See IP address management for more on this.
There are customers that either don't have an IPAM system for services that are planned for NSO or are not planning to get one for this single purpose. They usually don't want the operational overhead of another system and/or don't see the need for a separate investment. These customers are looking for NSO to provide basic resource allocation and lifecycle management for the assets required for services managed by NSO. They appreciate the fact that NSO is not an appropriate platform to provide more advanced features from the IPAM world like capacity planning nor to integrate with DNS and DHCP platforms. This means that the NSO Resource Manager does not compete with full-blown systems but is rather a complementary feature.
Overview
The NSO Resource Manager interface, the resource allocator, provides a generic resource allocation mechanism that works well with services and in a high availability (HA) configuration. Expected is implementations of specific resource allocators implemented as separate NSO packages. A service will then have the possibility to use allocator implementations dedicated to different resources.
The YANG model of the resource allocator (resource-allocator.yang) can be augmented with different resource pools, as is the case for the two applications id-allocator and ipaddress-allocator. Each pool has an allocation list where services are expected to create instances to signal that they request an allocation. Request parameters are stored in the request container and the allocation response is written in the response container.
Since the allocation request may fail the response container contains a choice where one case is for error and one for success.
Each allocation list entry also contains an allocating-service leaf-list. These are instance identifiers that point to the services that requested the resource. These are the services that will be redeployed when the resource has been allocated.
The resource allocation packages should subscribe to several points in this resource-pool tree. First, they must detect when a new resource pool is created or deleted. Secondly, they must detect when an allocation request is created or deleted. A package may also augment the pool definition with additional parameters, for example, an IP address allocator may wish to add configuration parameters for defining the available subnets to allocate from, in which case it must also subscribe to changes to these settings.
Installation
The installation of this package is done as with any other package, as described in the NSO Packages section of the Administration Guide.
Data Model for Resource Allocator
The API of the resource allocator is defined in this YANG data model:
grouping resource-pool-grouping {
leaf name {
tailf:info "Unique name for the pool";
type string;
}
list allocation {
key id;
leaf id {
type string;
}
leaf username {
description
"Authenticated user for invoking the service";
type string;
mandatory true;
}
leaf-list allocating-service {
tailf:info "Instance identifiers of service that own resource";
type instance-identifier;
}
container request {
description
"When creating a request for a resource the
implementing package augments here.";
}
container response {
config false;
tailf:cdb-oper {
tailf:persistent true;
}
choice response-choice {
case error {
leaf error {
type string;
}
}
case ok {
// The implementing package augments here
}
}
}
}HA Considerations
Looking at High Availability, there are two things we need to consider - the allocator state needs to be replicated, and the allocation needs only to be performed on one node.
The easiest way to replicate the state is to write it into CDB-oper and let CDB perform the replication. This is what we do in the ipaddress-allocator.
We only want the allocator to allocate addresses on the primary node. Since the allocations are written into CDB they will be visible on both primary and secondary nodes, and the CDB subscriber will be notified on both nodes. In this case, we only want the allocator on the primary node to perform the allocation.
We therefore read the HA mode leaf from CDB to determine which HA mode the current subscriber is running in; if HA mode is not enabled, or if HA mode is enabled and the current node is primary we proceed with the allocation.
Synchronous Allocation
This synchronized allocation API request uses a reactive fastmap, so the user can allocate resources and still keep a synchronous interface. It allocates resources in the create callback, at that moment everything we modify in the database is part of the service intent and fast map. We need to guarantee that we have used a stable resource and communicate to other services, which resources we have used. So, during the create callback, we store what we have allocated. Other services that are evaluated within the same transaction which runs subsequent to ours will see allocations, when our service is redeployed, it will not have to create the allocations again.
When an allocation raises an exception in case the pool is exhausted, or if the referenced pool does not exist in the CDB, commit will get aborted. Synchronous allocation doesn't require service re-deploy to read allocation. The same transaction can read allocation, commit dry-run or get-modification should show up the allocation details as output.
If the HA mode is not set to primary and the synchronization RM API is enabled, the restriction will be enforced, preventing IP or ID allocation and resulting in an exception being thrown to the user.
NSO ID Allocator Deployment
This section explores deployment information and procedures for the NSO ID Allocator (id-allocator). The NSO Resource ID Allocator is an extension of the generic resource allocation mechanism called the NSO Manager. It can allocate integers, which can serve, for instance, as VLAN identifiers. Additionally, it can allocate Odd or Even IDs based on the specified requirements and constraints. Odd/Even ID allocation feature includes an additional parameter named oddeven_alloc, allowing users to specify whether IDs should be allocated as Odd, Even, or Default.
Overview
The ID Allocator can host any number of ID pools, including Odd/Even pools. Each pool contains a certain number of IDs that can be allocated. They are specified by a range, and potentially broken into several ranges by a list of excluded ranges.
The ID allocator YANG models are divided into a configuration data-specific model (idallocator.yang), and an operational data-specific model (id-allocator-oper.yang). Users of this package will request allocations in the configuration tree. The operational tree serves as an internal data structure of the package.
An ID request can allocate either the lowest possible ID in a pool or a specified (by the user) value, such as 5 or 1000.
Allocation requests can be synchronized between pools. This synchronization is based on the ID of the allocation request itself (such as for instance allocation1), the result is that the allocations will have the same allocated value across pools.
The oddeven_alloc feature introduces a flexible way to control how IDs are assigned across various operations. By specifying this parameter, users can choose whether the system should allocate IDs as Odd, Even, or use the Default allocation method. This enhancement provides greater control and predictability in ID assignment, making it especially useful in environments that require structured or sequential ID patterns. The oddeven_alloc parameter can be configured during service creation, tooling RM actions, and non-service ID allocation scenarios. It is fully supported through both the CLI and APIs, including Java and Python, ensuring seamless integration into existing workflows and automation scripts.
The oddeven_alloc parameter introduces flexible ID allocation behavior, allowing users to define how IDs are assigned during various operations. This feature supports three modes of allocation:
Default – IDs are allocated using the system's standard mechanism.
Odd – Only odd-numbered IDs are assigned.
Even – Only even-numbered IDs are assigned.
Examples
This section presents some simple use cases of the NSO presented using Cisco-style CLI.
Security
The NSO ID Allocator requires a username to be configured by the service application when creating an allocation request. This username will be used to redeploy the service application once a resource has been allocated. Default NACM rules deny all standard users access to the /ralloc:resource-pools list. These default settings are provided in the (initial_data/aaa_init.xml) file of the resource-manager package.
It is up to the administrator to add a rule that allows the user to perform the service re-deploy.
The administrator's instructions on how to write these rules are detailed in the AAA Infrastructure.
Alarms
There are two alarms associated with the ID Allocator:
Empty Alarm: This alarm is raised when the pool is empty, and there are no available IDs for further allocation. This alarm is also raised when the available Odd or Even IDs are exhausted for further allocation.
Low threshold Reached Alarm: This alarm is raised when the pool is nearing empty, e.g., there is only 10% or fewer left in the pool. This alarm is also raised when the Even or Odd IDs are running low in available IDs.
CDB Upgrade from Package version below 4.0.0
Since the Resource Manager's version 4.0.0, the operational data model is not compatible with the previous version. In version 4.0.0 Yang model, there is a new element called allocationId added for /Id-allocator/pool/allocation to support sync ID allocation. The system will run the upgrade script automatically (when the Resource Manager of the new version is loaded) if there is a Yang model change in the new version. Users can also run the script manually for Resource Manager from 3.5.6 (or any version below 4.0.0) to version 4.0.0 or above; the script will add the missing allocationId element in the CDB operational data path /id-allocator/pool/allocation. The upgrade Python script is located in the Resource Manager package: python/resource_manager/rm_upgrade_nso.py.
After running the script manually to update CDB, the user must request package reload or restart ncs to reload new CBD data into the ID Pool java object in memory. For example, in the NSO CLI console: admin@ncs> request packages reload force.
The id-allocator-tool Action
id-allocator-tool ActionA set of debug and data tools (contained in rm-action/id-allocator-tool action) is available to help admin or support to operate on RM data. Two parameters in the id-allocator-tool action can be provided: operation, pool. All the process info and results will be logged in ncs-java-vm.log, and the action itself just returns the result. Here is a list of the valid operation values for the id-allocator-tool action:
check_missing_report: Scan the current resource pool and ID pool in the system, and identify and report the missing element for each id-allocator entry without fixing.fix_missing_allocation_id: Add the missing allocation ID for each ID allocator entry.fix_missing_owner: Add the missing owner info for each ID allocator entry.fix_missing_allocation: Create the missing allocation entry in the ID allocator for each ID pool allocation response/id.fix_response_id: Scan the ID pool and check if the allocation contains an invalid allocation request ID, and release the allocation from the ID pool if found. It happens for sync allocation when the device configuration fails after a successful ID allocation and then causes a service transaction fail. This leaves the ID pool containing successfully allocated ID while the allocation request response doesn't existpersistAll: Manually sync from ID pool in memory to ID allocator in CDB.printIdPool: Print the current ID pool data inncs-java-vm.logfor debugging purposes.
Action Usage Example
Note that when a pool parameter is provided, the operation will be on this specific ID pool, and if no pool is provided, the operation will be running on all ID pools in the system.
admin@ncs> unhide debug
admin@ncs> request rm-action id-allocator-tool operation fix_missing_allocation
admin@ncs> request rm-action id-allocator-tool operation printIdPool pool multiServiceNSO IP Address Allocator Deployment
This section contains deployment information and procedures for the Tail-f NSO IP Adress Allocator (ipaddress-allocator) application.
Overview
The NSO IP Address Allocator application contains an IP address allocator that use the Resource Manager API to provide IP address allocation. It uses a RAM-based allocation algorithm that stores its state in CDB as oper data.
The file resource-manager/src/java/src/com/tailf/pkg/ipaddressallocator/IPAddressAllocator.java contains the part that deals with the resource manager APIs whereas the RAM-based IP address allocator resides under resource-manager/src/java/src/com/tailf/ pkg/ipam.
The IPAddressAllocator class subscribes to five points in the DB:
/ralloc:resource-pools/ip-address-pool: To be notified when new pools are created/deleted. It needs to create/delete instances of the IPAddressPool class. Each instance of the IPAddressPool handles one pool./ralloc:resource-pools/ip-address-pool/subnet: To be notified when subnets are added/removed from an existing address pool. When a new subnet is added, it needs to invoke theaddToAvailablemethod of the rightIPAddressPoolinstance. When a pool is removed, it needs to reset all existing allocations from the pool, create new allocations, and re-deploy the services that had the allocations./ralloc:resource-pols/ip-address-pool/exclude: To detect when new exclusions are added and when old exclusions are removed./ralloc:resource-pols/ip-address-pool/range: To be notified when ranges are added to or removed from an address pool./ralloc:resource-pols/ip-address-pool/allocation: To detect when new allocation requests are added and when old allocations are released. When a new request is added, the right size of the subnet is allocated from theIPAddressPoolinstance and the result is written to the response/subnet leaf, and finally, the service is redeployed.
Examples
This section presents some simple use cases of the NSO IP Address Allocator. It uses the C-style CLI.
Security
The NSO IP Address Allocator requires a username to be configured by the service applications when creating an allocation request. This username will be used to redeploy the service applications once a resource has been allocated. The default NACM rules deny all standard users access to the / ralloc:resource-pools list. These default settings are provided in the (initial_data/ aaa_init.xml) file of the Resource Manager package.
Alarms
There are two alarms associated with the IP Address Allocator:
Empty Alarm: This alarm is raised when the pool is empty, and there are no available IPs that can be allocated.
Low Threshold Reached Alarm: This alarm is raised when the pool is nearing empty, e.g., there are only 10% or fewer separate IPs left in the pool.
The ip-allocator-tool Action
ip-allocator-tool ActionA set of debug and data tools contained in the rm-action/ip-allocator-tool action is available to help the admin or support personnel to operate on the RM data. Two parameters in the ip-allocator-tool action can be provided: operation, pool. All the process info and the results will be logged in ncs-java-vm.log, and the action itself just returns the result. Here is a list of the valid operation values for the ip-allocator-tool action.
fix_response_ip: Scan the IP pool to check if the allocation contains an invalid allocation request ID, and release the allocation from the IP pool, if found. It happens for sync allocation when the device configuration fails after a successful IP allocation and then causes a service transaction to fail. This leaves the IP pool to contain successfully allocated IP while the allocation request response doesn't exist.printIpPool: Print the current IP pool data in thencs-java-vm.logfor debugging purposes.fix_missing_allocation: Create the missing allocation entry in the IP allocator for each IP pool allocation response/IP.persistAll: Manually sync from IP pool in memory to IP allocator in CDB.
Action Usage Example
Note that when a pool parameter is provided, the operation will be on this specific IP pool.
admin@ncs> unhide debug
admin@ncs> request rm-action ip-allocator-tool operation fix_response_ip pool multiService
admin@ncs> request rm-action ip-allocator-tool operation printIpPool pool multiService
admin@ncs> request rm-action ip-allocator-tool operation fix_missing_allocation pool multiService
admin@ncs> request rm-action ip-allocator-tool operation persistAll pool multiServiceNSO Resource Manager Data Models
This section covers the NSO Resource Manager data models.
Further Reading
The NSO Packages section in the NSO Administration Guide.
The AAA Infrastructure section in the NSO Administration Guide.
Last updated
Was this helpful?