End of Sale Notice:

Commercial support for NGINX Service Mesh is available to customers who currently have active NGINX Microservices Bundle subscriptions. F5 NGINX announced the End of Sale (EoS) for the NGINX Microservices Bundles as of July 1, 2023.

See our End of Sale announcement for more details.

Install with Helm

This guide explains how to install F5 NGINX Service Mesh using Helm.

Prerequisites

Before installing F5 NGINX Service Mesh, make sure you’ve completed the following steps.

• You have Helm version 3.2.0 or newer installed.
• You have a working and supported Kubernetes or OpenShift cluster.
• You followed the Kubernetes or OpenShift Platform Setup guide to prepare your cluster to work with NGINX Service Mesh.
• You have the Kubernetes kubectl command-line utility configured on the machine where you want to install NGINX Service Mesh.
• You reviewed the Configuration Options.

Get the Chart

When installing with Helm, you can either add the NGINX Service Mesh Helm repository or download the charts from GitHub.

Add the Helm Repository

This step is required if you’re installing the chart via the helm repository.

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

Download the Chart from GitHub

This step is required if you’re installing the chart using its sources. Additionally, this step is required for upgrading the NGINX Service Mesh Custom Resource Definitions (CRDs).

git clone https://github.com/nginxinc/nginx-service-mesh
cd nginx-service-mesh/helm-chart
git checkout v2.0.0

Install the Chart

NGINX Service Mesh requires a dedicated namespace for the control plane. You can create this namespace yourself, or allow Helm to create it for you via the --create-namespace flag when installing. This namespace is dedicated to the NGINX Service Mesh control plane and should not be used for anything else.

NGINX Service Mesh will pull multiple required images into your Kubernetes cluster in order to function, some of which are from publicly-accessible third parties. For a full list refer to the Technical Specifications. If you are using a private registry, see our private registry guide.

If Persistent Storage is not configured in your cluster, disable it in the mesh by adding the --set mtls.persistentStorage=off flag to the install commands below.

OpenShift users must add the --set environment=openshift flag to the install commands below.

Install via Repository

To install the chart with the release name nsm and namespace nginx-mesh, run:

helm install nsm nginx-stable/nginx-service-mesh --namespace nginx-mesh --create-namespace --wait

Install via Source

To install the chart with the release name nsm and namespace nginx-mesh, run:

helm install nsm . --namespace nginx-mesh --create-namespace --wait

NGINX Service Mesh control plane Pods may take some time to become Ready once installed. Some Pods may display error logs during the startup process. This typically occurs as the Pods attempt to connect to each other.

OpenShift users may see error events related to security contexts while the NGINX Service Mesh control plane is installing. These should resolve themselves as each component becomes ready.

Ensure all control plane Pods are in a Ready state before deploying your applications.

Next Steps

Congratulations! At this point NGINX Service Mesh should be successfully installed in your cluster.

Add the Sidecar to Your Workloads

Now that the control plane is deployed in your cluster, it is time to add the sidecar to your workloads so you can start using the mesh. Check out the Sidecar Proxy Injection doc for instructions on how to do that.

Troubleshooting

If the mesh fails to install, review the Platform Setup docs for your platform, the installation steps above, and the Configuration Options to ensure everything is configured correctly. A couple frequent problem areas are cluster permissions, security contexts (particularly in OpenShift), and Persistent Storage.

If the mesh installation failed or you pressed ctrl-C during deployment, make sure to first remove the mesh before attempting to re-install.

If you are unable to resolve the issues, please reach out to the appropriate support channel.

Configuration Options

The values.yaml file within the nginx-service-mesh Helm chart contains the deployment configuration for NGINX Service Mesh. These configuration fields map directly to the nginx-meshctl deploy command-line options mentioned throughout our documentation. More details about these options can be found in the Configuration guide. You can update these fields directly in the values.yaml file, or by specifying the --set flag when running helm install.

The following table lists the configurable parameters of the NGINX Service Mesh chart and their default values.