Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Introduction to Address Pool Manager

SUMMARY Use this guide to configure and manage Address Pool Manager.

Introduction to Address Pool Manager

Juniper Address Pool Manager (APM) is a cloud-native, container-based application running on a Kubernetes cluster that manages IPv4 address pools in a network. It automatically provisions prefixes from a centralized address pool to broadband network gateways (BNGs) before the BNGs deplete their address pools. The BNGs add the supplied prefixes from APM as new pools to a linked address pool. A linked address pool and the pool's associated attributes (utilization, threshold, and so on) is called a pool domain.

BNG constantly monitors the domain’s free addresses against the domain's thresholds as follows:

  • BNG sends an alarm to APM requesting additional addresses when the number of free addresses in the domain reaches or drops below the domain’s apportion-threshold.

  • APM allocates the requested number of pool prefixes matching the requested prefix length and returns the addresses in the alarm response.

  • When the number of free addresses in the domain reaches or exceeds the domain’s reclaim-threshold, the BNG selects a pool prefix to remove. It also raises an alarm to APM requesting reclamation.

  • APM responds to the reclamation alarm by instructing the BNG to place an active-drain on the pool. Once the pool has completely drained (no allocated addresses), the BNG raises a pool-drained alarm.

  • APM informs the BNG that the prefix is returned to the domain’s source partition and that the BNG can safely remove the pool prefix from the domain.

  • The reclaimed prefix is now available for another BNG to request.


The term BNG in this document also applies to the BNG CUPS Controller.

Figure 1 shows a high-level view of APM operations to monitor BNGs and provision them with the addresses they need, when they need them.

Figure 1: Basic APM Operations Basic APM Operations

APM provides an address management solution that helps network operators efficiently allocate IPv4 addresses. Typical address allocation schemes are complex and not as efficient as network operators need. Providers typically preprovision addresses on network devices to handle the worst-case load in an attempt to prevent devices from running out of addresses. This means that the devices are over-provisioned for most of their operating time.

APM does not pre-provision addresses, because the addresses might never be needed and could be used elsewhere. Instead of preprovisioning, APM allocates prefixes only when the BNG needs them. Specific network considerations that can affect the timely and efficient allocation of addresses include:

  • Number of network devices that consume addresses

  • Presence of VPNs

  • System redundancy schemes

  • Geographic distribution of network elements

APM reclaims prefixes to continually adjust the distribution of prefixes and to maximize address space utilization. Prefix reclamation occurs on APM, whereas address reclamation occurs on the BNG. Prefix reclamation happens when the BNG has a surplus of IP addresses. The BNG sends a reclaim alarm to APM with a suggested pool prefix to reclaim. APM initiates a drain request on the pool to ensure that the pool is free of any address allocations before APM reclaims the pool prefix. APM can then reallocate the prefixes to other pools among its managed BNGs when those BNGs near address exhaustion and need more addresses.

Benefits of Address Pool Manager

  • Efficiency—Improves the efficiency of address utilization. APM centralizes and automates address allocation for multiple BNGs in the network. APM uses just-in-time prefix allocation, so that it provisions prefixes only when a BNG needs additional IP addresses.

    APM provisions only as many prefixes as the BNG needs. After you partition the APM global pool into groups of prefixes, APM further subdivides the prefixes to match the BNG’s request. This subdivision enables APM to optimize the size of the prefixes that it allocates.

  • Simplicity—Avoids the overhead and complexity of manual monitoring and provisioning individual BNGs.

  • Deployability—Installs and operates on any hardware that meets the requirements.

  • Reclaimability—Reclaims the unused prefixes from pools that are using few IP addresses to a central pool and redistributes those prefixes to other pools that need them.

Addressing Terminology

You should have a good understanding of IP addressing, classless inter-domain routing (CIDR), variable-length subnet masks (VLSMs), and how to subdivide IP prefixes into subnetworks (subnets). When you devise your addressing strategy (outside the scope of this documentation) or use manual address reclamation, you might find it helpful to see an IP subnet calculator. You can find many such calculators online.

