Web Server Load Balancing with NGINX Plus

NGINX Documentation

What's on this Page

Install NGINX Service Mesh

Overview

This topic contains instructions for downloading and installing NGINX Service Mesh.

Prerequisites

  • You have a working Kubernetes cluster, version 1.16 or newer.
  • 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.

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 as well as the nginx-mesh-images package containing all the NGINX Service Mesh images. See the Install the CLI and Download and Push Images to Container Registry sections for further instructions.

Install the CLI

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

Install on Linux

  1. Download the appropriate binary for your architecture, nginx-meshctl_linux.gz.

  2. Unzip the binary.

    gunzip nginx-meshctl_linux.gz

  3. Move the nginx-meshctl executable in to your PATH.

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

  4. Ensure the nginx-meshctl is executable.

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

  5. Test the installation.

    nginx-meshctl version

Install on macOS

  1. Download the appropriate binary for your architecture, nginx-meshctl_darwin.gz.

  2. Unzip the binary.

    gunzip nginx-meshctl_darwin.gz

  3. Move the nginx-meshctl executable in to your PATH.

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

  4. Ensure the nginx-meshctl is executable.

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

  5. Test the installation.

    nginx-meshctl version

Install on Windows

  1. Download the appropriate binary for your architecture, nginx-meshctl_windows.exe

  2. Add the binary to your PATH and rename.

  3. Test the installation.

    nginx-meshctl.exe version

Download and Push Images to Container Registry

In addition to the CLI binary, you need to download the NGINX Service Mesh images and push them to a container registry that your cluster can access.

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

  1. Download the nginx-mesh-images.X.Y.Z.tar.gz file. Where X.Y.Z is the appropriate version, for example, 1.0.0.

    This archive contains the following images:

    • nginx-mesh-api: NGINX Service Mesh API Server.
    • nginx-mesh-metrics: Gets pod and node metrics. Refer to SMI Metrics on GitHub for more information.
    • nginx-mesh-sidecar: NGINX Service Mesh sidecar.
    • nginx-mesh-init: NGINX Service Mesh sidecar init container. Sets up iptables for the sidecar.

    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.

  2. 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

  3. 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
    for image in $(ls)
do
  docker load < $image
done

  4. Tag each image appropriately for your environment and registry location.

    • nginx-mesh-api
    • nginx-mesh-metrics
    • nginx-mesh-init
    • nginx-mesh-sidecar
    docker tag <image-name>:X.Y.Z <your-docker-registry>/<image-name>:X.Y.Z

  5. Push each image.

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

Install the Service Mesh Control Plane

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.

  1. 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:

    nginx-meshctl deploy --registry-server <your-docker-registry/path/to/images> --image-tag <X.Y.Z>

    The --registry-server flag will accept a string referencing a docker name consisting of a domain and a variable number of path-components, describing the common path shared by all images. If the --registry-server flag is omitted, local images will be used. If you are using a private registry to store the NGINX Service Mesh images see the Private Registry guide for instructions.

    The --image-tag flag is optional and defaults to the version of the release.

    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, etc.

  2. 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
grafana-855bf57c67-hz4dt              1/1     Running   0          14m
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
prometheus-7bb967bb58-42c8l           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
zipkin-6fb7df55c4-rsq9g               1/1     Running   0          14m