Install NGINX Service Mesh using nginx-meshctl

This topic explains how to download, install, and deploy NGINX Service Mesh.

Overview

This topic contains instructions for downloading and installing NGINX Service Mesh using the nginx-meshctl command line tool.

For Helm users, see how to Install NGINX Service Mesh using Helm.

Prerequisites

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

You have a working Kubernetes cluster, version 1.18 or newer.
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 for NGINX Service Mesh.

Download NGINX Service Mesh

Note:
NGINX Microservice Bundle customers can download the nginx-meshctl tool from MyF5.

In order to download NGINX Service Mesh, you’ll need to register for an account at the F5 Downloads site. Once you have registered, click on the Find a Download button to see a list of the available products and select the NGINX_Service_Mesh product line. From the NGINX_Service_Mesh product page, you can select the version you would like to install from the dropdown menu and click on the product name to view the files available for download.

To install and deploy NGINX Service Mesh you need to download the nginx-meshctl binary for your architecture.

In addition to the binary, you also need access to all of the NGINX Service Mesh docker images. There are multiple ways to access these images:

Pull the Images from the Docker Registry
Pull the Images from MyF5
Download and Push Images to Container Registry.

Install the CLI

The NGINX Service Mesh command-line tool – nginx-meshctl – allows you to deploy, remove, and interact with the NGINX Service Mesh control plane. The following sections describe how to install the CLI on Linux, macOS, and Windows.

Install on Linux

Download the appropriate binary for your architecture, nginx-meshctl_linux-amd64.gz.
Unzip the binary.
```
gunzip nginx-meshctl_linux-amd64.gz
```

Move the nginx-meshctl executable in to your PATH.

sudo mv nginx-meshctl_linux-amd64 /usr/local/bin/nginx-meshctl

Ensure the nginx-meshctl is executable.

sudo chmod +x /usr/local/bin/nginx-meshctl

Test the installation.
```
nginx-meshctl version
```

Install on macOS

Download the appropriate binary for your architecture, either nginx-meshctl_darwin-arm64.gz for M1 Macs or nginx-meshctl_darwin-amd64 for Intel based Macs.
Unzip the binary.
```
gunzip nginx-meshctl_darwin-amd64.gz
```

Move the nginx-meshctl executable in to your PATH.

sudo mv nginx-meshctl_darwin-amd64 /usr/local/bin/nginx-meshctl

Ensure the nginx-meshctl is executable.

sudo chmod +x /usr/local/bin/nginx-meshctl

Test the installation.
```
nginx-meshctl version
```

Install on Windows

Download the appropriate binary for your architecture, nginx-meshctl_windows-amd64.exe
Add the binary to your PATH and rename.
Test the installation.
```
nginx-meshctl.exe version
```

Images

NGINX Service Mesh distributes a number of images and pulls additional publicly-accessible third-party container images into your Kubernetes cluster in order to function. For a full list refer to the Technical Specifications.

Manually Download and Push Images to Container Registry

NGINX Service Mesh images are pulled in automatically when deploying the mesh. However, if desired, you can manually download and push them to your own container registry that your cluster can access.

Important:
It is highly recommended that you match the version number when downloading the nginx-meshctl binary and nginx-mesh-images package. We make no compatibility guarantees across versions. For information on how to upgrade your existing mesh, see Upgrade NGINX Service Mesh.

Follow these steps to download, load, tag, and push the images:

Download the nginx-mesh-images.X.Y.Z.tar.gz file. Where X.Y.Z is the appropriate version and matches the binary downloaded in the previous section; for example, 1.0.0.

Each image file is a Docker-formatted tar archive. You can use the docker load command to make them accessible by your local Docker daemon. For instructions on how to download these files see the Download NGINX Service Mesh section.

