Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

APM Installation

APM Installation Overview

Juniper Address Pool Manager (APM) is an automated, centralized, container-based cloud-native application that network operators and administrators use to manage IP address resources. APM works with managed broadband network gateways (BNGs) to monitor address pools on BNGs. When the number of free addresses drops below a set threshold, the BNG raises an alarm. The alarm triggers APM to allocate unused prefixes from its global list of prefixes and provision a subset of the prefixes to the BNG as new pools.

Note:

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

You can deploy APM on any hardware that meets the requirements. The following sections describe:

  • APM installation requirements

  • How to install APM

  • How to adjust APM setup parameters

APM Installation Requirements

To install APM, you need the following hardware and software:

APM Requirements

APM installs on a Kubernetes cluster comprised of physical or virtual machines (VMs). For availability, you must have at least three nodes in the cluster. APM requires the following minimal resources from the Kubernetes cluster:

Table 1: Cluster Requirements
Category Details

Storage

Storage Class or PVs capable of backing 100 mebibytes (MiB) RWX PVC for configuration

Network load balancer addresses

One APMi

Node port address

One for optional CLI/SSH access

Container/registry storage

Container/registry storage 2.5 gibibytes (GiB)

Worker node resource consumption (specification):

Ubuntu version 22.04 LTS or later

Number of VMs or physical systems: 3

APM resource consumption on each Worker node:

  • CPU: 4 cores

  • Memory: 2 gibibytes (GiB)

  • Storage: 2.5 gibibytes (GiB)

Jump host

  • Ubuntu version 22.04 LTS or later

  • CPU: 1 cores

  • Memory: 8 gibibytes (GiB)

  • Storage: 128 gibibytes (GiB)

  • Python3-venv installed
Node specification

  • Ubuntu 22.04 LTS

  • CPU: at least 8 cores

  • Memory: 64 GB memory

  • Storage: 512 GB storage partitioned as 128 GB root(/), 128 GB /var/lib/docker, and 256 GB /mnt/longhorn(application data)

This specification establishes a cluster that can run APM as well as its companion applications such as BBE Event Collection and Visualization and BNG Controller simultaneously.

Additional Requirements

The BNG is a Juniper Networks MX Series router, a Juniper BNG CUPS Controller (BNG CUPS Controller). We recommend that the BNG is running Junos OS Release 23.2R2-S2 or later when using PPP or L2TP subscriber-access models and 23.4R2 for all access models (DHCP inclusive).

For APM, confirm that you have a juniper.net user account with permissions to download the APM software package. Download and install the APM software from a machine that will not be part of the Kubernetes cluster.

Install APM

SUMMARY Use this procedure to install APM for the first time.

Before you begin, confirm that you have met the requirements for the APM installation.

We recommend that you use a secure connection between APM and the BNG.

Note:

See the BBE Cloudsetup Installation Guide for instructions on installing BBE Cloudsetup facility and building the Kubernetes cluster. Use the apm setup [--bbecloudsetup] to install and to build your cluster. All the defaults align with BBE Cloudsetup if you use the bbecloudsetup option. If you don't use the bbecloudsetup option with setup, then you need to have the following information when you start the APM installation:

  • Kubernetes registry location
  • Registry name
  • Registry port
  • Name of the persistent volumes used for configuration files and database storage.
  • Syslog server/BBE Event Collection and Visualization address and syslog server port

  • Security key and certificate:

    We recommend that you secure the connection between APM and the BNG with TLS. Each side of a TLS-secured connection requires a private-key/signed-certificate pair. In order for each side of the secured connection to authenticate the other, we recommend that each certificate is signed by the same Certificate Authority (CA). Since the BNG identifies APM by its IP Address, you must include APM’s external IP address as a Subject Alternative Name (SAN) in APM’s certificate. You obtain APM’s external IP address by issuing the $ apm ip --context contextName --detail command.

Note:

Do not alter the default syslog configuration that comes with the APM factory-default configuration. This is used to facilitate the export of APM log data to Broadband Edge (BBE) Event Collection and Visualization.

