Deploy App Delivery Manager on Kubernetes
The guide provides step-by-step instructions to deploy NGINX App Delivery Manager on Kubernetes using a Helm chart.
This topic describes an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.
Share your thoughts about the documentation by taking this short survey: https://forms.gle/w6eDi53F4UcmDjw68.
Requirements
Review the following requirements for App Delivery Manager before continuing.
Install Instance Manager
Important:
To install App Delivery Manager, you must first install Instance Manager. This is because App Delivery Manager relies on features that are included with Instance Manager.
Dependencies with Instance Manager
Refer to the following table to see the module compatibility for each NGINX Management Suite chart.
NGINX Management Suite chart | Instance Manager | API Connectivity Manager | App Delivery Manager |
---|---|---|---|
1.11.0 | 2.14.0 | 1.9.0 | 4.0.0-ea.3 |
1.10.1 | 2.13.1 | 1.9.0 | 4.0.0-ea.3 |
1.10.0 | 2.13.1 | 1.8.0 | 4.0.0-ea.3 |
1.9.0 | 2.13.0 | 1.8.0 | 4.0.0-ea.3 |
1.8.2 | 2.12.0 | 1.8.0 | 4.0.0-ea.3 |
1.8.1 | 2.12.0 | 1.8.0 | 4.0.0-ea.2 |
1.8.0 | 2.12.0 | 1.7.0 | 4.0.0-ea.2 |
1.7.2 | 2.11.0 | 1.7.0 | 4.0.0-ea.2 |
1.7.1 | 2.11.0 | 1.7.0 | 4.0.0-ea.1 |
1.7.0 | 2.11.0 | 1.6.0 | 4.0.0-ea.1 |
1.6.0 | 2.10.1 | 1.6.0 | 4.0.0-ea.1 |
1.5.2 | 2.10.0 | 1.6.0 | 4.0.0-ea.1 |
1.5.1 | 2.10.0 | 1.6.0 | |
1.5.0 | 2.10.0 | 1.5.0 | |
1.4.0 | 2.9.1 | 1.5.0 | |
1.3.1 | 2.9.0 | 1.5.0 | |
1.3.0 | 2.9.0 | 1.4.1 | |
1.2.1 | 2.8.0 | 1.4.1 | |
1.2.0 | 2.8.0 | 1.4.0 | |
1.1.2 | 2.7.0 | 1.4.1 | |
1.1.1 | 2.7.0 | 1.4.0 | |
1.1.0 | 2.7.0 | 1.3.1 | |
1.0.0 | 2.6.0 | 1.3.1 |
Download Docker Image
Follow these steps to download the Docker image for App Delivery Manager:
-
Go to the MyF5 website, then select Resources > Downloads.
-
In the Select Product Family list, select NGINX.
-
In the Product Line list, select NGINX App Delivery Manager.
-
Select the following download options:
- Product version – Select the version of App Delivery Manager you want to install. Make sure this version is compatible with the version of Instance Manager you installed as a prerequisite. Refer to the Dependencies with Instance Manager section above.
- Linux distribution – Select the Linux distribution you’re deploying to. For example, ubuntu.
- Distribution Version – Select the Linux distribution’s version. For example, 20.04.
- Architecture – Select the architecture. For example, amd64.
-
In the Download Files section, download the
nms-adm-<version>-img.tar.gz
file.
Load Docker Image
Note:
To complete the commands in this section, you need to have Docker 20.10 or later installed.
-
Change to the directory where you downloaded the Docker image:
cd <directory name>
-
Load the Docker image from the
nms-adm-<version>-img.tar.gz
archive:docker load -i nms-adm-<version>-img.tar.gz
The output looks similar to the following:
$ docker load -i nms-adm-<version>-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-adm:4.0.0
Important:
Take note of the loaded image’s name and tag. You’ll need to reference this information in the next section when pushing the image to your private registry.
In the example output above,
nms-adm
is the image name and4.0.0
is the tag. The image name or tag could be different depending on the product version you downloaded from MyF5.
Push Image 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 image above.
-
Log in to your private registry:
docker login <my-docker-registry:port>
-
Tag the image with the image name and version you noted when loading the Docker image.
docker tag nms-adm:<version> <my-docker-registry:port>/nms-adm:<version>
For example:
docker tag nms-adm:1.5 myregistryhost:5000/nms-adm:1.5
-
Push the image to your private registry:
docker push <my-docker-registry:port>/nms-adm:<version>
For example:
docker push nms-adm:1.5 myregistryhost:5000/nms-adm:1.5
Enable App Delivery Manager
To enable the App Delivery Manager module, take the following steps:
-
Open the
values.yaml
file for editing. -
Add the following snippet to the
values.yaml
file:- 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 image above. - In the
imagePullSecrets
section, add the credentials for your private Docker registry.
# values.yaml global: nmsModules: nms-adm: enabled: true nms-adm: imagePullSecrets: - name: regcred adm: image: repository: <my-docker-registry:port>/nms-adm tag: <version>
- Replace
-
Close and save the
values.yaml
file.
Upgrade NGINX Management Suite Deployment
Note:
To complete the steps in this section, you need to have OpenSSL 1.1.1 or later installed.
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.
Upgrade Existing App Delivery Manager Deployment
If you’ve already deployed App Delivery Manager and would like to upgrade to a newer version, take the following steps:
-
Repeat the steps above to:
-
Run the
helm upgrade
command above to upgrade the NGINX Management Suite deployment.
Access Web Interface
You can access the NGINX Management Suite 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 License
A valid license is required to make full use of all the features in App Delivery 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.
Configurable Helm Settings
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.
The following table lists the configurable parameters and default values used by the App Delivery Manager chart when installing from a Helm chart.
Parameter | Description | Default |
---|---|---|
nms-adm.adm.logLevel |
Set the log level for the backend API service. The log level can be fatal , error , warning , info , or debug |
info |
nms-adm.adm.image.repository |
Repository name and path for the adm image. |
adm |
nms-adm.adm.image.tag |
Tag used for pulling images from registry. | latest |
nms-adm.adm.image.pullPolicy |
Image pull policy. | IfNotPresent |
nms-adm.adm.container.port.http |
TCP port for the pod to listen on. | 8039 |
nms-adm.adm.container.port.db |
Port to use for Dqlite. | 7811 |
nms-adm.adm.service.httpPort |
TCP port for the service to listen on. | 8039 |
nms-adm.adm.resources.requests.cpu |
CPU resource limits to allow for the adm pods. |
500m |
nms-adm.adm.resources.requests.memory |
Memory resource limits to allow for the api pods. |
512Mi |
nms-adm.adm.persistence.enabled |
Optionally disable persistent storage, used for database data. | true |
nms-adm.adm.persistence.claims |
An array of persistent volume claims, can be modified to use an existing PVC. | See Dqlite and Templates. |
App Delivery Manager Dqlite Configuration
- name: dqlite
existingClaim:
size: 500Mi
accessMode: ReadWriteOnce
App Delivery Manager Templates Configuration
The following volume persists the App Delivery Manager templates’ directories and preserves the new files a user may add to the templates directory.
- name: templates
existingClaim:
size: 500Mi
accessMode: ReadWriteOnce
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.