We use the following terminology in this documentation:

  • Prefix—A 32-bit IPv4 network address and prefix length expressed using CIDR notation; for example, A prefix defines the network portion of an IP address. A prefix represents a subnetwork.

  • Prefix length—The number of bits that determines the length of the prefix and the size of the network portion of an IP address. A /24 prefix length means that the network portion of the address is 24 bits long. The remaining bits (out of 32) represent the host portion of a network address. For a prefix with a /24 prefix length, the host portion is 8 bits: 32 – 24 = 8.

  • Network size—This term is sometimes used to mean several different things depending on the context, which can lead to ambiguity. We describe the prefix length and how it corresponds to the number of host addresses in subnetworks as follows:

    • A longer prefix, determined by a longer prefix length, corresponds to more subnetworks with fewer host addresses to allocate per subnetwork.

    • A shorter prefix, determined by a shorter prefix length, corresponds to fewer subnetworks with more host addresses to allocate per subnetwork.

  • Free addresses are IP addresses that are available and have not been assigned to subscribers.

How APM Works

APM maintains a centralized collection of IP prefixes for a group of BNGs in the network. The APM CLI refers to the managed BNGs as entities. This document generally uses the term BNG, but in some cases this document uses the term entity.

APM coordinates the creation of pool domains with the BNG. Each pool domain corresponds to a linked address pool for a given routing instance combination on the BNG. Also, on a BNG CUPS Controller, a pool domain corresponds to a linked address pool for a given subscriber group and routing instance combination. As pool domains are created dynamically, both the BNG and APM maintain profiles or templates containing attributes necessary to instantiate a pool domain. The APM profile contains attributes such as apportion, reclamation thresholds, and auto-reclamation behavior. The BNG. profile contains attributes such as prefix size and discard route installation behavior.

APMi version 1 (compatible with Junos OS Release 22.1R1 and later). You can check the APMi version by running the show apm entity command.

Thresholds and Alarms

The BNG creates the pool domain and monitors the number of free addresses in the pool domain. When the number of free addresses crosses a threshold value, the BNG sends an alarm message to APM. The BNG monitors the number of free addresses against the following thresholds:

  • Apportion threshold—When the number of free addresses reaches or falls below this value, the BNG runs the risk of running out of addresses. The BNG sends an apportion alarm to APM requesting more addresses. APM selects an available prefix to apportion and allocates the prefix to the BNG, BNG adds one or more prefix as a new pool in the pool domain. Failure to allocate a prefix (for example; an empty partition) results in a negative response. The retry time is set to a timestamp that is 15 minutes from the time of receiving the request. If the BNG still needs prefixes for the domain, it retries at the provided timestamp value.
  • Reclaim threshold—When the number of free addresses reaches or rises above this value, the BNG has a surplus of addresses. The BNG sends a reclaim alarm to APM with a suggested pool to drain. Depending on the configuration, APM may initiate a drain on the pool. A drained pool has no IP addresses within the pool being used by a subscriber.

    During the drain, the BNG router stops assigning addresses from the pool and waits for subscribers to log off to free up those addresses.

    After draining the pool, the BNG sends the pool drained alarm to APM. APM sends a message to the BNG router to delete the pool from the pool domain.


    APM initiates the reclamation process on the pool when:

    • Automatic reclamation is enabled for the pool domain.
    • Reclamation is allowed at the current time period.

    If APM cannot process the reclamation alarm because the auto-reclamation was outside the window, APM responds with a ALARM_NACK/NOOP and a retry time that is set to the second that the auto-reclamation window begins.

