Deploy Instance Manager 2.16 and earlier

Introduction

This guide provides a step-by-step tutorial on how to set up Instance Manager on a Kubernetes cluster using Helm. Learn how to download and use Docker images, and customize your deployment.

Note:

This guide applies to Instance Manager 2.16 and earlier.

For newer versions, view the Deploy Instance Manager 2.17 and later topic.

About Instance Manager

NGINX Instance Manager allows you to configure, scale, and manage NGINX Open Source and NGINX Plus instances at scale. Instance Manager provides a REST API and web-based graphical user interface (GUI) for managing NGINX instances across multiple servers, making it easier to configure, monitor, and troubleshoot NGINX deployments.

Instance Manager can be used to manage instances running on-premises, in the cloud, or in hybrid environments, and it supports the deployment of NGINX instances on a variety of operating systems and container platforms.

Instance Manager also includes advanced features like health checks, rolling updates, and configuration backups, which help to ensure the reliability and security of NGINX deployments.

About Helm

Helm charts are pre-configured packages of Kubernetes resources deployed with a single command, which allow you to to define, install, and upgrade Kubernetes applications.

They are composed of a set of files that describe a related group of Kubernetes resources, including deployments, services, and ingress. Helm charts can define and manage dependencies between various applications, allowing for the development of complex, multi-tier applications.

Warning:

NGINX Instance Manager does not support OpenShift.

For best compatibility, use NGINX Ingress Controller.

Before You Begin

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

Add Helm Repository

Note:
To complete the steps in the section, you need to have Helm 3.10.0 or later installed.

Run the following commands to install the NGINX Management Suite chart from the Helm repository:

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

The first command, helm repo add nginx-stable https://helm.nginx.com/stable, adds the nginx-stable repository to your local Helm repository list. This repository contains the Helm charts for deploying NGINX Management Suite.

The second command, helm repo update, updates the local Helm repository list with the newest versions of the charts from the nginx-stable repository. This command ensures you have the most up-to-date version of the charts available for installation.

Download Helm Package

Take the following steps to download and extract the Helm page on your host:

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 F5 NGINX Instance Manager.

4. Select the following download options:

   • Product version: Select the version of Instance Manager that you want to install.
   • Linux distribution: Select helmchart.
   • Distribution Version: Defaults to the helmchart version determined by the Product Version.
   • Architecture: Defaults to k8s.

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

6. Make a directory to extract the Helm package into:

   mkdir -p nms-docker-images
   

7. Extract the package into the target directory:

   tar -xzf nms-helm-<version>.tar.gz -C nms-docker-images
   

   
   

   The extracted files include the following Docker images:

   Docker images

   • nms-apigw-<version>.tar.gz
   • nms-core-<version>.tar.gz
   • nms-dpm-<version>.tar.gz
   • nms-ingestion-<version>.tar.gz
   • nms-integrations-<version>.tar.gz
   • nms-utility-<version>.tar.gz

Load Docker Images

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 extracted the Docker images:

   cd nms-docker-images
   

2. Load the Docker images:

   docker load -i nms-apigw-<version>.tar.gz
   docker load -i nms-core-<version>.tar.gz
   docker load -i nms-ingestion-<version>.tar.gz
   docker load -i nms-dpm-<version>.tar.gz
   docker load -i nms-integrations-<version>.tar.gz
   docker load -i nms-utility-<version>.tar.gz
   

   This set of commands loads the Docker images from the specified tar.gz archives. Replace <version> with the product version you specified when downloading the Helm bundle.

   The output looks similar to the following:

   1 2 3 4 5 6 7

   $ docker load -i nms-apigw-<version>.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.9.1

   Important:
   

   For the output of each docker load command, note the loaded image’s name and tag. You will need to reference these images and tags in the next section when pushing the images to your private registry.

   For example, in the output directly above, nms-apigw is the image name and 2.9.1 is the tag. The tag 2.9.1 could differ depending on the product version you downloaded from MyF5.

Push Images 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 images above.

1. Log in to your private registry:

   docker login <my-docker-registry:port>
   

