Deploy App Delivery Manager on Kubernetes

The guide provides step-by-step instructions to deploy NGINX App Delivery Manager on Kubernetes using a Helm chart.

Requirements

Review the following requirements for App Delivery Manager before continuing.

Install Instance Manager

Important:
To install App Delivery Manager, you must first install Instance Manager. This is because App Delivery Manager relies on features that are included with Instance Manager.

• Deploy Instance Manager on Kubernetes

Dependencies with Instance Manager

Refer to the following table to see the module compatibility for each NGINX Management Suite chart.

Download Docker Image

Follow these steps to download the Docker image for App Delivery Manager:

1. Go to the MyF5 website, then select Resources > Downloads.

2. In the Select Product Family list, select NGINX.

3. In the Product Line list, select NGINX App Delivery Manager.

4. Select the following download options:

   • Product version – Select the version of App Delivery Manager you want to install. Make sure this version is compatible with the version of Instance Manager you installed as a prerequisite. Refer to the Dependencies with Instance Manager section above.
   • Linux distribution – Select the Linux distribution you’re deploying to. For example, ubuntu.
   • Distribution Version – Select the Linux distribution’s version. For example, 20.04.
   • Architecture – Select the architecture. For example, amd64.

5. In the Download Files section, download the nms-adm-<version>-img.tar.gz file.

Load Docker Image

Note:
To complete the commands in this section, you need to have Docker 20.10 or later installed.

1. Change to the directory where you downloaded the Docker image:

   cd <directory name>
   

2. Load the Docker image from the nms-adm-<version>-img.tar.gz archive:

   docker load -i nms-adm-<version>-img.tar.gz
   

   The output looks similar to the following:

   $ docker load -i nms-adm-<version>-img.tar.gz
   1b5933fe4b5: Loading layer [==================================================>]  5.796MB/5.796MB
   fbe0fc9bcf95: Loading layer [==================================================>]  17.86MB/17.86MB
   ...
   112ae1f604e0: Loading layer [==================================================>]   67.8MB/67.8MB
   4b6a693b90f4: Loading layer [==================================================>]  3.072kB/3.072kB
   Loaded image: nms-adm:4.0.0
   

   Important:
   

   Take note of the loaded image’s name and tag. You’ll need to reference this information in the next section when pushing the image to your private registry.

   In the example output above, nms-adm is the image name and 4.0.0 is the tag. The image name or tag could be different depending on the product version you downloaded from MyF5.

Push Image to Private Registry

Note:
To complete the steps in this section, you need an externally-accessible private Docker registry to push the container images to.

To push the Docker images to your private registry, take the following steps:

• Replace <my-docker-registry:port> with your private Docker registry and port (if needed).

• Replace <version> with the tag you noted when loading the Docker image above.

1. Log in to your private registry:

   docker login <my-docker-registry:port>
   

2. Tag the image with the image name and version you noted when loading the Docker image.

   docker tag nms-adm:<version> <my-docker-registry:port>/nms-adm:<version>
   

   For example:

   docker tag nms-adm:1.5 myregistryhost:5000/nms-adm:1.5
   

3. Push the image to your private registry:

   docker push <my-docker-registry:port>/nms-adm:<version>
   

   For example:

   docker push nms-adm:1.5 myregistryhost:5000/nms-adm:1.5
   

Enable App Delivery Manager

To enable the App Delivery Manager module, take the following steps:

1. Open the values.yaml file for editing.

2. Add the following snippet to the values.yaml file:

   • Replace <my-docker-registry:port> with your private Docker registry and port (if needed).
   • Replace <version> with the tag you noted when loading the Docker image above.
   • In the imagePullSecrets section, add the credentials for your private Docker registry.

   # values.yaml
   global:
       nmsModules:
           nms-adm:
               enabled: true
   nms-adm:
       imagePullSecrets:
       - name: regcred
       adm:
           image:
               repository: <my-docker-registry:port>/nms-adm 
               tag: <version>
   

3. Close and save the values.yaml file.

Upgrade NGINX Management Suite Deployment