You configure the apportion threshold and reclaim threshold values in the pool domain profile. The thresholds determine whether there are enough free addresses for the BNG and when APM should allocate or reclaim prefixes. Consider the following fictional timeline in Figure 2. BNG assigns addresses to subscribers when they log in and reclaims the addresses when they log out. The timeline shows the number of free addresses as tracked by the BNG over a period of time. Table 1 describes the actions taken by the BNG and APM for different scenarios as the number of free addresses crosses different thresholds.

Figure 2: Free Addresses on a BNG Free Addresses on a BNG
Table 1: Action Taken by APM for Different Alarms
Time Alarm Sent by BNG Description
t0 Start of the timeline with a populated pool domain.
t1 Apportion alarm As subscribers log in, the number of free addresses on the BNG falls below the apportion threshold. The BNG sends an apportion alarm. APM receives the apportion alarm and allocates prefixes to the pool domain. The BNG allocates addresses from the pool domain's pool prefixes.
t2 Apportion alarm

APM receives the apportion alarm, but the partition has no available prefixes. The alarm is NACKed and a retry timestamp is set to 15 minutes later. The BNG retries the apportion alarm at this timestamp unless it no longer needs the addresses.

t3 Apportion alarm At the retry timestamp, BNG resends the apportion alarm since the number of free addresses is still below the apportion threshold.
t4 Reclaim alarm Subscribers continue to log out until the number of free addresses rises above the reclaim threshold. The BNG sends the reclaim alarm with the suggested pool to be reclaimed. APM places a drain on the suggested pool and the BNG starts the drain process on the pool.
t5 Pool-drained alarm When the address pool has zero subscribers, there are no allocated addresses in the pool. BNG sends the pool-drained alarm to APM. APM responds to the pool-drained alarm with a delete request. The BNG removes the pool from the pool domain's list of pools. APM moves the corresponding prefix back to the partition for reallocation.

The number of free addresses drops upon removal of the pool.

t6 Reclaim alarm APM receives the reclaim alarm, but does not take any action because the alarm occurred outside of the reclamation window. APM returns an alarm NACK with a retry timestamp set to the time of the beginning of the reclamation window. The BNG retries the reclamation alarm at this time if there's still a surplus of free addresses.

General Operation of APM

The following steps explain the general operation of APM:

  1. The BNG and APM communicate using the APMi, Juniper-defined gRPC-based protocol. Google RPC (gRPC) is common framework for building extensible and interoperable communication protocols. Upon initial connection, the BNG initiates pool domain synchronization. The pool domain synchronization process synchronizes the set of pool domains that are active. APM aligns the list of active pool domains with the BNG’s list of pool domains. After pool domain synchronization, the BNG runs pool synchronization (discovery) for each pool domain. APM aligns the list of pools for each domain with the BNG’s list. If APM has retained any additional pools (not in BNG’s list of pools for the domain), the pool prefixes are released to the partition. If APM is missing pools, APM attempts to allocate pools.
  2. APM monitors alarm messages sent by the BNG.

  3. APM evaluates and acts on the alarm. For example, if a BNG is running out of addresses, the BNG sends an apportion alarm to APM. APM allocates the requested number of prefixes from the domain's source partition and returns them in the alarm response. The BNG adds these pool prefixes to the pool domain.

Figure 1 shows a more detailed view of the relationships among the various functional components of a single APM instance. Each manager block shows the database tables it uses.

Figure 3: Functional Components of APM Functional Components of APM

You can run multiple instances of APM simultaneously on multiple different clusters in the network. These instances of APM are independent and unaware of each other. The instances do not share state or configuration.