Install the APM Application

  1. Download the APM software package from the Juniper Networks software download page to the jump host.

    APM is available as a compressed tarball image (.tgz). The filename includes the release number as part of the name. The release number has the format: <Major>.<Minor>.<Maintenance>

    • major is the main release number of the product.
    • minor is the minor release number of the product.
    • maintainance is the revision number.
  2. Unpack the APM tarball (.tgz) file on the jump host by entering:
  3. Run the loader script after you unpack the tarball.
  4. Use the sudo -E apm link --context contextName --version apmSwVersion command to link to the cluster. The link command associates the loaded APM software package to the cluster in preparation for the setup.

    • contextName is the Kubernetes context (cluster name).

    • apmSwVersion is the software version.

  5. If you are using a secure registry (such as a bbecloudsetup-created cluster), authenticate with the registry by issuing a docker login as the system user (the system/user supplied in the bbecloudsetup cluster configuration file) to the cluster's registry transport address (the FQDN supplied as the system/address in the bbecloudsetup cluster configuration file).
  6. Run setup to configure your installation.

    • contextName is the Kubernetes context name. In a multiple geographically located APM installation, each context name must be different.

    • update prompts for only missing values (primarily used after loading a new software release).

    • bbecloudsetup uses the default values provided with the charts (default values align with a BCS2-created cluster).

    • host:port is a hostname or IP address of the cluster (any of the cluster’s nodes) and open port and also to use for ssh access to the CLI.

    • config config-file-name is the configuration file to use for setting up APM.

    Note:

    You can use an initial configuration file to start and roll out APM. You use the configuration file through the –-config config-file-path switch on the utility script’s setup command.

    When APM is started or rolled out, the configuration file that you supply during setup is used to initialize APM. If you do not supply a configuration file, APM starts with the factory defaults.

    The supplied configuration file is stored on the jumphost’s context repository. This allows the configuration to be preserved across APM start and stop events. Commits to the initial configuration are not automatically saved to the persistent location on the jumphost. To update the configuration at the persistent location, use the utility script’s save-config command.

    Using the save-config command ensures that the latest configuration is used the next time that APM is started and rolled out. In order to restore the initial configuration back to its factory default, enter setup interactively and enter ^d to the startup config ... question.

    The action in the parenthesis changes to remove. Press Enter to accept the removal of the deployed configuration. APM reverts back to the factory default configuration after a stop and then rollout command sequence.

    When you change the initial configuration file using the utility script’s setup command, you must perform a stop and then rollout command sequence for the change to take effect.

    The setup command does the following:

    • Loads the container images to the local Docker repository.

    • Collects information about the cluster environment such as; Names of storage class or persistent volumes, location of a container registry, container/pod name of registry, any TLS key information, and so on.

    • Initializes the APM configuration.

      If you did not use the bbecloudsetup option with the setup command, you need to complete these prompts during the setup:

      • Provide storage class and name of storage class.
      • Export logs to a syslog server. If you enter Y, you are prompted to provide syslog server/BBE Event Collection and Visualization address and syslog server port.
      • Enter the name for the persistent volume if the storage class is not specified. The setup script verifies that the persistent volume is of sufficient size to support the log file size and the number of files. If you use storage class then you don't need the persistent volume.
  7. Verify the APM installation apm version --context contextName [--detail] .

    • contextName is the Kubernetes context

    • detail detail adds information about available releases in the software repository.

  8. Verify that all the objects are in present or bound state. Use the apm ip command to verify the status.

    • contextName is the Kubernetes context (cluster names) to run the command with

    • detail adds the exposed port information.

Start APM

SUMMARY Use this procedure to configure and to start APM.

  1. Enter rollout to start the APM installation. The APM utility allows you to rollout different software versions for all microservices that are part of APM. You need to use the rollout command with sudo/as root. The rollout command also validates that all the values needed for the new releases are present and loads the new release container images to the registry. Use sudo -E apm rollout --context contextName [--version software release] [--service Servicename] to start APM services. For example:

    • contextName is the Kubernetes context (cluster names).

    • version software release is the software release to rollout (defaults to the release that links to the cluster).

    • service Servicename is the microservice name to rollout (cfg-man, addr-man, ent-man, log-man, debug-man, prov-man).

    Note:

    On the first rollout -–service is not required. The -–service is used with the –-version to rollout/upgrade specific versions of specific services.
    Note:

    By default, APM starts from factory-default. The configuration is reset to its initial state. Any persistent state database (DB) and any persistent logs are cleared.

  2. Enter apm status --context contextName [-o|--output json] [--detail] to verify that the APM services are up and running. For example:
    Note:

    Collect the logs for a service and contact the Juniper Networks Technical Assistance Center (JTAC) when either of the following occurs:

    • The service is not running.

    • The service’s uptime compared with other services indicates that it has restarted.