diff --git a/docs/content/app-protect/installation.md b/docs/content/app-protect/installation.md index 8671d53321..fa8c17c691 100644 --- a/docs/content/app-protect/installation.md +++ b/docs/content/app-protect/installation.md @@ -12,6 +12,31 @@ 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 + +Take the steps below 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). + + For NGINX Plus Ingress Controller with App Protect, pull from `docker-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`: + ``` + $ docker pull docker-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 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 + { + "name": "nginx-ic-nap/nginx-plus-ingress", + "tags": [ + "1.12.0-ubi", + "1.12.0" + ] + } + ``` + ## Build the Docker Image Take the steps below to create the Docker image that you'll use to deploy NGINX Ingress Controller with App Protect in Kubernetes. diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index 5035a7d43e..a1939ac057 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: 1600 +weight: 2100 doctypes: [""] toc: true --- -This document explains how to build an Ingress Controller image. Note that for NGINX, we provide the image though [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). For NGINX Plus, you need to build the image. +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/). ## Prerequisites diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index e8fcfc80a4..cc10a3c3c0 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -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: - - 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). + - 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. ## Getting the Chart Sources diff --git a/docs/content/installation/installation-with-manifests.md b/docs/content/installation/installation-with-manifests.md index 545b99d5ee..121cf08b22 100644 --- a/docs/content/installation/installation-with-manifests.md +++ b/docs/content/installation/installation-with-manifests.md @@ -15,7 +15,8 @@ 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, 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). + * 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. + * 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: ``` $ git clone https://github.com/nginxinc/kubernetes-ingress/ diff --git a/docs/content/installation/installation-with-operator.md b/docs/content/installation/installation-with-operator.md index 79bd8f285b..e6f9514a7e 100644 --- a/docs/content/installation/installation-with-operator.md +++ b/docs/content/installation/installation-with-operator.md @@ -10,13 +10,12 @@ toc: true This document describes how to install the NGINX Ingress Controller in your Kubernetes cluster using the NGINX Ingress Operator. -**Note: an NGINX Ingress Operator version compatible with the 1.12 NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version.** - ## Prerequisites 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, 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). + * 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. + * 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). ## 1. Create the NginxIngressController manifest diff --git a/docs/content/installation/pulling-ingress-controller-image.md b/docs/content/installation/pulling-ingress-controller-image.md new file mode 100644 index 0000000000..dc43d0c76b --- /dev/null +++ b/docs/content/installation/pulling-ingress-controller-image.md @@ -0,0 +1,79 @@ +--- +title: Pulling the Ingress Controller Image +description: +weight: 1600 +doctypes: [""] +toc: true +--- + +This document explains how to pull an NGINX Plus Ingress Controller image from the F5 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 and your NGINX Plus license 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 + +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 Plus, you must have the NGINX Plus Ingress Controller license -- the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`). + +## 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. + + ``` + # 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 + ``` + + > **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`: + ``` + $ docker pull docker-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`: + ``` + $ docker pull docker-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.: + ``` + $ curl https://docker-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://docker-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" + ] + } + ``` + +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 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 push /nginx-ic-nap/nginx-plus-ingress:1.12.0 + ``` diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index fb01051405..7495771799 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -38,17 +38,17 @@ The supported architecture is x86-64. All images include NGINX Plus R24. The supported architecture is x86-64. -NGINX Plus images are not available through DockerHub. +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). {{% table %}} -|Name | Base image | Third-party modules | -| ---| ---| --- | -|Alpine-based image | ``alpine:3.13`` | | -|Debian-based image | ``debian:buster-slim`` | | -|Debian-based image with Opentracing | ``debian:buster-slim`` | NGINX Plus OpenTracing module, C++ OpenTracing binding for Jaeger 0.4.2 | -|Ubi-based image | ``registry.access.redhat.com/ubi8/ubi:8.3`` | | -|Debian-based image with App Protect | ``debian:buster-slim`` | NGINX Plus App Protect module | -|Ubi-based image with App Protect | ``registry.access.redhat.com/ubi7/ubi`` | NGINX Plus App Protect module | +|Name | Base image | Third-party modules | F5 Container Registry Image | +| ---| ---| --- | --- | +|Alpine-based image | ``alpine:3.13`` | | `nginx-ic/nginx-plus-ingress:1.12.0-alpine` | +|Debian-based image | ``debian:buster-slim`` | | `nginx-ic/nginx-plus-ingress:1.12.0` | +|Debian-based image with Opentracing | ``debian:buster-slim`` | NGINX Plus OpenTracing module, C++ OpenTracing binding for Jaeger 0.4.2 | `nginx-ic/nginx-plus-ingress:1.12.0-ot` | +|Ubi-based image | ``redhat/ubi8-minimal`` | | `nginx-ic/nginx-plus-ingress:1.12.0-ubi` | +|Debian-based image with App Protect | ``debian:buster-slim`` | NGINX Plus App Protect module | `nginx-ic-nap/nginx-plus-ingress:1.12.0` | +|Ubi-based image with App Protect | ``registry.access.redhat.com/ubi7/ubi`` | NGINX Plus App Protect module | `nginx-ic-nap/nginx-plus-ingress:1.12.0-ubi` | {{% /table %}} ### Custom Images