Important: NGINX Plus R33 requires NGINX Instance Manager 2.18 or later
To ensure uninterrupted traffic processing, upgrade to NGINX Instance Manager 2.18 or later if your NGINX data plane instances are running NGINX Plus R33. This upgrade is necessary to support usage reporting.

NGINX Plus R33 instances must send usage data to the F5 licensing endpoint or NGINX Instance Manager. If they don’t, they will stop processing traffic.

For more information about usage reporting and enforcement, see About solution licenses.

Deploy using Helm

Overview

Legacy 'nms' references
Some commands, file paths, and configuration references still use nms due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

This guide provides a step-by-step tutorial on how to set up F5 NGINX Instance Manager on a Kubernetes cluster using Helm. You’ll learn how to download and use Docker images and customize your deployment.

About Helm

Helm charts are pre-configured packages of Kubernetes resources deployed with a single command. They let you define, install, and upgrade Kubernetes applications easily.

Helm charts consist of files that describe a group of related Kubernetes resources, like deployments, services, and ingress. They also allow you to manage dependencies between applications, making it easier to deploy multi-tier or complex applications.

Supportability considerations
NGINX Instance Manager does not support OpenShift. For better compatibility, use NGINX Ingress Controller.

Before you begin

To deploy NGINX Instance Manager using a Helm chart, you need:

Get the NGINX Instance Manager images

Using Docker

Configure Docker to access the NGINX Instance Manager public registry

1. Download your NGINX Instance Manager subscription’s JSON Web Token from MyF5. You can use the same JSON Web Token as NGINX Plus in your MyF5 portal.

   1. Log in to MyF5.
   2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
   3. Find your NGINX products or services subscription, and select the Subscription ID for details.
   4. Download the JSON Web Token from the subscription page.

2. Open the JSON Web Token file you downloaded from MyF5 and copy its contents.

   Copying the JWT token
   Make sure there are no extra characters or spaces when copying the contents of the JWT token: they can invalidate the token and cause 401 errors during authentication.

3. Log in to the Docker registry using the contents of the JSON Web Token file:

   docker login private-registry.nginx.com --username=<JWT_CONTENTS> --password=none
   

Pull the NGINX Instance Manager images

You can now pull the necessary images for NGINX Instance Manager from the private registry at private-registry.nginx.com.

Replace <version-tag> with the specific version you want to use.

Note:
The latest tag is not supported.

docker pull private-registry.nginx.com/nms/apigw:<version-tag>
docker pull private-registry.nginx.com/nms/core:<version-tag>
docker pull private-registry.nginx.com/nms/dpm:<version-tag>
docker pull private-registry.nginx.com/nms/ingestion:<version-tag>
docker pull private-registry.nginx.com/nms/integrations:<version-tag>
docker pull private-registry.nginx.com/nms/utility:<version-tag>

If needed, you can push these images to your own private registry.

Push images to your private registry

After pulling the images, tag them and upload them to your private registry.

1. Log in to your private registry:

   docker login <my-docker-registry>
   

2. Tag and push each image. Replace <my-docker-registry> with your registry’s path and <version-tag> with the version you’re using (for example, 2.17.0):

   • For the apigw image:

     docker tag private-registry.nginx.com/nms/apigw:<version-tag> <my-docker-registry>/nms/apigw:<version-tag>
     docker push <my-docker-registry>/nms/apigw:<version-tag>
     

   • For the core image:

     docker tag private-registry.nginx.com/nms/core:<version-tag> <my-docker-registry>/nms/core:<version-tag>
     docker push <my-docker-registry>/nms/core:<version-tag>
     

   • For the dpm image:

     docker tag private-registry.nginx.com/nms/dpm:<version-tag> <my-docker-registry>/nms/dpm:<version-tag>
     docker push <my-docker-registry>/nms/dpm:<version-tag>
     

   • For the ingestion image:

     docker tag private-registry.nginx.com/nms/ingestion:<version-tag> <my-docker-registry>/nms/ingestion:<version-tag>
     docker push <my-docker-registry>/nms/ingestion:<version-tag>
     

   • For the integrations image:

     docker tag private-registry.nginx.com/nms/integrations:<version-tag> <my-docker-registry>/nms/integrations:<version-tag>
     docker push <my-docker-registry>/nms/integrations:<version-tag>
     

   • For the utility image:

     docker tag private-registry.nginx.com/nms/utility:<version-tag> <my-docker-registry>/nms/utility:<version-tag>
     docker push <my-docker-registry>/nms/utility:<version-tag>
     

Using Helm with a JWT token

If you don’t need a private registry, you can use a JWT token as a Docker configuration secret with Helm charts.

Create a Docker registry secret on the cluster, using the JWT token as the username and none as the password. The Docker server is private-registry.nginx.com.

