Add an NGINX Ingress Controller image to your cluster
This document describes how to add an F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using a JWT token.
To follow these steps, you will need the following pre-requisite:
You can also get the NGINX Ingress Controller image using the following alternate methods:
- Download NGINX Ingress Controller from the F5 Registry
- Build NGINX Ingress Controller
- For NGINX Open Source, you can pull the nginx/nginx-ingress image from DockerHub
If you are using Helm for deployment, there are two main methods: using a chart or source.
The following command installs NGINX Ingress Controller with a Helm chart, passing required arguments using the set
parameter.
helm install my-release -n nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 2.2.1 --set controller.image.repository=private-registry.nginx.com/nginx-ic/nginx-plus-ingress --set controller.image.tag=5.1.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": [
"5.1.0-alpine",
"5.1.0-alpine-fips",
"5.1.0-ubi",
"5.1.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": [
"5.1.0-alpine-fips",
"5.1.0-ubi",
"5.1.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": [
"5.1.0-ubi",
"5.1.0"
]
}
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 totrue
. - Change the
repository
argument to the NGINX Ingress Controller image you intend to use. - Add an argument to
imagePullSecretName
orimagePullSecretsNames
to allow Docker to pull the image from the private registry.
- Change the
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: 5.1.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.
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:5.1.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.
If you need to download an image for local use (Such as to 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 thehistory -c
command to erase your shell history.Follow these practices to help ensure the security of your system and data.