Each APM instance includes the following microservices as functional components of the application:

  • Entity manager —Orchestrates the activities of pool management for the BNGs under management. These activities include processing alarms, and allocating and reclaiming pool prefixes.

  • Address manager—Organizes the central pool of addresses into partitions and manages the allocations of the root prefixes configured in each partition. It subdivides the root prefixes into smaller prefixes and allocates the prefixes according to the configured criteria for the BNG.

  • Provisioning manager—Interfaces with the BNG to provision pool domains and their associated address pools. The provisioning manager ensures that the domains and the associated allocated pool prefixes remain synchronized between APM and the BNG.

    The APM provisioning manager communicates with the managed BNGs using the APMi. The provisioning manager sends gRPC messages to directly provision and deprovision prefixes on the BNGs in response to domain alarms initiated by the BNG.

  • The MGMT microservice provides a text-based configuration schema and CLI so that you can configure the global prefix pool, the managed BNGs, and their associated pool domain attributes. You can use the CLI to display statistics and state for various functional components. The output provides information about system load, efficiency, utilization, and errors or abnormal conditions.
  • Broadband Edge (BBE) Event Collection and Visualization (cloud-based centralized utility)—provides a way to capture APM logs that span the life-cycle of APM microservices. The utility collects and stores logs across instances of APM microservices.

  • Fluentd —Collects logs from the address manager, entity manager, and provisioning manager, optionally, exports them to remote syslog collectors such as Broadband Edge Event Collection and Visualization.
  • Database instance (DB)—Provides shared access to database tables that each functional component of APM uses. The database includes tables for address, BNG, and pool domain information. The database provides persistent storage for configuration information and operational states.

    APM employs a database with state information about the entities, pool domains, pools, prefixes, allocations, configuration, and so on. Two database instances, a primary and a standby, deploy in a hot-standby mode. The database instances are monitored by a database sentinel service that detects a failure in the primary database. Upon failure of the primary database, the secondary assumes the role of the primary while a new standby database is restored.


    Redundancy requires a minimum of three worker nodes in addition to the primary node. The worker nodes must all be on separate physical servers. However, the nodes can be either physical or virtual machines.

Functional Components of APM

CLI and Configuration Management

The user interface (MGMT) is a containerized version of the Junos OS management process. With this interface, you can use the same CLI structure as Junos OS for configuration and monitoring. The MGMT also provides an interface that enables you to remotely manage APM.

APM performs the following tasks:

  • Loads the initial APM configuration from the MGMT service into the database before other APM components can proceed to their runtime state.

  • Translates commands and configurations into actions and parameters that the APM microservices understand.

  • Records the initial configuration and subsequent changes in the database for persistence. It notifies APM components about any changes.

Entity Manager

The entity manager coordinates the operations of other functional components, that affect the entity state.

For each BNG under management, the entity manager tracks the following information:

  • The BNG address, which is the transport address of the BNG that hosts managed pools.

  • A list of the pool domains being managed.

A pool domain represents a linked address pool on the BNG. For each pool domain, the entity manager tracks the following information:

  • Pool domain name—A user-defined string that identifies the managed pool for the BNG. Each pool domain name must be unique for that BNG. That means the pool domain name effectively acts as a key; it is sometimes referred to as the pool domain key. A user-defined string constructed by the entity. For BNG, the string consists of the domain-profile name linked with the routing instance name. For the BNG CUPS Controller, the string consists of the domain-profile name linked with the subscriber-group name and routing-instance name.

  • APM uses the format pool-domain-name-sequence-number to name the pools that it creates. The sequence-number is at least 4 digits; if the value is less than 1,000 the sequence number is padded with leading 0's. So 0001, 0999, 1000, 213339 are valid sequence numbers. For example, if the name of a pool domain is test-pd, then APM names the first pool test-pd. It names subsequent pools test-pd-0000, test-pd-0001, and so on.

  • Prefixes—An ordered list of the prefixes that make up the pool domain.

The entity manager collects a number of volatile statistics for various operations (last discovery, last allocation, last reclamation, and so on) on the pool domain. The statistics include the alarm counts, the number of pools, their associated prefixes, and the timestamps. You can display these statistics with APM show commands, such as show apm entity.

The entity manager requests a new prefix for a pool domain from the address manager when the provisioning manager relays the apportion alarm from the BNG to the entity manager.

