CLI Reference

Usage

nginx-meshctl is the CLI utility for controlling NGINX Service Mesh.

The CLI requires a connection to a Kubernetes cluster via a kubeconfig.

Usage:
  nginx-meshctl [flags]
  nginx-meshctl [command]

Available Commands:
  config      Display the NGINX Service Mesh configuration.
  deploy      Deploys NGINX Service Mesh into your Kubernetes cluster.
  help        Help for nginx-meshctl or any command.
  inject      Inject the NGINX Service Mesh sidecars into Kubernetes resources.
  remove      Remove NGINX Service Mesh from your Kubernetes cluster.
  services    List the Services registered with NGINX Service Mesh.
  status      Check connection to NGINX Service Mesh API.
  top         Display traffic statistics.
  version     Display version info.

Flags:
  -h, --help                Help for nginx-meshctl.
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Config

Configures Kubernetes settings used by NGINX Service Mesh.

Usage: `nginx-meshctl config [flags]`

Flags:
  -h, --help   Help for config.

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Deploy

Deploys NGINX Service Mesh into your Kubernetes cluster.

The deploy command installs the following resources into your Kubernetes cluster by default:

  • Mesh API: The Control Plane for NGINX Service Mesh
  • Metrics API: SMI-formatted metrics
  • Tracing Server: Opentracing
  • Prometheus Server: Metrics
  • Grafana: Visualization for metrics
  • SPIRE: mTLS service-to-service communication

Usage: nginx-meshctl deploy [flags]

Flags:
      --access-control-mode string     Default access control mode for service-to-service communication.
                                          Valid values: allow, deny (default "allow")
      --deploy-grafana                 Deploy Grafana as a part of the NGINX Service Mesh.
                                          Valid values: true, false (default true)
      --disable-auto-inject            Disable automatic sidecar injection upon resource creation.
                                       		Use the --enabled-namespaces flag to enable automatic injection in select namespaces.
      --disable-tracing                Disable tracing for all services.
      --disabled-namespaces strings    Disable automatic sidecar injection for specific namespaces.
                                       		Cannot be used with --disable-auto-inject.
      --enabled-namespaces strings     Enable automatic sidecar injection for specific namespaces.
                                       		Must be used with --disable-auto-inject.
  -h, --help                           Help for deploy.
      --image-tag string               Tag used for pulling images from registry
                                       		Affects: nginx-mesh-api, nginx-mesh-metrics, nginx-mesh-sidecar, nginx-mesh-init, nginx-mesh-cert-reloader
      --mtls-ca-ttl string             The CA/signing key TTL. (default "5040h")
      --mtls-mode string               mTLS mode for pod-to-pod communication.
                                       		Valid values: off, permissive, strict (default "permissive")
      --mtls-svid-ttl string           The TTL of certificates issued to workloads. (default "1h")
      --mtls-trust-domain string       The trust domain of the NGINX Service Mesh. (default "example.org")
      --mtls-upstream-ca-conf string   The upstream certificate authority configuration file.
      --nginx-error-log-level string   NGINX error log level.
                                       		Valid values: debug, info, notice, warn, error, crit, alert, emerg (default "warn")
      --nginx-lb-method string         NGINX load balancing method.
                                       		Valid values: [least_conn, least_time, least_time last_byte, least_time last_byte inflight, random, random two, random two least_conn, random two least_time, random two least_time=last_byte, round_robin] (default "least_time")
      --nginx-log-format string        NGINX log format.
                                       		Valid values: default, json (default "default")
      --persistent-storage string      Use persistent storage. "auto" will enable persistent storage if a default StorageClass exists.
                                       		Valid values: auto, off, on (default "auto")
      --prometheus-address string      The address of a Prometheus server deployed in your Kubernetes cluster.
                                       		Address should be in the format <service-name>.<namespace>:<service-port>.
      --registry-key string            Path to JSON Key file for accessing private registry.
                                       		Cannot be used with --registry-username or --registry-password.
      --registry-password string       Password for accessing private registry.
                                       		Requires --registry-username to be set. Cannot be used with --registry-key.
      --registry-server string         Hostname:port (if needed) for registry and path to images.
                                       		Affects: nginx-mesh-api, nginx-mesh-metrics, nginx-mesh-sidecar, nginx-mesh-init
      --registry-username string       Username for accessing private registry.
                                       		Requires --registry-password to be set. Cannot be used with --registry-key.
      --sample-rate float32            The sample rate to use for tracing. Float between 0 and 1. (default 0.01)
      --tracing-address string         The address of a Jaeger or Zipkin tracing server deployed in your Kubernetes cluster.
                                       		Address should be in the format <service-name>.<namespace>:<service_port>.
      --tracing-backend string         The tracing backend that you want to use.
                                       		Valid values: jaeger, zipkin (default "jaeger")

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Deploy Examples

