Private Registry


NGINX Service Mesh supports using a private registry to store its components. In order to deploy NGINX Service Mesh from a private registry, you need to configure the NGINX Service Mesh CLI with credentials that can access the registry.

CLI Flags

You can use the following NGINX Service Mesh CLI flags to configure private registry access.

Flag Description
--registry-key The path on disk to a JSON key file that allows access to the registry. Cannot be used with --registry-username or --registry-password.
--registry-username The username to access the private registry. Cannot be used with --registry-key. Must be used with --registry-password.
--registry-password The password to access the private registry. Cannot be used with --registry-key. Must be used with --registry-username.
--registry-server The host name and port (if needed) of the private registry, for example, “”. Can also contain the path, though only the domain is used for authentication. Pull requests for images to this registry will authenticate using the provided credentials.

There are two methods of accessing a private registry:

  • For registries that support authentication via a JSON key, you can specify the path to the JSON key using --registry-key. The path can be relative to the working directory or absolute.
  • For registries that only support username and password, those can be specified with --registry-username and --registry-password.
Using the --registry-password flag can expose your plain text password on the console and in the console history.


Deploy from a private registry using a JSON Key:

nginx-meshctl deploy ... --registry-server <your-docker-registry> --registry-key </path/to/key.json>

Deploying from a private registry using a username and password:

nginx-meshctl deploy ... --registry-server <your-docker-registry> --registry-username <your-username> --registry-password <your-password>

How it Works

When deploying with the private registry flags, nginx-meshctl will create a Kubernetes Secret (example below) that encapsulates the secret data:

apiVersion: v1
kind: Secret
    name: nginx-mesh-registry-key
    namespace: nginx-mesh
        usage: nginx-mesh-registry-key
    .dockerconfigjson: <base64-encoded-key>

The is a base64 encoded JSON that encapsulates the secret data with a header. When using the --registry-key option, that section looks like:

    "auths": {
        "<your-docker-registry as specified with --registry-server>": {
            "username": "_json_key",
            "password": "<your-json-key as specified with --registry-key>"

NGINX Service Mesh creates the Kubernetes Secret in its namespace. Kubernetes Secrets aren’t cluster-wide, so when injecting a pod with a sidecar, NGINX Service Mesh duplicates the Kubernetes Secret into the namespace of that pod.

NGINX Service Mesh will additionally inject the below yaml snippet into Pods injected with a sidecar. This allows the Pod to use the Kubernetes Secret to pull the NGINX Service Mesh sidecar container:

- name: nginx-mesh-registry-key

When you remove NGINX Service Mesh, all of the Kubernetes Secrets that it created are deleted. It uses a label selector to get a list of all the Kubernetes Secrets with the label usage=nginx-mesh-registry-key. You can simulate this operation using kubectl:

kubectl get secrets -l usage=nginx-mesh-registry-key -A