Get the NGINX Ingress Controller image with JWT

This document describes how to pull the F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using your JWT token.

Overview

Important:

An NGINX Plus subscription certificate and key will not work with the F5 Docker registry.

For NGINX Ingress Controller, you must have an NGINX Ingress Controller subscription – download the NGINX Plus Ingress Controller (per instance) JWT access token from MyF5.

To list the available image tags using the Docker registry API, you will also need to download the NGINX Plus Ingress Controller (per instance) certificate (nginx-repo.crt) and the key (nginx-repo.key) from MyF5.

Note:

You can also get the image using alternative methods:

You can use Docker to pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the Get NGINX Ingress Controller from the F5 Registry topic.

You can follow the Build NGINX Ingress Controller topic.

If you would like to use an NGINX Ingress Controller image with NGINX open source, we provide the image through DockerHub.

Before You Begin

You will need the following information from MyF5 for these steps:

A JWT Access Token (per instance) for NGINX Ingress Controller from an active NGINX Ingress Controller subscription.
The certificate (nginx-repo.crt) and key (nginx-repo.key) for each NGINX Ingress Controller instance, used to list the available image tags from the Docker registry API.

Prepare NGINX Ingress Controller

Choose your desired NGINX Ingress Controller Image.
Log into the MyF5 Portal, navigate to your subscription details, and download the relevant .cert, .key and .JWT files.
Create a Kubernetes secret using the JWT token. You should use cat to view the contents of the JWT token and store the output for use in later steps.
Ensure there are no additional characters or extra whitespace that might have been accidentally added. This will break authorization and prevent the NGINX Ingress Controller image from being downloaded.
Modify your deployment (manifest or Helm) to use the Kubernetes secret created in step 3.
Deploy NGINX Ingress Controller into your Kubernetes cluster and verify that the installation has been successful.

Using the JWT token in a Docker Config Secret

Create a Kubernetes docker-registry secret type on the cluster, using the JWT token as the username and none for password (as the password is not used). The name of the docker server is private-registry.nginx.com.
```
kubectl create secret docker-registry regcred --docker-server=private-registry.nginx.com --docker-username=<JWT Token> --docker-password=none [-n nginx-ingress]
```
It is important that the --docker-username=<JWT Token> contains the contents of the token and is not pointing to the token itself. Ensure that when you copy the contents of the JWT token, there are no additional characters or extra whitespaces. This can invalidate the token and cause 401 errors when trying to authenticate to the registry.
Confirm the details of the created secret by running:
```
kubectl get secret regcred --output=yaml
```
You can now use the newly created Kubernetes secret in Helm and manifest deployments.

Note:

For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history:

JWTs: JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access.

Shell history: Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your ~/.bash_history file. Alternatively, you can run the history -c command to erase your shell history.

Follow these practices to help ensure the security of your system and data.

Manifest Deployment

The page “Installation with Manifests” explains how to install NGINX Ingress Controller using manifests. The following snippet is an example of a deployment:

spec:
  serviceAccountName: nginx-ingress
  imagePullSecrets:
  - name: regcred
  automountServiceAccountToken: true
  securityContext:
    seccompProfile:
      type: RuntimeDefault
  containers:
  - image: private-registry.nginx.com/nginx-ic/nginx-plus-ingress:4.0.0
    imagePullPolicy: IfNotPresent
    name: nginx-plus-ingress

The imagePullSecrets and containers.image lines represent the Kubernetes secret, as well as the registry and version of NGINX Ingress Controller we are going to deploy.

Helm Deployment

If you are using Helm for deployment, there are two main methods: using sources or charts.

Helm Source

The Installation with Helm documentation has a section describing how to use sources: these are the unique steps for Docker secrets using JWT tokens.

Clone the NGINX kubernetes-ingress repository.
Navigate to the charts/nginx-ingress folder of your local clone.

Open the values.yaml file in an editor.

You must change a few lines NGINX Ingress Controller with NGINX Plus to be deployed.

Change the nginxplus argument to true.
Change the repository argument to the NGINX Ingress Controller image you intend to use.
Add an argument to imagePullSecretName or imagePullSecretsNames to allow Docker to pull the image from the private registry.

The following code block shows snippets of the parameters you will need to change, and an example of their contents:

## Deploys the Ingress Controller for NGINX Plus
nginxplus: true
## Truncated fields
## ...
## ...
image:
## The image repository for the desired NGINX Ingress Controller image
repository: private-registry.nginx.com/nginx-ic/nginx-plus-ingress

## The version tag
tag: 4.0.0

serviceAccount:
    ## The annotations of the service account of the Ingress Controller pods.
    annotations: {}

## Truncated fields
## ...
## ...

    ## The name of the secret containing docker registry credentials.
    ## Secret must exist in the same namespace as the helm release.
    ## Note that also imagePullSecretsNames can be used here if multiple secrets need to be set.
    imagePullSecretName: regcred

With the modified values.yaml file, you can now use Helm to install NGINX Ingress Controller, for example:

helm install nicdev01 -n nginx-ingress --create-namespace -f values.yaml .

The above command will install NGINX Ingress Controller in the nginx-ingress namespace.

If the namespace does not exist, --create-namespace will create it. Using -f values.yaml tells Helm to use the values.yaml file that you modified earlier with the settings you want to apply for your NGINX Ingress Controller deployment.

Helm Chart

If you want to install NGINX Ingress Controller using the charts method, the following is an example of using the command line to pass the required arguments using the set parameter.

helm install my-release -n nginx-ingress oci://ghcr.io/nginxinc/charts/nginx-ingress --version 2.0.0 --set controller.image.repository=private-registry.nginx.com/nginx-ic/nginx-plus-ingress --set controller.image.tag=4.0.0 --set controller.nginxplus=true --set controller.serviceAccount.imagePullSecretName=regcred

You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, for example:

   $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq

   {
    "name": "nginx-ic/nginx-plus-ingress",
    "tags": [
        "4.0.0-alpine",
        "4.0.0-alpine-fips",
        "4.0.0-ubi",
        "4.0.0"
    ]
    }

   $ curl <https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list> --key <path-to-client.key> --cert <path-to-client.cert> | jq
   {
    "name": "nginx-ic-nap/nginx-plus-ingress",
    "tags": [
        "4.0.0-alpine-fips",
        "4.0.0-ubi",
        "4.0.0"
    ]
    }

   $ curl <https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list> --key <path-to-client.key> --cert <path-to-client.cert> | jq
   {
    "name": "nginx-ic-dos/nginx-plus-ingress",
    "tags": [
        "4.0.0-ubi",
        "4.0.0"
    ]
    }

Pulling an Image for Local Use

If you need to pull the image for local use to then push to a different container registry, use this command:

docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none

Replace the contents of <output_of_jwt_token> with the contents of the JWT token itself. Once you have successfully pulled the image, you can then tag it as needed.

Note:

For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history:

JWTs: JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access.

Shell history: Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your ~/.bash_history file. Alternatively, you can run the history -c command to erase your shell history.

Follow these practices to help ensure the security of your system and data.

Last modified October 2, 2024