Earlier this year we introduced NGINX Management Suite as our new control plane for NGINX software solutions, enabling you to configure, scale, secure and monitor user applications and REST APIs on the NGINX data plane from a single pane of glass.
NGINX Management Suite has a modular design: at its core is the Instance Manager module, which provides tracking, configuration, and visibility for your entire fleet of NGINX Open Source and NGINX Plus instances. As of this writing, API Connectivity Manager is the other available module, used to manage and orchestrate NGINX Plus running as an API gateway.
NGINX Management Suite can run on bare metal, as a Linux virtual machine, or containerized. The recommended way to deploy it on Kubernetes is using the Helm chart we provide, but for specific purposes you might need to build your own Docker image and manage its lifecycle through a custom CI/CD pipeline that doesn’t necessarily rely on Helm.
[Editor – This post was updated in February 2023 to fully automate the process of building the Docker image.]
Prerequisites
We provide a GitHub repository of the resources you need to create a Docker image for NGINX Management Suite, with support for these versions of Instance Manager and API Connectivity Manager:
- Instance Manager 2.4.0+
- API Connectivity Manager 1.0.0+
- Security Monitoring 1.0.0+
To build the Docker image, you need:
- A Linux host (bare metal or VM)
- Docker 20.10+
- A private registry to which you can push the target Docker image
- A subscription (or 30-day free trial) for NGINX Management Suite
To run the Docker image, you need:
- A running Kubernetes cluster
kubectlwith access to the Kubernetes cluster- A subscription (or 30-day free trial) for the NGINX Ingress Controller based on NGINX Plus
Building the Docker Image
Follow these instructions to build the Docker image.
Note: We have made every effort to accurately represent the NGINX Management Suite UI at the time of publication, but the UI is subject to change. Use these instructions as a reference and adapt them to the current UI as necessary.
-
Clone the GitHub repository:
$ git clone https://github.com/nginxinc/NGINX-Demos Cloning into 'NGINX-Demos'... remote: Enumerating objects: 215, done. remote: Counting objects: 100% (215/215), done. remote: Compressing objects: 100% (137/137), done. remote: Total 215 (delta 108), reused 171 (delta 64), pack-reused 0 Receiving objects: 100% (215/215), 2.02 MiB | 1.04 MiB/s, done. Resolving deltas: 100% (108/108), done. -
Change to the build directory:
$ cd NGINX-Demos/nginx-nms-docker/ -
Run
dockerpsto verify that Docker is running and then run the buildNIM.sh script to build the Docker image. The‑ioption sets the automated build mode,‑Cand‑Kare required options which name the NGINX Management Suite certificate and key respectively, and the‑toption specifies the location and name of the private registry to which the image is pushed.$ ./scripts/buildNIM.sh -i -C nginx-repo.crt -K nginx-repo.key -t registry.ff.lan:31005/nginx-nms:2.5.1 ==> Building NGINX Management Suite docker image Sending build context to Docker daemon 92.19MB Step 1/18 : FROM ubuntu:22.04 ---> a8780b506fa4 Step 2/18 : ARG NIM_DEBFILE ---> Running in 0f2354280c34 Removing intermediate container 0f2354280c34 [...] ---> 0588a050c852 Step 18/18 : CMD /deployment/startNIM.sh ---> Running in d0cc5466a43d Removing intermediate container d0cc5466a43d ---> 25117ec0410a Successfully built 25117ec0410a Successfully tagged registry.ff.lan:31005/nginx-nms:2.5.1 The push refers to repository [registry.ff.lan:31005/nginx-nms] 9c4918474e3a: Pushed 42543d044dbb: Pushed 1621b2ec0a5e: Pushed c6a464fc6a79: Pushed 75fa1d3c61bb: Pushed 3501fcf5dbd8: Pushed d4a221057e67: Pushed 9ad05eafed57: Pushed f4a670ac65b6: Pushed 2.5.1: digest: sha256:9a70cfdb63b71dc31ef39e4f20a1420d8202c85784cb037b45dc0e884dad74c9 size: 2425
Running NGINX Management Suite on Kubernetes
Follow these instructions to prepare the Deployment manifest and start NGINX Management Suite on Kubernetes.
-
Base64‑encode the NGINX Management Suite license you downloaded in Step 4 of the previous section, and copy the output to the clipboard:
$ base64 -w0 nginx-mgmt-suite.lic TulNRS1WZXJz... -
Using your favorite editor, open manifests/1.nginx-nim.yaml and make the following changes:
-
In the
spec.template.spec.containerssection, replace the default image name (your.registry.tld/nginx-nim2:tag) with the Docker image name you specified with the‑toption in Step 3 of the previous section (in our case, registry.ff.lan:31005/nginx-nms:2.5.1):spec: ... template: ... spec: containers: - name: nginx-nim2 image: your.registry.tld/nginx-nim2:tag -
In the
spec.template.spec.containers.envsection, configure authentication credentials by making these substitutions in thevaluefield for each indicatedname:NIM_USERNAME– (Optional) Replace the defaultadminwith an admin account name.NIM_PASSWORD– (Required) Replace the defaultnimadminwith a strong password.NIM_LICENSE– (Required) Replace the default<BASE64_ENCODED_LICENSE_FILE>with the base64‑encoded license you generated in Step 1 above.
spec: ... template: ... spec: containers: ... env: ... - name: NIM_USERNAME value: admin - name: NIM_PASSWORD value: nimadmin - name: NIM_LICENSE value: "<BASE64_ENCODED_LICENSE_FILE>"
-
- Check and modify files under manifests/certs to customize the TLS certificate and key used for TLS offload by setting the FQDN you want to use. By default, the nimDockerStart.sh startup script publishes the containerized NGINX Management Suite through NGINX Ingress Controller.
-
Optionally, edit manifests/3.vs.yaml and customize the hostnames used to reach NGINX Management Suite.
-
Run nimDockerStart.sh to start NGINX Management Suite in your Kubernetes cluster. As indicated in the trace, it runs as the nginx-nim2 pod. The script also initializes pods for ClickHouse as the backend database and Grafana for analytics visualization. For more information, see the README at the GitHub repo.
$ ./scripts/nimDockerStart.sh start namespace/nginx-nim2 created ~/NGINX-NIM2-Docker/manifests/certs ~/NGINX-NIM2-Docker Generating a RSA private key .....................................+++++ .....................................+++++ writing new private key to 'nim2.f5.ff.lan.key' ----- secret/nim2.f5.ff.lan created configmap/clickhouse-conf created configmap/clickhouse-users created persistentvolumeclaim/pvc-clickhouse created deployment.apps/clickhouse created service/clickhouse created deployment.apps/nginx-nim2 created service/nginx-nim2 created service/nginx-nim2-grpc created persistentvolumeclaim/pvc-grafana-data created persistentvolumeclaim/pvc-grafana-log created deployment.apps/grafana created service/grafana created virtualserver.k8s.nginx.org/nim2 created virtualserver.k8s.nginx.org/grafana created ~/NGINX-NIM2-Docker -
Verify that three pods are now running:
$ kubectl get pods -n nginx-nim2 NAME READY STATUS RESTARTS AGE clickhouse-759b65db8c-74pn5 1/1 Running 0 63s grafana-95fbbf5c-jczgk 1/1 Running 0 63s nginx-nim2-5f54664754-lrhmn 1/1 Running 0 63s
Accessing NGINX Management Suite
To access NGINX Management Suite, navigate in a browser to https://nim2.f5.ff.lan (or the alternate hostname you set in Step 4 of the previous section). Log in using the credentials you set in Step 2 of the previous section.
Stopping NGINX Management Suite
To stop and remove the Docker instance of NGINX Management Suite, run this command:
$ ./scripts/nimDockerStart.sh stop
namespace "nginx-nim2" deletedGet Started
To try out the NGINX solutions discussed in this post, start a 30-day free trial today or contact us to discuss your use cases:
- NGINX Management Suite
- NGINX Ingress Controller based on NGINX Plus