Note:
Make sure there are no extra characters or spaces when copying the JWT token. They can invalidate the token and cause 401 errors during authentication.

kubectl create secret docker-registry regcred \
--docker-server=private-registry.nginx.com \
--docker-username=<JWT Token> \
--docker-password=none

Warning:

You might see a warning about --password being insecure.

This can be ignored (since no password is used), but if others have access to this system, delete the JWT token and clear your shell history after deployment.

To confirm the secret is created:

kubectl get secret regcred --output=yaml

You can now use this secret for Helm deployments and point the charts to the public registry.

Add the Helm repository

Note:
You need Helm 3.10.0 or later for these steps.

Run these commands to install the NGINX Instance Manager chart from the Helm repository:

helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update

The first command adds the nginx-stable repository to your local Helm repo list. The second updates the list to ensure you have the latest versions of the charts.

Create a Helm deployment values.yaml file

The values.yaml file customizes the Helm chart installation without editing the chart itself. You can specify image repositories, environment variables, resource requests, and more.

1. Create a values.yaml file similar to this example:

   • Replace <my-docker-registry:port> with your private Docker registry and port (if needed).
   • In the imagePullSecrets section, add the credentials for your private Docker registry.

   See Also:
   For more on creating a secret, see Kubernetes Pull an Image from a Private Registry.

   nms-hybrid:
       imagePullSecrets:
           - name: regcred
       apigw:
           image:
               repository: <my-docker-registry:port>/nms-apigw
               tag: <version>
       core:
           image:
               repository: <my-docker-registry:port>/nms-core
               tag: <version>
       dpm:
           image:
               repository: <my-docker-registry:port>/nms-dpm
               tag: <version>
       ingestion:
           image:
               repository: <my-docker-registry:port>/nms-ingestion
               tag: <version>
       integrations:
           image:
               repository: <my-docker-registry:port>/nms-integrations
               tag: <version>
       utility:
           image:
               repository: <my-docker-registry:port>/nms-utility
               tag: <version>
   

   This file specifies the Docker images for apigw, core, dpm, ingestion, integrations, and utility. It also indicates that a secret called regcred should be used for pulling images.

2. Save and close the values.yaml file.

Manage network policies

To apply network policies for NGINX Instance Manager, ensure Kubernetes has a network plugin installed before the Helm chart installation.

By default, the following network policies will be created in the release namespace:

kubectl get netpol -n nms

NAME           POD-SELECTOR                          AGE
apigw          app.kubernetes.io/name=apigw          4m47s
clickhouse     app.kubernetes.io/name=clickhouse     4m47s
core           app.kubernetes.io/name=core           4m47s
dpm            app.kubernetes.io/name=dpm            4m47s
ingestion      app.kubernetes.io/name=ingestion      4m47s
integrations   app.kubernetes.io/name=integrations   4m47s
utility        app.kubernetes.io/name=integrations   4m47s

To disable network policies, update the values.yaml file:

networkPolicies:
    # Set this to true to enable network policies for NGINX Instance Manager.
    enabled: false

Install the chart

Run the helm install command to deploy NGINX Instance Manager:

1. Replace <path-to-your-values.yaml> with the path to your values.yaml file.

2. Replace YourPassword123# with a secure password (containing a mix of uppercase, lowercase letters, numbers, and special characters).

   Important:
   Remember to save the password for future use. Only the encrypted password is stored, and there’s no way to recover or reset it if lost.

(Optional) Replace <nms-chart-version> with the desired chart version. If omitted, the latest version will be installed.

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

To help you choose the right NGINX Instance Manager chart version, see the table in:

Validate the deployment

Check the status of the deployment:

helm -n nms status nms

The status should show STATUS: deployed if successful.

Access the web interface

You can access the NGINX Instance Manager 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 a license

A valid license is required to use all NGINX Instance Manager features.

For instructions on downloading and applying a license, see Add a License.

Upgrade NGINX Instance Manager

To upgrade:

1. Update the Helm repository list.

2. Adjust your values.yaml file if needed.

3. To upgrade the NGINX instance deployment, run the following command. This command updates the nms deployment with a new version from the nginx-stable/nms repository. It also hashes the provided password and uses the values.yaml file at the path you specify.

    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
   

   • Replace <path-to-your-values.yaml> with the path to the values.yaml file you created](/nginx-instance-manager/deploy/kubernetes/deploy-using-helm/#configure-chart).

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

     Save the password!
     Save this password for future use. Only the encrypted password is stored in Kubernetes, and you can’t recover or reset it later.

   • (Optional) Replace with the desired version number. If you don’t specify a version, the latest version will be installed.

Uninstall NGINX Instance Manager

To uninstall:

helm uninstall --namespace nms nms

This deletes the nms application and all associated Kubernetes resources.

Troubleshooting

For instructions on creating a support package to share with NGINX Customer Support, see Create a Support Package from a Helm Installation.