The prefix request includes the following information:

  • Address family—Currently supports IPv4

  • Allocation key—The IP address and pool domain of the managed BNG

  • Requested prefix length—The size of the prefix that you want to allocate from a partition to a pool domain.

The entity manager subsequently attempts to provision the allocated prefix(es) to the BNG’s address pool.

The entity manager begins a process to discover and to reconcile the BNG pool domains (Sync) under management when the provisioning manager notifies the entity manager that a BNG is reachable. The provisioning manager sends a reachability report to the entity manager whenever the reachability state changes. The entity manager requests discovery of all pool domains managed for that BNG.

The discovery process uses the provisioning interface to find the pool domains and the associated pool information as known by the BNG. At the end of the discovery process, APM and the BNG have the same pool domains and allocated pool prefixes.

If the discovered information does not match the existing information, then APM updates its databases with the partition information for pool domains (to match the BNG). If APM discovers a conflict during the update, it flags the conflict as a warning in the log.

Address Manager

The address manager uses a VLSM algorithm to subdivide the root prefixes in the address pool partitions into smaller sub-prefixes up to the max-prefix-len value that you configured for each root prefix. During apportionment, the address manager matches a request for an appropriately sized prefix to a partition and a root prefix. APM allocates a free sub-prefix from the root prefix to satisfy the apportioning event.

The address manager logs a warning message if the percentage of free addresses within a partition drops below the free-prefix-utilization threshold. The crossing of that threshold indicates that the partition is in danger of running out of addresses because it has allocated so many addresses.

When you configure APM, you assign root prefixes to a partition. The address manager apportions prefixes from only a single partition for any domain. Each partition represents an allocation context. The address manager uses the bias that you configure for the domain to select the partition from which it subdivides prefixes for allocation to the domain.

When you add a root prefix to a partition, make sure it fits within the specified minimum and maximum prefix length limits for that partition:

  • The min-prefix-lenvalue is the shortest valid root prefix.

  • The max-prefix-lenvalue is the longest valid root prefix.

Thus, min-prefix-len <= root prefix length <= max-prefix-len.

For example, if min-prefix-len is 20 and max-prefix-len is 24, you can add a root prefix with prefix lengths of /20, /21, /22, /23, or /24.

The smaller the prefix length, the more individual host addresses available in the subnet. The larger the prefix length, the fewer individual host addresses available in the subnet. For example:

  • A prefix length of /20 provides 4,094 usable host addresses.

  • A prefix length of /24 provides 254 usable host addresses.


If you configure a root prefix that is outside the specified limits, APM does not add it to the partition.

Prefix Subdivision

The goals of prefix subdivision enable APM to share a root prefix among several domains and to allow domains to grow in smaller increments. The address manager uses a VLSM algorithm to subdivide root prefixes in a partition during configuration. Each subdivision is a subnetwork (subnet).

You can control how deeply the address manager subdivides a root prefix by specifying the maximum allowed prefix length. The value of max-prefix-length is the longest prefix allowed for a subnet. Consequently, this configuration determines the minimum number of host addresses that an allocated prefix must provide.

Prefix Allocation

The address manager can allocate any particular prefix to only one domain. Prefix allocation depends on the domain’s bias information and the requested prefix size.

The address manager makes a best-effort attempt to match the requested prefix size (preferred-prefix-len) when it allocates a prefix. The partition might not have any prefixes left that match the requested length. For example, when the address manager allocates a superior prefix to a pool, it also allocates all of its subordinate prefixes to the pool.


VLSM creates a hierarchy of subnets from a root prefix. It subdivides the root prefix by adding bits to the prefix length. Each bit added to the prefix length creates another subordinate level of subnets with the following property:

  • Each level has twice as many subnets as the next higher level.

  • Each level has only half as many host addresses per subnet as the next higher level.