Extract the contents of the tar archive and cd into the release directory.
```
tar zxvf nginx-mesh-images.X.Y.Z.tar.gz
cd nginx-mesh-images-X.Y.Z
```
Run the docker load command for each of the image files listed below.
- nginx-mesh-api.X.Y.Z.tar.gz
- nginx-mesh-metrics.X.Y.Z.tar.gz
- nginx-mesh-init.X.Y.Z.tar.gz
- nginx-mesh-sidecar.X.Y.Z.tar.gz
- nginx-mesh-cert-reloader.X.Y.Z.tar.gz
- nginx-mesh-csi-driver.X.Y.Z.tar.gz
```
for image in $(ls)
do
  docker load < $image
done
```
Tag each image appropriately for your environment and registry location.
- nginx-mesh-api
- nginx-mesh-metrics
- nginx-mesh-init
- nginx-mesh-sidecar
- nginx-mesh-cert-reloader
- nginx-mesh-csi-driver
```
docker tag <image-name>:X.Y.Z <your-docker-registry>/<image-name>:X.Y.Z
```

Push each image.

docker push <your-docker-registry>/<image-name>:X.Y.Z

When deploying NGINX Service Mesh using nginx-meshctl, set the --registry-server flag to your registry. If using Helm, set the registry.server field to your registry.

Air Gap Environment

If your environment does not have access to public image repositories, then you will need to manually pull the images from this list, and push them to your private registry. The image names and tags must remain the same. For example:

gcr.io/spiffe-io/spire-agent:1.4.4 would become your-registry/spire-agent:1.4.4

nats:2.9.3-alpine3.16 would become your-registry/nats:2.9.3-alpine3.16

When running nginx-meshctl deploy, use the --disable-public-images flag to instruct the mesh to use your --registry-server for all images. For example:

nginx-meshctl deploy --registry-server your-registry --disable-public-images ...

Install the NGINX Service Mesh Control Plane

See Also:
Check out Getting Started with NGINX Service Mesh to learn about the deployment options before proceeding.
You can find the full list of options in the nginx-meshctl Reference.

Important:
nginx-meshctl creates the namespace for the NGINX Service Mesh control plane.
This namespace is dedicated to the NGINX Service Mesh control plane and should not be used for anything else.
If desired, you can specify any name for the namespace via the --namespace argument, but do not create this namespace yourself.

Take the steps below to install the NGINX Service Mesh control plane.

Run the nginx-meshctl deploy command using the desired options.

For example, the following command will deploy NGINX Service Mesh using all of the default settings for the latest release:
```
nginx-meshctl deploy
```
Note:
We recommend deploying the mesh with auto-injection disabled globally, using the --disable-auto-inject flag. This ensures that Pods are not automatically injected without your consent, especially in system namespaces. You can opt-in the namespaces where you would like auto-injection enabled using --enabled-namespaces "namespace-1,namespace-2" or by labeling a namespace with injector.nsm.nginx.com/auto-inject=enabled.

If you are using a private registry to store the NGINX Service Mesh images see the Private Registry guide for instructions.

For example, nginx-meshctl deploy --registry-server "registry:5000/images" --image-tag X.Y.Z will look for containers registry:5000/images/nginx-mesh-api:X.Y.Z, registry:5000/images/nginx-mesh-sidecar:X.Y.Z, and so on.

Run the kubectl get pods command to verify that the Pods are up and running.

Be sure to specify the nginx-mesh namespace when running the command.

$ kubectl -n nginx-mesh get pods
NAME                                  READY   STATUS    RESTARTS   AGE
nats-server-84f8b6f669-xszkc          1/1     Running   0          14m
nginx-mesh-api-954467945-sc7qh        1/1     Running   0          14m
nginx-mesh-metrics-57464df46d-qskd2   1/1     Running   0          14m
spire-agent-92ktv                     1/1     Running   0          15m
spire-agent-9dbn6                     1/1     Running   0          15m
spire-agent-z5cq6                     1/1     Running   0          15m
spire-server-0                        2/2     Running   0          15m

Note:
If running in OpenShift, you will see two pods per Spire Agent container.

UDP MTU Sizing

Note:
UDP traffic proxying is turned off by default. You can activate it at deploy time using the --enable-udp flag. Linux kernel 4.18 or greater is required.

NGINX Service Mesh automatically detects and adjusts the eth0 interface to support the 32 bytes of space required for PROXY Protocol V2. See the UDP and eBPF architecture section for more information.

NGINX Service Mesh does not detect changes made to the MTU in the pod at runtime. If adding a CNI changes the MTU of the eth0 interface of running pods, you should re-roll the affected pods to ensure those changes take place.