Deploy using Helm

Overview

You can deploy F5 NGINX Instance Manager on Kubernetes using Helm. This method is quick, scalable, and supports both standard and lightweight modes.

New in 2.20.0

Starting with version 2.20.0, NGINX Instance Manager supports lightweight mode, which skips ClickHouse and disables metrics collection, ideal for simpler setups or resource-limited environments.

  • Lightweight mode requires NGINX Agent v2.41.1 or later.
Chart renamed in NIM 2.20.0 The Helm chart has been renamed from nginx-stable/nms-hybrid to nginx-stable/nim.
Make sure to update your chart references if you’re using version 2.20.0 or later.

Requirements

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

Requirements

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

Requirements Notes
Docker 20.10 or later (linux/amd64) Docker documentation
Kubernetes 1.21.3 or later (linux/amd64) Ensure your client can access the Kubernetes API server. Helm uses the default storage class for persistent volume provisioning.
kubectl 1.21.3 or later kubectl documentation
Helm 3.10.0 or later Helm installation guide
OpenSSL 1.1.1 or later OpenSSL source
tar 1.20 or later The tar tool is usually installed by default. Check with tar --version.
values.yaml file with nmsClickhouse.mode Optional. Defaults to internal. Set to external or disabled to use an external ClickHouse instance or enable lightweight mode. In external mode, set nim.externalClickhouse.address to your ClickHouse host.
NGINX subscription JWT Required to authenticate with private-registry.nginx.com to pull the image. Download your JWT from MyF5 under My Products & Plans > Subscriptions.

Set up image registry access for NGINX Instance Manager

You can use your NGINX JWT 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.

Kubernetes 

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

OpenShift 

oc new-project nms
oc create secret docker-registry regcred \
  --docker-server=private-registry.nginx.com \
  --docker-username=<NGINX JWT Token> \
  --docker-password=none \
  -n nms
Note

You might see a warning that --password is insecure. In this case, it’s safe to ignore—none is used as a placeholder.

As a best practice, you can delete the JWT token and clear your shell history after deployment if others have access to the system.

Confirm the secret

  • Kubernetes

    kubectl get secret regcred --output=yaml -n nms

  • OpenShift

    oc get secret regcred --output=yaml -n nms

You can now use this secret for Helm deployments and point the chart to the private registry.

Add the repository

Run the following commands to add the official NGINX Helm repository and update your local chart list.

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

Create a values.yaml file

Create a file named values.yaml using the following example. This file customizes your NGINX Instance Manager deployment with Helm.

The values file lets you:

  • Set the deployment mode
  • Provide registry credentials
  • Specify image sources for each NIM service

Set nmsClickhouse.mode to control ClickHouse deployment:

Mode Description
internal Deploys ClickHouse in the cluster (default).
external Connects to an external ClickHouse instance and requires nim.externalClickhouse.address.
disabled Disables ClickHouse and enables lightweight mode (no metrics).
See also See the Helm chart configuration settings guide for a complete list of chart parameters. 
nmsClickhouse:
  mode: internal # options: internal, external, disabled

# when mode is external, uncomment and set this:
# externalClickhouse:
#   address: <clickhouse-host>:<port>

imagePullSecrets:
  - name: regcred

apigw:
  image:
    repository: private-registry.nginx.com/nms/apigw
    tag: 2.20.0

core:
  image:
    repository: private-registry.nginx.com/nms/core
    tag: 2.20.0

dpm:
  image:
    repository: private-registry.nginx.com/nms/dpm
    tag: 2.20.0

ingestion:
  image:
    repository: private-registry.nginx.com/nms/ingestion
    tag: 2.20.0

integrations:
  image:
    repository: private-registry.nginx.com/nms/integrations
    tag: 2.20.0

secmon:
  image:
    repository: private-registry.nginx.com/nms/secmon
    tag: 2.20.0

utility:
  image:
    repository: private-registry.nginx.com/nms/utility
    tag: 2.20.0

These values are required when pulling images from the NGINX private registry. The chart does not auto-resolve image tags. Update the tag: fields to match the NGINX Instance Manager version you want to install.

Use the file with the -f values.yaml flag when installing the chart.

OpenShift support OpenShift support was added in NGINX Instance Manager 2.19. To enable it, add the setting openshift.enabled: true to your values.yaml file.
For more details, see Appendix: OpenShift security constraints.

Install the chart

Install NGINX Instance Manager using Helm. The adminPasswordHash sets the default admin password.

helm install nim nginx-stable/nim \
  -n nim \
  --create-namespace \
  --set adminPasswordHash=$(openssl passwd -6 '<your-password>') \
  -f <your-values.yaml> \
  --version <chart-version> \
  --wait
  • Replace <your-password> with your preferred admin password.
  • Replace <your-values.yaml> with the path to your customized values.yaml file.
  • Replace <chart-version> with the version you want to install (for example, 2.20.0).

Note: You can set the ClickHouse mode at install time instead of editing values.yaml:

For lightweight mode (no ClickHouse):

--set nmsClickhouse.mode=disabled

For external ClickHouse:

--set nmsClickhouse.mode=external \
--set nim.externalClickhouse.address=<clickhouse-host>:<port>

Validate the deployment

After installation, run the following command to confirm the deployment was successful:

helm status nim -n nim