2. Tag the images with the version you noted when loading the Docker images above.

   docker tag nms-apigw:<version> <my-docker-registry:port>/nms-apigw:<version>
   docker tag nms-core:<version> <my-docker-registry:port>/nms-core:<version>
   docker tag nms-dpm:<version> <my-docker-registry:port>/nms-dpm:<version>
   docker tag nms-ingestion:<version> <my-docker-registry:port>/nms-ingestion:<version>
   docker tag nms-integrations:<version> <my-docker-registry:port>/nms-integrations:<version>
   docker tag nms-utility:<version> <my-docker-registry:port>/nms-utility:<version>
   

   For example:

   docker tag nms-apigw:2.9.1 myregistryhost:5000/nms-apigw:2.9.1
   ...
   

3. Push the images to your private registry:

   docker push <my-docker-registry:port>/nms-apigw:<version>
   docker push <my-docker-registry:port>/nms-core:<version>
   docker push <my-docker-registry:port>/nms-dpm:<version>
   docker push <my-docker-registry:port>/nms-ingestion:<version>
   docker push <my-docker-registry:port>/nms-integrations:<version>
   docker push <my-docker-registry:port>/nms-utility:<version>
   

   For example:

   docker push myregistryhost:5000/nms-apigw:2.9.1
   ...
   

Create a Helm Deployment values.yaml File

values.yaml is a Helm configuration file you can use to customize the installation of a Helm chart without editing the chart itself. Values can be used to specify different image repositories and tags, set environment variables, configure resource requests and limits, and more.

1. Create a values.yaml file similar to the following example:

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

   • Replace <version> with the tag you used when pushing the images to your private registry.

   • In the imagePullSecrets section, add the credentials for your private Docker registry.

     See Also:
     For instructions on creating a secret, see the Kubernetes topic 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 values.yaml file specifies the Docker images to be used for the apigw, core, dpm, ingestion, integrations and utility components, including the repository (<my-docker-registry:port>) and tag (version) of each image. It also specifies that a secret called regcred should be used for image pulls.

2. Save and close the values.yaml file.

Manage Network Policies

To enforce existing network policies for NGINX Management Suite, Kubernetes must have a network plugin installed before helm chart installation.

When enabled, 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 the existing network policies, update the values.yaml file as shown below:

 networkPolicies:
	 # Setting this to true enables network policies for NGINX Management Suite.
	 enabled: false

Install Chart

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

Run the helm install command to install Instance Manager from the Helm chart:

• 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 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 Management Suite chart version, refer to the following table, which provides information about the compatible modules for each version.

Validate Deployment

Run the following command to check the status of the deployment:

helm -n nms status nms

This helm command shows the status of the app called nms in the namespace nms. The command displays the release name, chart version, last deployment time, and current status.

The status should be STATUS: deployed if the deployment was successful.

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 to make full use of all the features in Instance Manager.

Refer to the Add a License topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license.

Upgrade Instance Manager

To upgrade Instance Manager, take the following steps:

1. Repeat the steps above to:

   • Download Helm Package
   • Load Docker Images
   • Push Images to Private Docker Registry
   • Configure values.yaml file to pull from your private Docker registry.

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

Uninstall Instance Manager

Uninstalling Instance Manager also uninstalls the entire NGINX Management Suite.

To uninstall Instance Manager, run the following command:

helm uninstall --namespace nms nms

This helm command uninstalls the app named nms from the namespace nms. It deletes all of the Kubernetes resources associated with the app, including any deployments, pods, services, and configmaps.

Configurable Helm Settings

The following table lists the configurable parameters and default values for the NGINX Management Suite platform when installing from a Helm chart.

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.

Instance Manager Dqlite Storage Configuration

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

Instance Manager Secrets Storage Configuration

  - name: secrets
    existingClaim:
    size: 128Mi
    accessMode: ReadWriteOnce

Instance Manager NATS Storage Configuration

  - name: nats-streaming
    existingClaim:
    size: 1Gi
    accessMode: ReadWriteOnce

Kubernetes Taints and Tolerations

The following example snippet shows a toleration on an Instance Manager APIGW deployment. In this example, Kubernetes will tolerate the “NoExecute” effect for 60 seconds before evicting the pod from the tainted node.

tolerations:
  - key: "node.kubernetes.io/unreachable"
    operator: "Exists"
    effect: "NoExecute"
    tolerationSeconds: 60
  - key: "node.kubernetes.io/network-unavailable"
    operator: "Exists"
    effect: "NoExecute"
    tolerationSeconds: 60

For more information, refer to the official Kubernetes Taints and Tolerations documentation.

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.