Each root prefix and its associated subnet hierarchies constitute a prefix tree. A partition, therefore, consists of a collection of prefix trees. The address manager can allocate only a prefix that fits somewhere within one of these prefix trees.

Prefixes might be in one of the following states:

  • Available—The prefix is available for allocation to a domain.

  • Allocated—The prefix is already allocated to a domain and an entity.

  • Reserved—The prefix is administratively reserved with the reserved-prefix statement. APM cannot allocate the prefix to a domain that does not match the requesting domain.

VLSM Example

Figure 4 shows a hierarchy for the root prefix in the partition test-1. You can see that the number of subnets doubles for each bit added to the prefix length, from one subnet for /24 to eight subnets for /27. The number of usable addresses per subnet is halved for each additional prefix length bit, from 254 addresses for /24 to 30 addresses for /27.


Each prefix block in the diagram shows usable addresses:

Usable addresses = Total number of addresses – 2

The two excluded addresses correspond to the lowest address (the network address) and the highest address (the multicast address).

Figure 4: VLSM Subnet Hierarchy Example VLSM Subnet Hierarchy Example

Consider the following scenario with this root prefix tree:

  1. The address manager receives an allocation request with a preferred prefix length of 25.

  2. The address manager looks for a /25 prefix that includes the address. matches and is selected if it is available.

What happens if is not available? This means that is also unavailable. The address manager looks for another /25 prefix.

The address manager selects if it is available. If that prefix is not available, then the address manager tries to allocate a /25 prefix from a different root prefix.

Provisioning Manager

The provisioning manager consists of worker processes that manage the following provisioning operations:

  • Discovery—Synchronizes the pool domains and the associated pool information between APM and a BNG. At the end of the discovery process, APM and the BNG agree on the list of pool domains and allocated pool prefixes.

    APM behavior—APM reconciles its pool domains with the BNG’s list such that the APM list matches the BNG's list. The pool prefixes for domains that are deleted during reconciliation have their associated pool prefixes returned to their original partition.

    The provisioning manager performs discovery whenever APM establishes a connection with the managed BNG, including a reestablished connection after a connection failure. While the connection is down, an administrator could change the configuration on the BNG. APM adjusts accordingly if it detects a change during the subsequent discovery.

  • Provisioning—Provisions and deprovisions prefixes on a managed BNG. While the address manager manages the allocation of prefixes, the provisioning manager communicates with the BNG to provision the address pool.

When the connection is restored, the provisioning manager notifies the entity manager that the BNG is reachable. The entity manager requests the provisioning manager to start the synchronization process.

How Prefix Reclamation Works

Address reclamation on the BNG recovers the underutilized provisioned prefixes from the device address pools and returns the prefixes to APM’s centralized pool. APM can then reallocate these prefixes as needed to other pools that are nearing address exhaustion. This means that the distribution of prefixes continually adjusts to maximize address space utilization and efficiency.

Reclamation is the process of reclaiming pool prefixes from a BNG's pool domain when the BNG has a surplus of free addresses. You set the reclaim threshold value in the pool domain profile configuration. You then reference the pool domain profile in the entity configuration on APM.

The BNG monitors the free-address count for each of its pool domains. When the free-address count reaches the reclaim threshold, the BNG is considered to have a surplus of addresses. The BNG sends a reclaim alarm to APM with information identifying a suggested pool to be reclaimed. The reclaim alarm drives the automatic reclamation process. Alternatively, you can initiate a manual reclamation process.

Reclamation consists of draining a pool and then recovering the prefixes from the pool, as explained here:

  • When APM initiates a drain, it sends a message to the device to begin actively draining the pool. This means that no new subscribers are allocated from this pool. For connection-based access model subscribers (for example PPP), an active drain triggers an immediate logout and re-connect. For lease-based subscribers, an active drain causes the lease-renewal to be rejected. For both models, the net result is the subscriber re-connects but is allocated an address from another pool in the domain.

  • The pool is completely drained when there are no subscribers using an address in the pool. All addresses in that pool are free. The BNG sends a pool-drained alarm message to APM.