Note:
To complete the steps in this section, you need to have OpenSSL 1.1.1 or later installed.

Run the following command to upgrade the NGINX Management Suite deployment:

• Replace <path-to-your-values.yaml> with the path to the values.yaml file you created.

• Replace YourPassword123# with a secure password that contains a combination of uppercase and lowercase letters, numbers, and special characters.

  Important:
  Make sure to copy and save the password for future reference. Only the encrypted password is stored in Kubernetes. There’s no way to recover or reset a lost password.

• (Optional) Replace <nms-chart-version> with the desired version; see the table below for the available versions. Alternatively, you can omit this flag to install the latest version.

helm upgrade -n nms --set nms-hybrid.adminPasswordHash=$(openssl passwd -6 'YourPassword123#') nms nginx-stable/nms -f <path-to-your-values.yaml> [--version <nms-chart-version>] --wait

This command upgrades an existing Helm chart deployment named nms with a new version of the chart located in the nginx-stable/nms repository. It also sets the value of the nms-hybrid.adminPasswordHash to the hashed version of the provided password and uses a values.yaml file located at the provided path.

Upgrade Existing App Delivery Manager Deployment

If you’ve already deployed API Connectivity Manager and would like to upgrade to a newer version, take the following steps:

1. Repeat the steps above to:

   • Download Newer Docker Image
   • Load Docker Image
   • Push Image to Private Docker Registry

2. Run the helm upgrade command above to upgrade the NGINX Management Suite deployment.

Access Web Interface

You can access the NGINX Management Suite web interface using the external IP address for the API Gateway.

1. To look up the external IP address for the API Gateway, run the following command:

   kubectl -n nms get svc apigw
   

   This kubectl command retrieves the service named apigw from the namespace nms. It outputs the details of the service, such as its type, port, cluster and external IP addresses.

   The default service type is ClusterIP and the output looks similar to the following example:

   NAME    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
   apigw   ClusterIP   10.108.57.167   <none>        443/TCP   32s
   

   Using the CLUSTER-IP value, go to https://<CLUSTER-IP>:443/ui.

   For example, https://10.108.57.167/ui.

   This IP address might not be reachable, depending on how the Kubernetes cluster networking was configured. If so, the apigw service type can be changed to a more suitable option, such as LoadBalancer, by changing the Configurable Helm Setting value for nms-hybrid.apigw.service.type .

Add License

A valid license is required in order to use App Delivery Manager.

Download License

To download a license for NGINX Management Suite:

1. Go to the MyF5 Customer Portal and sign in.
2. On the top menu, select My Products & Plans > Trials.
3. In the My Trials list, select your your NGINX Management Suite trial.
4. Select the Licenses and Certificates link.
5. On the Getting started panel, select Download License. The license .lic file is saved to your system.

Apply License

To upload and apply a license for NGINX Management Suite:

1. Go to the FQDN for your NGINX Management Suite host in a web browser and log in.
2. Select the Settings gear icon.
3. On the Settings menu, select Licenses.
4. Select Upload License.
5. Locate the .lic file that you downloaded to your system, then select Upload.

Configurable Helm Settings

To modify a configuration for an existing release, run the helm upgrade command and use -f <my-values-file>, where my-values-file is a path to a values file with your desired configuration.

The following table lists the configurable parameters and default values used by the App Delivery Manager chart when installing from a Helm chart.

App Delivery Manager Dqlite Configuration

  - name: dqlite
    existingClaim:
    size: 500Mi
    accessMode: ReadWriteOnce

App Delivery Manager Templates Configuration

The following volume persists the App Delivery Manager templates' directories and preserves the new files a user may add to the templates directory.

  - name: templates
    existingClaim:
    size: 500Mi
    accessMode: ReadWriteOnce

Troubleshooting

For help with common issues and suggested solutions and workarounds, refer to the NGINX Management Suite Troubleshooting Guide.

For guidance on how to create a support package containing system and service details to share with NGINX Customer Support, refer to the guide Create a Support Package from a Helm Installation.

What’s Next

Deploy Other NGINX Management Suite Modules

• Deploy API Connectivity Manager on Kubernetes