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 user 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 usenms
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:
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. The Helm chart will enable persistent storage using the default storage class in your Kubernetes cluster. More info is available in Dynamic 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 your version with tar --version . If tar is missing or outdated, install it from your distribution’s package manager (like YUM for CentOS/RHEL or APT for Debian/Ubuntu). |
Get the NGINX Instance Manager images
Using Docker
Configure Docker to access the NGINX Instance Manager public registry
-
Download your NGINX Instance Manager subscription’s JSON Web Token from MyF5:
- Log in to MyF5.
- Go to My Products & Plans > Subscriptions to see your active subscriptions.
- Find your NGINX products or services subscription, and select the Subscription ID for details.
- Download the JSON Web Token from the subscription page.
-
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. -
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:
Thelatest
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.
-
Log in to your private registry:
docker login <my-docker-registry>
-
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.
-
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
, andutility
. It also indicates that a secret calledregcred
should be used for pulling images. - Replace
-
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:
-
Replace
<path-to-your-values.yaml>
with the path to yourvalues.yaml
file. -
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:
NGINX Instance Manager chart | Instance Manager |
---|---|
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 |
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.
-
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 namedapigw
from the namespacenms
. 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 tohttps://<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 asLoadBalancer
, by changing the Configurable Helm Setting value fornms-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:
-
Adjust your
values.yaml
file if needed. -
To upgrade the NGINX instance deployment, run the following command. This command updates the
nms
deployment with a new version from thenginx-stable/nms
repository. It also hashes the provided password and uses thevalues.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 thevalues.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.