Most of the examples below show shortened commands for convenience. The ‘…’ in these examples represents the image references. Be sure to include the image references when running the deploy command.

  • Deploy the latest version of NGINX Service Mesh, using default values, from your container registry:

    nginx-meshctl deploy --registry-server "registry:5000"

  • Deploy the Service Mesh in namespace “my-namespace”:

    nginx-meshctl deploy ... --namespace my-namespace

  • Deploy the Service Mesh with mTLS and automatic injection turned off:

    nginx-meshctl deploy ... --mtls-mode off --disable-auto-inject

  • Deploy the Service Mesh and only allow automatic injection in namespace “my-namespace”:

    nginx-meshctl deploy ... --disable-auto-inject --enabled-namespaces="my-namespace"

  • Deploy the Service Mesh and disallow automatic injection in namespaces “my-namespace-1” and “my-namespace-2”

    nginx-meshctl deploy ... --disabled-namespaces="my-namespace-1,my-namespace-2"

  • Deploy the Service Mesh with tracing disabled:

    nginx-meshctl deploy ... --disable-tracing

  • Deploy the Service Mesh with a custom tracing server in your Kubernetes cluster:

    nginx-meshctl deploy ... --tracing-backend="jaeger" --tracing-address="my-jaeger-server.my-namespace.svc.cluster.local:9411"

  • Deploy the Service Mesh with upstream certificates and keys for mTLS:

    nginx-meshctl deploy ... --mtls-upstream-ca-conf="disk.yaml"

Inject

Inject the NGINX Service Mesh sidecar into Kubernetes resources.

  • Accepts JSON and YAML formats.
  • Outputs JSON or YAML resources with injected sidecars to stdout.

Usage: nginx-meshctl inject [flags]

Flags:
  -f, --file string                  The filename that contains the resources you want to inject. If no filename is provided, input will be taken from stdin.
  -h, --help                         Help for inject.
      --ignore-incoming-ports ints   Ports to ignore for incoming traffic.
      --ignore-outgoing-ports ints   Ports to ignore for outgoing traffic.

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Inject Examples

  • Inject the resources in my-app.yaml and create in Kubernetes:

    nginx-meshctl inject -f ./my-app.yaml | kubectl apply -f -

  • Inject the resources passed into stdin and write the changes to the same file:

    nginx-meshctl inject < ./my-app.json > ./my-injected-app.json

  • Inject the resources in my-app.yaml and configure proxies to ignore ports 1433 and 1434 for outgoing traffic:

    nginx-meshctl inject --ignore-outgoing-ports 1433,1434 -f ./my-app.yaml

  • Inject the resources passed into stdin and configure proxies to ignore port 1433 for incoming traffic:

    nginx-meshctl inject --ignore-incoming-ports 1433 < ./my-app.json

Remove

Remove the NGINX Service Mesh from your Kubernetes cluster.

  • Removes the resources created by the deploy command from the Service Mesh namespace (default: “nginx-mesh”).
  • You will need to clean up all Deployments with injected proxies manually.

Usage: nginx-meshctl remove [flags]

Flags:
  -h, --help   Help for remove.
  -y, --yes    Answer yes for confirmation of removal.

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Remove Examples

  • Remove the NGINX Service Mesh from the default namespace (“nginx-mesh”):

    nginx-meshctl remove

  • Remove the NGINX Service Mesh from namespace “my-namespace”:

    nginx-meshctl remove --namespace my-namespace

  • Remove the NGINX Service Mesh without prompting the user to confirm removal:

    nginx-meshctl remove -y

Services

List the Services registered with NGINX Service Mesh.

  • Outputs the Services and their upstream addresses and ports.
  • The list contains only those Services whose Pods contain the NGINX Service Mesh sidecar.

Usage: nginx-meshctl services [flags]

Flags:
  -h, --help   Help for services.

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)

Top

Display traffic statistics.

Top provides information about the incoming and outgoing requests to and from a resource type or name. Supported resource types are: Pods, Deployments, StatefulSets, DaemonSets, and Namespaces.

Usage:
  nginx-meshctl top [resource-type/resource] [flags]

Flags:
  -h, --help   Help for top.
  -n, --namespace string   Namespace where the resource(s) resides. (default "default")

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user>/.kube/config")

Top Examples

  • Display traffic statistics for all Deployments:

    nginx-meshctl top

  • Display traffic statistics for all Pods:

    nginx-meshctl top pods

  • Display traffic statistics for Deployment “my-app”:

    nginx-meshctl top deployments/my-app

Upgrade

Upgrade NGINX Service Mesh to the latest version.

This command removes the existing NGINX Service Mesh while preserving user configuration data. The latest version of NGINX Service Mesh is then deployed using that data.

Usage:
  nginx-meshctl upgrade [flags]

Flags:
  -h, --help   Help for upgrade.
  -y, --yes    Answer yes for confirmation of upgrade.

Global Flags:
  -k, --kubeconfig string   Path to kubectl config file. (default "/Users/<user/.kube/config")
  -n, --namespace string    NGINX Service Mesh control plane namespace. (default "nginx-mesh")
  -t, --timeout duration    Timeout when communicating with NGINX Service Mesh API Server. (default 5s)