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 nginx-meshctl
Overview
This guide contains instructions for downloading and installing F5 NGINX Service Mesh using the nginx-meshctl
command line tool.
Prerequisites
Before installing NGINX Service Mesh, make sure you’ve completed the following steps.
- You have a working and supported Kubernetes or OpenShift cluster.
- You followed the 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.
Install the CLI
The following sections describe how to install the CLI on Linux, macOS, and Windows.
Download nginx-meshctl
The NGINX Service Mesh command-line tool – nginx-meshctl
– allows you to deploy, remove, and interact with the NGINX Service Mesh control plane.
To install NGINX Service Mesh, you need to download the nginx-meshctl
binary for your architecture. The latest version of nginx-meshctl
is available on our Github releases page.
Install on Linux
-
Download the appropriate binary for your architecture, either
nginx-meshctl_<version>_linux_amd64.tar.gz
ornginx-meshctl_<version>_linux_arm64.tar.gz
. -
Unzip the binary.
tar -xvf nginx-meshctl_<version>_linux_amd64.tar.gz nginx-meshctl
-
Move the
nginx-meshctl
executable in to your PATH.sudo mv nginx-meshctl /usr/local/bin/nginx-meshctl
-
Ensure the
nginx-meshctl
is executable.sudo chmod +x /usr/local/bin/nginx-meshctl
-
Test the installation.
nginx-meshctl
Install on macOS
-
Download the appropriate binary for your architecture, either
nginx-meshctl_<version>_darwin_arm64.tar.gz
for M1 Macs ornginx-meshctl_<version>_darwin_amd64.tar.gz
for Intel based Macs. -
Unzip the binary.
tar -xvf nginx-meshctl_<version>_darwin_amd64.tar.gz nginx-meshctl
-
Move the
nginx-meshctl
executable in to your PATH.sudo mv nginx-meshctl /usr/local/bin/nginx-meshctl
-
Ensure the
nginx-meshctl
is executable.sudo chmod +x /usr/local/bin/nginx-meshctl
-
Test the installation.
nginx-meshctl
Install on Windows
-
Download the appropriate binary for your architecture, either
nginx-meshctl_<version>_windows_amd64.zip
ornginx-meshctl_<version>_windows_arm64.zip
. -
Extract the binary,
nginx-meshctl.exe
, from the zip file. -
Add the binary to your PATH.
-
Test the installation.
nginx-meshctl
Install the NGINX Service Mesh Control Plane
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.
Check out the Configuration Options to learn about the deployment options.
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.
Follow the steps below to install the NGINX Service Mesh control plane.
-
Run the
nginx-meshctl deploy
command using the desired options.Examples:
Deploy NGINX Service Mesh using all of the default settings for the latest release:
nginx-meshctl deploy
OpenShift users must add the
--environment openshift
flag when deploying:nginx-meshctl deploy --environment openshift
Disable Persistent Storage if it is not configured in your cluster:
nginx-meshctl deploy --persistent-storage off
-
Verify the pods are running. If running in OpenShift, you will see additional
spiffe-csi-driver
Pods.$ kubectl get pods -n nginx-mesh NAME READY STATUS RESTARTS AGE nats-server-84f8b6f669-xszkc 1/1 Running 0 14m nginx-mesh-controller-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
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. Some 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.