APM can perform address reclamation by either of the following methods:

  • Automatic—You can configure reclamation to be an entirely automatic process that occurs when APM receives a reclaim or pool-drained alarm. You can specify the process to begin immediately, or to take place only during a specific time window, or to wait a period of time before acting on the alarm.

  • Manual—You use show commands to display the alarms for individual pools on the BNG. You then issue request apm commands to drain addresses from a pool, deprovision the drained pool, and recover its addresses.

Automatic Reclamation of Prefixes

You can enable APM to automatically handle the task of reclamation. You can configure automatic reclamation in the pool-domain-profile assigned to the entity as configured in the entity-match statement.

When you enable automatic reclamation, these actions take place:

  • APM responds to domain reclamation alarms sent by the entity. The reclamation alarm contains a suggested pool name to reclaim.

  • APM responds to the reclamation alarm by instructing the entity to place an active-drain on the pool. When the pool has completely drained (no outstanding address allocations from the pool), the entity raises a domain pool-drained alarm.

  • APM responds to the pool-drained alarm by instructing the entity to delete the pool; APM returns the pool prefix to the partition from which it was allocated.

  • Once the prefix has been returned to the partition, it is available to other entities raising domain apportion alarms.

Auto-reclamation allows you to limit the number of unused addresses maintained on the entity. Because the auto-reclamation process involves a potentially service impacting active-drain, you can configure APM to only initiate auto-reclamation during a configured maintenance window.

Releasing Allocated Prefixes for an Entity

In the event that a network entity should fail and is unable to reconnect with APM to allow any allocated pool prefixes to be reclaimed to their source partitions, you can use the request apm release entity system-id command. This command deallocates all pool prefixes and pool domains associated with a network entity. You cannot use the request apm release entity system-id command if the entity's APMi state is reachable.

Use these steps for releasing prefixes from an unreachable entity.

  1. Use the show apm entity system id command to display the entity's reachability status and the pool prefixes held by its pool domains. the output shows that the entity is reachable and has allocated 3 pool prefixes.
  2. The request apm release entity system id command is unsuccessful when the entity is reachable.

  3. Enter the show apm entity to see if the entity is unreachable.

  4. As the entity in Step 3 is unreachable, you can enter the request apm release entity system-id command to begin reclamation. APM deprovisions the pool and returns the addresses to the source partition for reallocation. All the pool prefixes that were reported in Step 1 are released.

Manual Reclamation of Addresses

Manual reclamation gives you fine-grained control. Manual reclamation requires you to closely monitor the pool domains and address pools on your managed BNGs.

  1. Use the show apm alarms command to display all pending alarms received from the BNG. The output displays the names of pools with the reclaim alarm status.

    The reclaim alarm means that the pool domain has a surplus of addresses. The Info field contains the name of a pool that the BNG recommends for reclamation. A reclaim alarm does not mean that the pool has an active drain set. If a drain is not in place on the pool, the pool could still allocate addresses.

  2. Issue the request apm drain command to begin draining the pool.

    You can remove a drain that you have initiated by issuing the request apm activate command.

  3. Use the show apm alarms command to see that the pool has been drained. The alarm status displays the pool-drained status.
  4. Issue the request apm reclaim command to begin reclamation. APM deprovisions the pool and returns the addresses to the source partition for reallocation.

