diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index c416c6ac1c..06f9576119 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -10,7 +10,9 @@ This chart deploys the NGINX Ingress controller in your Kubernetes cluster. - Helm 3.0+. - Git. - If you’d like to use NGINX Plus: - - Build an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](../../build/README.md). + - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` parameter. + - Alternatively, pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image). + - Alternatively, you can build an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image). - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. ## Getting the Chart Sources @@ -36,15 +38,13 @@ $ helm repo add nginx-stable https://helm.nginx.com/stable $ helm repo update ``` -**Note**: If you wish to use the experimental repository, replace `stable` with `edge`. - ## Installing the Chart ### Installing the CRDs -By default, the Ingress Controller requires a number of custom resource definitions (CRDs) installed in the cluster. The Helm client will install those CRDs. +By default, the Ingress Controller requires a number of custom resource definitions (CRDs) installed in the cluster. The Helm client will install those CRDs. If the CRDs are not installed, the Ingress Controller pods will not become `Ready`. -If you do not use the custom resources that require those CRDs (which corresponds to `controller.enableCustomResources` set to `false` and `controller.appprotect.enable` set to `false`). The installation of the CRDs can be skipped by specifying `--skip-crds` for the helm install command. +If you do not use the custom resources that require those CRDs (which corresponds to `controller.enableCustomResources` set to `false` and `controller.appprotect.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` for the helm install command. ### Installing via Helm Repository diff --git a/docs/content/app-protect/installation.md b/docs/content/app-protect/installation.md index fa8c17c691..c0569ee9bd 100644 --- a/docs/content/app-protect/installation.md +++ b/docs/content/app-protect/installation.md @@ -12,22 +12,25 @@ This document provides an overview of the steps required to use NGINX App Protec You can also [install the Ingress Controller with App Protect by using Helm](/nginx-ingress-controller/installation/installation-with-helm/). Use the `controller.appprotect.*` parameters of the chart. -## Pull the Docker Image +## Using the Docker Images from the F5 Container registry -Take the steps below to pull the Docker image that you'll use to deploy NGINX Ingress Controller with App Protect in Kubernetes. +Take the steps below to either configure a Docker Registry secret in your Kubernetes cluster, or to pull the Docker image that you'll use to deploy NGINX Ingress Controller with App Protect in Kubernetes. -- Follow the steps to [Pull the NGINX Ingress Controller image](/nginx-ingress-controller/installation/pulling-ingress-controller-image). +- Follow the steps to [use the JWT token to create a docker registry secret](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). - For NGINX Plus Ingress Controller with App Protect, pull from `docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`: +- Alternatively, follow the steps to [Pull the NGINX Ingress Controller image](/nginx-ingress-controller/installation/pulling-ingress-controller-image). + + For NGINX Plus Ingress Controller with App Protect, pull from `private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`: ``` - $ docker pull docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 + $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 ``` - - `1.12.0` will pull down the Debian based image. The other available image tag is `1.12.0-ubi` for the UBI based image. + `1.12.0` will pull down the Debian based image. The other available image tag is `1.12.0-ubi` for the UBI based image. + +- Use the docker registry API to list the available image tags for the repository. To list the available image tags for the repository, you can use the Docker registry API, e.g.: ``` - $ curl https://docker-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq + $ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index a1939ac057..f4d545c704 100644 --- a/docs/content/installation/building-ingress-controller-image.md +++ b/docs/content/installation/building-ingress-controller-image.md @@ -1,12 +1,12 @@ --- title: Building the Ingress Controller Image description: -weight: 2100 +weight: 2200 doctypes: [""] toc: true --- -This document explains how to build an Ingress Controller image using the source code. You can also use pre-built images: please see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the NGINX Ingress Controller based on NGINX Plus from the F5 Docker registry; for NGINX Ingress Controller based on NGINX OSS, we provide the images through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). +This document explains how to build an Ingress Controller image using the source code. You can also use pre-built images: please see [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret) and [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the NGINX Ingress Controller based on NGINX Plus from the F5 Docker registry; for NGINX Ingress Controller based on NGINX OSS, we provide the images through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). ## Prerequisites diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index a4e1e71f8e..25e976d7e5 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -1,7 +1,7 @@ --- title: Installation with Helm description: -weight: 1800 +weight: 1900 doctypes: [""] toc: true --- @@ -15,7 +15,8 @@ This document describes how to install the NGINX Ingress Controller in your Kube - Helm 3.0+. - Git. - If you’d like to use NGINX Plus: - - Pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). + - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` parameter. + - Alternatively, pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). - Alternatively, you can build an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. diff --git a/docs/content/installation/installation-with-manifests.md b/docs/content/installation/installation-with-manifests.md index d54fc59379..c72864389a 100644 --- a/docs/content/installation/installation-with-manifests.md +++ b/docs/content/installation/installation-with-manifests.md @@ -1,7 +1,7 @@ --- title: Installation with Manifests description: -weight: 1700 +weight: 1800 doctypes: [""] aliases: - /installation/ @@ -16,8 +16,9 @@ This document describes how to install the NGINX Ingress Controller in your Kube 1. Make sure you have access to the Ingress controller image: * For NGINX Ingress controller, use the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). * For NGINX Plus Ingress controller, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. + * To pull from the F5 Container registry in your Kubernetes cluster, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). -1. Clone the Ingress controller repo and change into the deployments folder: +2. Clone the Ingress controller repo and change into the deployments folder: ``` $ git clone https://github.com/nginxinc/kubernetes-ingress/ $ cd kubernetes-ingress/deployments @@ -120,7 +121,7 @@ We include two options for deploying the Ingress controller: $ kubectl apply -f deployment/nginx-plus-ingress.yaml ``` - **Note**: Update the `nginx-plus-ingress.yaml` with the container image that you have built. + **Note**: Update the `nginx-plus-ingress.yaml` with the chosen image from the F5 Container registry; or the container image that you have built. * *Use a DaemonSet*: When you run the Ingress Controller by using a DaemonSet, Kubernetes will create an Ingress controller pod on every node of the cluster. @@ -137,7 +138,7 @@ We include two options for deploying the Ingress controller: $ kubectl apply -f daemon-set/nginx-plus-ingress.yaml ``` - **Note**: Update the `nginx-plus-ingress.yaml` with the container image that you have built. + **Note**: Update the `nginx-plus-ingress.yaml` with the chosen image from the F5 Container registry; or the container image that you have built. ### 3.2 Check that the Ingress Controller is Running diff --git a/docs/content/installation/installation-with-operator.md b/docs/content/installation/installation-with-operator.md index e6f9514a7e..fb924f7aa8 100644 --- a/docs/content/installation/installation-with-operator.md +++ b/docs/content/installation/installation-with-operator.md @@ -2,7 +2,7 @@ title: Installation with the NGINX Ingress Operator description: -weight: 1900 +weight: 2000 doctypes: [""] toc: true --- @@ -15,6 +15,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube 1. Make sure you have access to the Ingress Controller image: * For NGINX Ingress Controller, use the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). * For NGINX Plus Ingress controller, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. + * To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). 1. Install the NGINX Ingress Operator following the [instructions](https://github.com/nginxinc/nginx-ingress-operator/blob/master/docs/installation.md). diff --git a/docs/content/installation/pulling-ingress-controller-image.md b/docs/content/installation/pulling-ingress-controller-image.md index 7c837b0639..c7a2928265 100644 --- a/docs/content/installation/pulling-ingress-controller-image.md +++ b/docs/content/installation/pulling-ingress-controller-image.md @@ -1,52 +1,50 @@ --- title: Pulling the Ingress Controller Image description: -weight: 1600 +weight: 1700 doctypes: [""] toc: true --- -This document explains how to pull an NGINX Plus Ingress Controller image from the F5 Docker registry using your NGINX Ingress Controller subscription certificate and key. Note that an NGINX Plus subscription certificate and key will not work with the Docker registry. -Please see [here](/nginx-ingress-controller/installation/building-ingress-controller-image) for information on how to build an Ingress Controller image using the source code from this repository and your NGINX Plus subscription certificate and key. -Note that for NGINX Ingress Controller based on NGINX OSS, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). +This document explains how to pull an NGINX Plus Ingress Controller image from the F5 Docker registry using your NGINX Ingress Controller subscription certificate and key. **Please note that an NGINX Plus subscription certificate and key will not work with the F5 Docker registry.** You can also get the image using alternative methods: + +* Please see [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret) for details on how to use the JWT token to use the image directly in your Kubernetes cluster. +* Please see [here](/nginx-ingress-controller/installation/building-ingress-controller-image) for information on how to build an Ingress Controller image using the source code from this repository and your NGINX Plus subscription certificate and key. +* For NGINX Ingress Controller based on NGINX OSS, we provide the image through DockerHub. ## Prerequisites Before you can pull the image, make sure that the following software is installed on your machine: * [Docker](https://www.docker.com/products/docker) v18.09+ -* For NGINX Ingress Controller, you must have the NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5] (https://myf5.com). +* For NGINX Ingress Controller, you must have the NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5](https://myf5.com). ## Pulling the Image using Docker and Pushing It to the Private Registry -1. First, configure the Docker environment to use certificate-based client-server authentication with the F5 Container registry - `docker-registry.nginx.com`. - To do so in a Linux based environment, create a `docker-registry.nginx.com` directory under `/etc/docker/certs.d` and create a certificate `client.cert` (using `nginx-repo.crt` - please note that the certificate MUST have the `.cert` suffix, not `.crt`) and a key `client.key` (using `nginx-repo.key`). See [this document](https://docs.docker.com/engine/security/certificates/) for more details. +1. First, configure the Docker environment to use certificate-based client-server authentication with the F5 Container registry - `private-registry.nginx.com`. + To do so in a Linux based environment, create a `private-registry.nginx.com` directory under `/etc/docker/certs.d` and create a certificate `client.cert` (using `nginx-repo.crt` - please note that the certificate MUST have the `.cert` suffix, not `.crt`) and a key `client.key` (using `nginx-repo.key`). See [this document](https://docs.docker.com/engine/security/certificates/) for more details. ``` - # mkdir /etc/docker/certs.d/docker-registry.nginx.com - # cp nginx-repo.crt /etc/docker/certs.d/docker-registry.nginx.com/client.cert - # cp nginx-repo.key /etc/docker/certs.d/docker-registry.nginx.com/client.key + # mkdir /etc/docker/certs.d/private-registry.nginx.com + # cp nginx-repo.crt /etc/docker/certs.d/private-registry.nginx.com/client.cert + # cp nginx-repo.key /etc/docker/certs.d/private-registry.nginx.com/client.key ``` > **Note**: The preceding example is operating-system specific and is for illustrative purposes only. You should consult your operating system documentation for creating an os-provided bundled certificate chain. For example, to configure this for Docker Desktop for Mac or Docker Desktop for Windows, see [this document](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [this document](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) for more details. -2. Use docker to pull the required image from `docker-registry.nginx.com`. - For NGINX Plus Ingress Controller, pull from `docker-registry.nginx.com/nginx-ic/nginx-plus-ingress`: +2. Use docker to pull the required image from `private-registry.nginx.com`. Choose the image from the available images listed [here](nginx-ingress-controller/technical-specifications/#images-with-nginx-plus). + For NGINX Plus Ingress Controller, pull from `private-registry.nginx.com/nginx-ic/nginx-plus-ingress`, e.g.: ``` - $ docker pull docker-registry.nginx.com/nginx-ic/nginx-plus-ingress:1.12.0 + $ docker pull private-registry.nginx.com/nginx-ic/nginx-plus-ingress:1.12.0 ``` - `1.12.0` will pull down the Debian based image. Other available image tags are `1.12.0-alpine` for the Alpine based image, `1.12.0-ot` for the Debian based image with OpenTracing, and `1.12.0-ubi` for the UBI based image. - - For NGINX Plus Ingress Controller with App Protect, pull from `docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`: + For NGINX Plus Ingress Controller with App Protect, pull from `private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`, e.g.: ``` - $ docker pull docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 + $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 ``` - `1.12.0` will pull down the Debian based image. The other available image tag is `1.12.0-ubi` for the UBI based image. - - To list the available image tags for the repositories, you can use the Docker registry API, e.g.: + To list the available image tags for the repositories, you can also use the Docker registry API, e.g.: ``` - $ curl https://docker-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq + $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq { "name": "nginx-ic/nginx-plus-ingress", "tags": [ @@ -57,7 +55,7 @@ Before you can pull the image, make sure that the following software is installe ] } - $ curl https://docker-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq + $ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ @@ -70,12 +68,12 @@ Before you can pull the image, make sure that the following software is installe 3. Tag and push the image to your private registry. Make sure to run the `docker login` command first to log in to the registry. ``` - $ docker tag docker-registry.nginx.com/nginx-ic/nginx-plus-ingress:1.12.0 /nginx-ic/nginx-plus-ingress:1.12.0 + $ docker tag private-registry.nginx.com/nginx-ic/nginx-plus-ingress:1.12.0 /nginx-ic/nginx-plus-ingress:1.12.0 $ docker push /nginx-ic/nginx-plus-ingress:1.12.0 ``` or for NGINX App Protect enabled image ``` - $ docker tag docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 /nginx-ic-nap/nginx-plus-ingress:1.12.0 + $ docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:1.12.0 /nginx-ic-nap/nginx-plus-ingress:1.12.0 $ docker push /nginx-ic-nap/nginx-plus-ingress:1.12.0 ``` diff --git a/docs/content/installation/running-multiple-ingress-controllers.md b/docs/content/installation/running-multiple-ingress-controllers.md index b4afa2fa8f..a2d11d5156 100644 --- a/docs/content/installation/running-multiple-ingress-controllers.md +++ b/docs/content/installation/running-multiple-ingress-controllers.md @@ -2,7 +2,7 @@ title: Running Multiple Ingress Controllers description: -weight: 2000 +weight: 2100 doctypes: [""] aliases: - /multiple-ingress-controllers/ diff --git a/docs/content/installation/using-the-jwt-token-docker-secret.md b/docs/content/installation/using-the-jwt-token-docker-secret.md new file mode 100644 index 0000000000..eb77036697 --- /dev/null +++ b/docs/content/installation/using-the-jwt-token-docker-secret.md @@ -0,0 +1,59 @@ +--- +title: Using the NGINX IC Plus JWT token in a Docker Config Secret +description: +weight: 1600 +doctypes: [""] +toc: true +--- + +This document explains how to use the NGINX Plus Ingress Controller image from the F5 Docker registry in your Kubernetes cluster by using your NGINX Ingress Controller subscription JWT token. **Please note that an NGINX Plus subscription certificate and key will not work with the F5 Docker registry.** You can also get the image using alternative methods: + +* You can use Docker to pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). +* Please see [here](/nginx-ingress-controller/installation/building-ingress-controller-image) for information on how to build an Ingress Controller image using the source code from this repository and your NGINX Plus subscription certificate and key. +* Note that for NGINX Ingress Controller based on NGINX OSS, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). + +## Prerequisites + +* For NGINX Ingress Controller, you must have the NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) JWT access token from [MyF5](https://myf5.com). +* 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](https://myf5.com). + +## Using the JWT token in a Docker Config Secret + +1. Create a `docker-registry` secret on the cluster using the JWT token as the username, and `none` for password (password is unused). The name of the docker server is `private-registry.nginx.com`. Optionally namespace the secret. + + ``` + kubectl create secret docker-registry regcred --docker-server=private-registry.nginx.com --docker-username= --docker-password=none [-n nginx-ingress] + ``` + +2. Confirm the details of the created secret by running: + + ``` + kubectl get secret regcred --output=yaml + ``` + +3. This secret can now be added to a deployment spec, or to a service account to apply to all deployments for a given SA spec. See the official documentation [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) and [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account) for more details. + +4. Update the deployment spec with the chosen image path. Choose the image from the available images listed [here](nginx-ingress-controller/technical-specifications/#images-with-nginx-plus). + +5. You can use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, e.g.: + ``` + $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq + { + "name": "nginx-ic/nginx-plus-ingress", + "tags": [ + "1.12.0-alpine", + "1.12.0-ot", + "1.12.0-ubi", + "1.12.0" + ] + } + + $ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq + { + "name": "nginx-ic-nap/nginx-plus-ingress", + "tags": [ + "1.12.0-ubi", + "1.12.0" + ] + } + ``` diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index ecf8e56e08..e8a690caa1 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -38,7 +38,7 @@ The supported architecture is x86-64. All images include NGINX Plus R24. The supported architecture is x86-64. -NGINX Plus images are available through the F5 Container registry `docker-registry.nginx.com` - see [Pulling the NGINX Ingress Controller image](/nginx-ingress-controller/installation/pulling-ingress-controller-image). +NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com` - see [Using the NGINX IC Plus JWT token in a Docker Config Secret](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret) and [Pulling the NGINX Ingress Controller image](/nginx-ingress-controller/installation/pulling-ingress-controller-image). {{% table %}} |Name | Base image | Third-party modules | F5 Container Registry Image |