Helm Installation Guide

Follow the steps in the guide to install NGINX Instance Manager on Kubernetes with a helm chart.

This documentation applies to NGINX Instance Manager 2.1.0 and later.

Overview

We recommend using the NGINX Instance Manager helm chart to install NGINX Instance Manager on Kubernetes.

Among the benefits of deploying from a helm chart, the chart includes the required services, which you can scale independently as needed; upgrades can be done with a single helm command; and there’s no requirement for root privileges.

Important:
OIDC is not supported for helm chart deployments of NGINX Instance Manager on Kubernetes. Only basic auth is supported.

Before You Begin

To complete this tutorial, you need the following:

  • Kubernetes 1.21.3+ (linux/amd64) with client access to the Kubernetes API server

  • An externally-accessible private Docker registry to push the container images to

  • The following binaries:

    • Docker 20.10+ (linux/amd64)
    • helm v3.8.0+
    • kubectl v1.21.3+
    • openssl v1.1.1+
    • tar v1.20+

1. Download Helm Bundle

Take the following steps to download the helm chart bundle:

  1. Download the NGINX Instance Manager helm chart to your virtual machine.

    1. On the MyF5 website, select Resources > NGINX Downloads.

    2. In the NGINX products list, select NGINX Instance Manager.

    3. Select the following download options:

      • Product version: 2.1.0 or later
      • Linux distribution
      • Architecture

    4. Download the nms-helm-<version>.tar.gz files.



2. Extract Helm Bundle

The nms-helm-<version>.tar.gz file from Step 1: Download Helm Bundle includes several Docker container images and the helm package tarball. To extract these files, take the following steps:

  1. Make a directory to extract the package into:

    mkdir -p <directory name>

  2. Extract the package into the target directory:

    tar -xzf nms-helm-<version>.tar.gz -C <directory name>

    The extracted files include the following Docker images and helm package:

    Docker images

    • nms-apigw-img.tar.gz
    • nms-core-img.tar.gz
    • nms-dpm-img.tar.gz
    • nms-ingestion-img.tar.gz

    Helm package

    • nms-hybrid-<version>.tgz


3. Load Docker Images

Take the following steps to extract and load the Docker container images:

  1. Change to the directory where you extracted the Docker images:

    cd <directory name>

  2. Load the Docker images:

    docker load -i nms-apigw-img.tar.gz
docker load -i nms-core-img.tar.gz
docker load -i nms-ingestion-img.tar.gz
docker load -i nms-dpm-img.tar.gz

    The output looks similar to the following:

    $ docker load -i nms-apigw-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-apigw:2.1.0

  3. For the output of each docker load command, note the loaded image’s name and tag. For example, in the output directly above, nms-apigw is the image name and 2.1.0 is the tag. You’ll need to reference these images and tags in the next section when pushing the images to your private registry.



4. Push Images to Private Registry

Before you begin: To complete this step, you need an externally-accessible private Docker registry to push the container images to.

After loading the Docker images, you can now tag and push the images to your private Docker registry. Replace <my-docker-registry> in the examples below with the path to your private Docker registry.

  1. Log in to your private registry:

    docker login <my-docker-registry>

  2. Tag the images with the values you noted in Step 3: Load Docker Images above. In this example, the images are tagged with version 2.1.0.

    docker tag nms-apigw:2.1.0 <my-docker-registry>/nms-apigw:2.1.0
docker tag nms-core:2.1.0 <my-docker-registry>/nms-core:2.1.0
docker tag nms-dpm:2.1.0 <my-docker-registry>/nms-dpm:2.1.0
docker tag nms-ingestion:2.1.0 <my-docker-registry>/nms-ingestion:2.1.0

  3. Push the images to your private registry:

    docker push <my-docker-registry>/nms-apigw:2.1.0
docker push <my-docker-registry>/nms-core:2.1.0
docker push <my-docker-registry>/nms-dpm:2.1.0
docker push <my-docker-registry>/nms-ingestion:2.1.0


5. Extract Helm Chart

Now, extract the helm chart:

tar -xzf nms-hybrid-<version>.tgz

The package contents are extracted to a directory called nms-hybrid.



6. Configure Helm Chart

After you extract the helm chart, you can edit the bundled values.yaml file to customize the deployment settings for your environment.

See the following sections for recommended settings.


Image Repositories and Tags