When you choose manual reclamation, be careful in choosing the pool to reclaim. Here are some of the considerations for choosing a pool to reclaim.

  • When you drain a pool, you must accommodate the subscribers using those addresses in other pools in the pool domain. There must be enough free addresses in the other pools (in the domain) to absorb these subscribers. Therefore, the number of free addresses in the pool domain must be greater than the number of used addresses in the pool that you drain:

    (pool domain free addresses) –(drain pool free addresses) > (drain pool used addresses)

  • When you drain a pool, you must not leave the pool domain in immediate danger of running out of free addresses. If the free address count in the domain falls below the apportion threshold, it triggers an apportion alarm that results in APM provisioning more addresses for the pool. In other words, try not to initiate a drain on a pool unless the following inequality holds true:

    (pool domain free addresses) – (drain pool total addresses) > (apportion threshold)


You use the show apm entity command to monitor APM’s reclamation operations. The command output shows timestamps for the last discovery, last allocation, and last reclamation events when you display statistics for a router or a specific pool domain. The timestamps are in ISO-8601 format with a 24-hour clock:


  • T is the delimiter between the date and the time.

  • Z indicates that the time is in the UTC time zone. If the router time uses a different time zone, the format shows the offset from UTC to identify the time zone.

  • Time zones west of UTC have a negative offset, designated by –hh:mm.

  • Time zones east of UTC have a positive offset designated by +hh:mm.

For example, the following timestamps all show the same time, assuming standard time:

  • 2020–03–20T15:10:25Z (London)

  • 2020–03–20T10:10:25-05:00 (New York)

  • 2020–03–20T16:10:25+01:00 (Paris)

  • 2020–03–20T23:10:25+08:00 (Beijing)

APM and Kubernetes

APM operates in a Kubernetes cluster environment. APM is a containerized application that is packaged with Docker. Kubernetes is the orchestrator for the containers. It groups containers into logical units (pods) that simplify management. The APM command and CLI simplify the interactions with Kubernetes.

With Kubernetes, you can automatically restart APM microservices. Because Kubernetes deploys the microservices as replica sets, it can ensure that the pod with the microservice restarts if the pod fails. At initial deployment and upon restart, the service pod checks that the configuration has completed loading. The service pod also verifies that it can connect to the database and the message broker. Upon successful confirmation, the APM service starts.

Kubernetes provides redundancy for the APM functionality, because it distributes and manages the application containers across a cluster that consists of multiple node machines—one primary and several workers:

  • The primary node controls the workers. It provides a control plane for decision making and cluster management. You communicate with the primary node when you interact with the cluster. A set of processes run on the primary node to implement the primary node functions.

  • Worker nodes do the work of the APM application. Each worker node must be on a physically separate platform from other worker nodes. If you use virtual machines (VMs) to host nodes, the VMs must be on different physical servers.

    If a worker node fails, the Kubernetes service that is running on the primary node detects the failure. It reschedules the services that were running on the failed node to other worker nodes in the cluster.


    The database service used by APM requires at least three physical worker nodes to provide high availability for the application.

Replication provides database redundancy. The primary database instance duplicates to one replica database instance. Each instance is a separate pod. An odd number of database sentinel instances monitor the primary and replica database instance. When a sentinel detects a failure of the primary instance, a majority of the sentinels must agree. Then a majority of the sentinels must elect the replica instance to promote to the primary role. If the previous primary instance recovers, it assumes the role of a replica instance.

APM-Provisioned Kubernetes Objects

APM creates the following Kubernetes objects during start or rollout. APM uses these objects throughout its life cycle. The objects are removed on apm stop.

  • Namespace—Virtual cluster of node machines that are running APM. All APM objects are isolated in the jnpr-apm.

  • External-Services—Objects are created at setup time to obtain the external IP address assigned by the cluster’s load balancer (ingress controller). External services outside the cluster use these external IP addresses to initiate communication with APM. If the cluster does not support a network load balancer, the cluster uses the primary node as the external IP address.

  • ConfigMap—Stores the configuration file for the database server (redis.conf) and an initial configuration file (juniper.conf) for MGMT.

  • PersistentVolumeClaims—For containers that have dynamic data storage requirements. This object includes MGMT and the database deployments.

  • Secrets—Stores keys and certificates that you need to secure the APMi.