You should see STATUS: deployed in the output.

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 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 your deployment:

  1. Update the Helm repository list.
  2. Review and adjust your values.yaml file as needed.
  3. Run the following command to upgrade the deployment. This command uses the current chart version from the nginx-stable/nim repository and applies the configuration from your values.yaml file.
helm upgrade nim nginx-stable/nim \
  -n nim \
  --set adminPasswordHash=$(openssl passwd -6 '<your-password>') \
  -f <path-to-your-values.yaml> \
  --version <nim-version> \
  --wait
  • Replace <your-password> with a secure password that includes uppercase and lowercase letters, numbers, and special characters.
  • Replace <path-to-your-values.yaml> with the full path to your configuration file.
  • Replace <nim-version> with the version of NGINX Instance Manager you want to upgrade to.
Save the password! Only the encrypted version of the admin password is stored in Kubernetes. If you lose it, it can’t be recovered or reset. Make sure to save the password in a secure place.
Upgrading from earlier versions If you’re upgrading from a deployment that used the legacy nms chart or release name, you’ll need to update the chart reference and adjust the release name as needed. The latest chart is now called nginx-stable/nim, and nim is the recommended release name.

Uninstall NGINX Instance Manager

To uninstall NGINX Instance Manager, run:

helm uninstall <release-name> -n <namespace>

This command removes the deployment and all Kubernetes resources managed by the Helm chart.

For example, if you used the default release and namespace names:

helm uninstall nim -n nim

Manage network policies

If you plan to use network policies, make sure your Kubernetes cluster has a supported network plugin installed before you install the Helm chart.

By default, the Helm chart creates a set of network policies for NGINX Instance Manager in the deployment namespace.

To view them:

  • Kubernetes:

    kubectl get netpol -n <namespace>

  • OpenShift:

    oc get netpol -n <namespace>

The number and names of network policies vary depending on the deployment mode (standard vs. lightweight). For example, in standard mode, you might see output like this:

NAME         POD-SELECTOR                     AGE
apigw        app.kubernetes.io/name=apigw     2m
core         app.kubernetes.io/name=core      2m
dpm          app.kubernetes.io/name=dpm       2m
ingestion    app.kubernetes.io/name=ingestion 2m
secmon       app.kubernetes.io/name=secmon    2m

If you’re using lightweight mode, your output may include fewer entries.

To disable network policies, add the following to your values.yaml file:

networkPolicies:
  enabled: false

Helm Deployment for NGINX Instance Manager 2.18 or lower

Create a Helm deployment values.yaml file

The values.yaml file customizes the Helm chart installation without modifying the chart itself. You can use it to specify image repositories, environment variables, resource requests, and other settings.

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

    • In the imagePullSecrets section, add the credentials for your private Docker registry.
    • Change the version tag to the version of NGINX Instance Manager you would like to install. See “Install the chart” below for versions.
    See Also: For details on creating a secret, see Kubernetes Pull an Image from a Private Registry. 
    nms-hybrid:
    imagePullSecrets:
        - name: regcred
    apigw:
        image:
            repository: private-registry.nginx.com/nms/apigw
            tag: <version>
    core:
        image:
            repository: private-registry.nginx.com/nms/core
            tag: <version>
    dpm:
        image:
            repository: private-registry.nginx.com/nms/dpm
            tag: <version>
    ingestion:
        image:
            repository: private-registry.nginx.com/nms/ingestion
            tag: <version>
    integrations:
        image:
            repository: private-registry.nginx.com/nms/integrations
            tag: <version>
    utility:
        image:
            repository: private-registry.nginx.com/nms/utility
            tag: <version>

  2. Save and close the values.yaml file.

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.

  3. (Optional) Replace <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:

NGINX Instance Manager chart Instance Manager
2.0.0 2.20.0
1.15.0 2.18.0
1.14.4 2.17.4
1.14.0 2.17.0
1.13.0 2.16.0
1.12.1 2.15.1
1.12.0 2.15.0
1.11.0 2.14.0
1.10.1 2.13.1
1.10.0 2.13.1
1.9.0 2.13.0
1.8.2 2.12.0
1.8.1 2.12.0
1.8.0 2.12.0
1.7.2 2.11.0
1.7.1 2.11.0
1.7.0 2.11.0
1.6.0 2.10.1
1.5.2 2.10.0
1.5.1 2.10.0
1.5.0 2.10.0
1.4.0 2.9.1
1.3.1 2.9.0
1.3.0 2.9.0
1.2.1 2.8.0
1.2.0 2.8.0
1.1.2 2.7.0
1.1.1 2.7.0
1.1.0 2.7.0
1.0.0 2.6.0

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 Manager 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.

  4. Replace <chart-version> with the desired chart version 1.15.0 or lower. If omitted, it will lead to an unsuccessful deployment as it will try to upgrade to the latest vesrion 1.16.0 or later.

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

    • Replace <path-to-your-values.yaml> with the path to the values.yaml file you created](https://frontdoor-test-docs.nginx.com/previews/docs/684/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.

Troubleshooting

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

Appendix: OpenShift security constraints

OpenShift restricts containers from running as root by default. To support NGINX Instance Manager, the Helm chart creates a custom Security Context Constraint (SCC) when you set:

openshift:
  enabled: true

This ensures pods can run with the user IDs required by NGINX Instance Manager services.

Note If you see permission errors during deployment, your user account might not have access to manage SCCs. Contact a cluster administrator to request access.

To verify that the SCC was created after installing the Helm chart, run:

oc get scc nms-restricted-v2-scc --output=yaml

Next steps