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
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 ornginx-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 thenginx-meshctl
binary andnginx-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 theregistry.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 thenginx-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 withinjector.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 containersregistry: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.