Configure the helm chart to pull from your private Docker registry.

  1. Open values.yaml file for editing.
  2. Locate imagePullSecrets and add the credentials for your private Docker registry. For instructions on creating a secret, see the Kubernetes documentation Pull an Image from a Private Registry.
  3. Update the image:repository and image:tag values for the apigw, core, dpm, and ingestion services with the values you used in Step 4: Push Images to Private Registry.
  4. Save and close the values.yaml file.

Alternatively, you can use the helm install --set command to set values from the command line. The following example shows how to set values for imagePullSecrets, repository, and tag, where ./nms-hybrid is the extracted helm chart directory:

helm install \
--set imagePullSecrets=<secret> \
--set apigw.image.repository=nms-apigw \
--set apigw.image.tag=2.1.0 \
--set core.image.repository=nms-core \
--set core.image.tag=2.1.0 \
--set dpm.image.repository=nms-dpm \
--set dpm.image.tag=2.1.0 \
--set ingestion.image.repository=nms-ingestion \
--set ingestion.image.tag=2.1.0 \
nim ./nms-hybrid

ClickHouse Server

NGINX Instance Manager requires a ClickHouse database server for storing metrics information.

The helm chart installs ClickHouse server by default. This setting is enabled in the values.yaml file by setting nmsClickhouse.enabled = true.

Optionally, to use your own installation of ClickHouse, take the following steps:

  1. Open values.yaml for editing. You can find this file is in the helm package you downloaded.

  2. Set nmsClickhouse.enabled = false.

  3. Add values for externalClickhouse.address, .user, and .password matching your ClickHouse installation.

    Note:
    externalClickhouse is required when nmsClickhouse is disabled.

Certificates

NGINX Instance Manager generates a certificate authority and self-signs its certificates by default.

If you are deploying in a production environment, you should use your own certificates instead of the defaults. To do so, take the following steps.

  1. Open values.yaml for editing.
  2. Set existingCA.enabled = true.
  3. Add a base64-encoded cert to existingCA.base64EncodedCert.
  4. Add a base-64-encoded key to existingCA.base64EncodedKey.

Storage Settings

Review the deployment’s default resource and storage settings by editing the values.yaml file in the helm package you downloaded. Adjust the values to meet your data needs.

Persistent volumes are enabled by default for the ClickHouse database server and core and dpm services. To disable persistent storage for a configuration, set persistence.enable = false.



7. Dry Run

Use the helm command to perform a dry run. The Kubernetes API server returns the resources the helm chart will create in your Kubernetes environment.

The following example command creates a namespace called nms, sets a hashed password using openssl, and installs NGINX Instance Manager as an app called nim from the helm chart in ./nms-hybrid:

helm install --create-namespace --namespace nms --dry-run --set adminPasswordHash=$(openssl passwd -6 'YourPassword123#') nim ./nms-hybrid


8. Install

Run the helm install command to install NGINX Instance Manager from the helm chart.

The following example command creates a namespace called nms, sets a hashed password using openssl, and installs NGINX Instance Manager as an app called nim from the helm chart in ./nms-hybrid:

helm install --create-namespace --namespace nms --set adminPasswordHash=$(openssl passwd -6 'YourPassword123#') nim ./nms-hybrid
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.


9. Validate Deployment

To check the status of the deployment, run the following command. In this example, nms is the namespace and nim is the application name specified during installation.

helm -n nms status nim

If the deployment was successful, the status should be STATUS: deployed.



10. Access 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

    The output includes information similar to the following example. Note the value in the EXTERNAL-IP column.

    NAME    TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)         AGE
apigw   LoadBalancer   10.100.153.15   localhost     443:30414/TCP   2m1s

  2. Using the value from the previous step, go to https://<apigw-EXTERNAL-IP>:443/ui.

    For example, https://localhost:443/ui.



Upgrade

To upgrade NGINX Instance Manager when a new helm chart is available, run the following command:

helm upgrade --namespace nms nim nms-hybrid-<version>.tgz

After upgrading NGINX Instance Manager, validate the deployment following the instructions above. If the upgrade fails, your existing installation won’t be affected.



Uninstall

To uninstall NGINX Instance Manager from Kubernetes, run the following command. In this example, nms is the namespace and nim is the application name specified during installation.

helm uninstall --namespace nms nim


What’s Next