From 10011bbeb5b872193cf32a3f898b2a1fcacb4e58 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Thu, 22 Jun 2023 19:39:05 -0700 Subject: [PATCH 1/3] Add FIPS to the list of images --- .../building-ingress-controller-image.md | 71 ++++++++++++------- docs/content/technical-specifications.md | 1 + 2 files changed, 45 insertions(+), 27 deletions(-) diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index 1e24b46173..53989d40ed 100644 --- a/docs/content/installation/building-ingress-controller-image.md +++ b/docs/content/installation/building-ingress-controller-image.md @@ -1,28 +1,29 @@ --- -title: Building the Ingress Controller Image -description: "This document explains how to build an Ingress Controller image using the source code." +title: Building NGINX Ingress Controller Image +description: "This document explains how to build an NGINX Ingress Controller image using the source code." weight: 2200 doctypes: [""] toc: true docs: "DOCS-601" --- -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/) and [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress). +This document explains how to build an NGINX 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/) and [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress). ## Prerequisites Before you can build the image, make sure that the following software is installed on your machine: -* [Docker](https://www.docker.com/products/docker) v18.09+ + +* [Docker](https://www.docker.com/products/docker) v19.03+ * [GNU Make](https://www.gnu.org/software/make/) * [git](https://git-scm.com/) * [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server. * For NGINX Plus, you must have the NGINX Plus license -- the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`). -Although the Ingress Controller is written in golang, golang is not required, you have the option to download the binary or to build the Ingress Controller in a Docker container. +Although the NGINX Ingress Controller is written in golang, golang is not required, you have the option to download the binary or to build the NGINX Ingress Controller in a Docker container. ## Building the Image and Pushing It to the Private Registry -We build the image using the make utility and the provided `Makefile`. Let’s create the Ingress Controller binary, build an image and push the image to the private registry. +We build the image using the make utility and the provided `Makefile`. Let’s create the NGINX Ingress Controller binary, build an image and push the image to the private registry. **Note**: If you have a local golang environment and you want to build the binary, you can remove `TARGET=download` from the `make` commands. If you want to build the binary, but you don't have a local golang environment you can use `TARGET=container`. @@ -30,34 +31,43 @@ We build the image using the make utility and the provided `Makefile`. Let’s c If you’re using Google Container Registry, make sure you’re logged into the gcloud tool by running the `gcloud auth login` and `gcloud auth configure-docker` commands. -1. Clone the Ingress Controller repo: - ``` - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v3.1.1 - $ cd kubernetes-ingress +1. Clone the NGINX Ingress Controller repo: + + ```console + git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v3.1.1 + cd kubernetes-ingress ``` 1. Build the image: * For **NGINX**: + + ```console + make debian-image PREFIX=myregistry.example.com/nginx-ingress TARGET=download ``` - $ make debian-image PREFIX=myregistry.example.com/nginx-ingress TARGET=download - ``` + or if you wish to use alpine + + ```console + make alpine-image PREFIX=myregistry.example.com/nginx-ingress TARGET=download ``` - $ make alpine-image PREFIX=myregistry.example.com/nginx-ingress TARGET=download - ``` + `myregistry.example.com/nginx-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry. As a result, the image **myregistry.example.com/nginx-ingress:3.1.1** is built. Note that the tag `3.1.1` comes from the `VERSION` variable, defined in the Makefile. * For **NGINX Plus**, first, make sure that the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) of your license are located in the root of the project: - ``` + + ```console $ ls nginx-repo.* nginx-repo.crt nginx-repo.key ``` + Then run: + + ```console + make debian-image-plus PREFIX=myregistry.example.com/nginx-plus-ingress TARGET=download ``` - $ make debian-image-plus PREFIX=myregistry.example.com/nginx-plus-ingress TARGET=download - ``` + `myregistry.example.com/nginx-plus-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry. As a result, the image **myregistry.example.com/nginx-plus-ingress:3.1.1** is built. Note that the tag `3.1.1` comes from the `VERSION` variable, defined in the Makefile. @@ -65,10 +75,12 @@ We build the image using the make utility and the provided `Makefile`. Let’s c **Note**: In the event of a patch version of [NGINX Plus being released](/nginx/releases/), make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the `make` command. 1. Push the image: + + ```console + make push PREFIX=myregistry.example.com/nginx-ingress ``` - $ make push PREFIX=myregistry.example.com/nginx-ingress - ``` - Note: If you're using a different tag, append `TAG=your-tag` to the command above. + + **Note**: If you're using a different tag, append `TAG=your-tag` to the command above. Next you will find the details about available Makefile targets and variables. @@ -77,26 +89,30 @@ Next you will find the details about available Makefile targets and variables. You can see a list of all the targets by running `make` without any target or `make help` Below you can find some of the most useful targets in the **Makefile**: -* **build**: creates the Ingress Controller binary using the local golang environment (ignored when `TARGET` is `container`). + +* **build**: creates the NGINX Ingress Controller binary using the local golang environment (ignored when `TARGET` is `container`). * **alpine-image**: for building an alpine-based image with NGINX. * **alpine-image-plus**: for building an alpine-based image with NGINX Plus. +* **alpine-image-plus-fips**: for building an alpine-based image with NGINX Plus and FIPS inside. * **debian-image**: for building a debian-based image with NGINX. * **debian-image-plus**: for building a debian-based image with NGINX Plus. -* **debian-image-nap-plus**: for building a debian-based image with NGINX Plus and the [app-protect-waf](/nginx-app-protect/) module. -* **debian-image-dos-plus**: for building a debian-based image with NGINX Plus and the [app-protect-dos](/nginx-app-protect-dos/) module. -* **debian-image-nap-dos-plus**: for building a debian-based image with NGINX Plus app-protect-waf and app-protect-dos modules. +* **debian-image-nap-plus**: for building a debian-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect/) module. +* **debian-image-dos-plus**: for building a debian-based image with NGINX Plus and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module. +* **debian-image-nap-dos-plus**: for building a debian-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect/) and [NGINX App Protect DoS](/nginx-app-protect-dos/) modules. * **ubi-image**: for building an ubi-based image with NGINX for [Openshift](https://www.openshift.com/) clusters. * **ubi-image-plus**: for building an ubi-based image with NGINX Plus for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-nap-plus**: for building an ubi-based image with NGINX Plus and the [app-protect-waf](/nginx-app-protect/) module for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-dos-plus**: for building an ubi-based image with NGINX Plus and the [app-protect-dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-nap-dos-plus**: for building an ubi-based image with NGINX Plus, [app-protect-waf](/nginx-app-protect/) and the [app-protect-dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-nap-plus**: for building an ubi-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-dos-plus**: for building an ubi-based image with NGINX Plus and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-nap-dos-plus**: for building an ubi-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect/) and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. Note: You need to store your RHEL organization and activation keys in a file named `rhel_license` in the project root. Example: + ```bash RHEL_ORGANIZATION=1111111 RHEL_ACTIVATION_KEY=your-key ``` A few other useful targets: + * **push**: pushes the image to the Docker registry specified in `PREFIX` and `TAG` variables. * **all**: executes test `test`, `lint`, `verify-codegen`, `update-crds` and `debian-image`. If one of the targets fails, the execution process stops, reporting an error. * **test**: runs unit tests. @@ -105,6 +121,7 @@ A few other useful targets: ### Makefile Variables The **Makefile** contains the following main variables for you to customize (either by changing the Makefile or by overriding the variables in the make command): + * **ARCH** -- the architecture of the image (and the binary). The default value is `amd64`. The most common architectures are `amd64` and `arm64`. Some other popular options are `arm`, `ppc64le` and `s390x`. * **PREFIX** -- the name of the image. The default is `nginx/nginx-ingress`. * **TAG** -- the tag added to the image. It's set to the version of the Ingress Controller by default. diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 186aaa8722..73d9c1a4c7 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -64,6 +64,7 @@ NGINX Plus images are available through the F5 Container registry `private-regis |Name | Base image | Third-party modules | F5 Container Registry Image | Architectures | | ---| ---| --- | --- | --- | |Alpine-based image | ``alpine:3.17`` | NGINX Plus JavaScript and OpenTracing modules, OpenTracing tracers for Jaeger, Zipkin and Datadog | `nginx-ic/nginx-plus-ingress:3.1.1-alpine` | arm64, amd64 | +|Alpine-based image with FIPS inside | ``alpine:3.17`` | NGINX Plus JavaScript and OpenTracing modules, OpenTracing tracers for Jaeger, Zipkin and Datadog, FIPS module and OpenSSL configuration | `nginx-ic/nginx-plus-ingress:3.1.1-alpine-fips` | arm64, amd64 | |Debian-based image | ``debian:11-slim`` | NGINX Plus JavaScript and OpenTracing modules, OpenTracing tracers for Jaeger, Zipkin and Datadog | `nginx-ic/nginx-plus-ingress:3.1.1` | arm64, amd64 | |Debian-based image with NGINX App Protect WAF | ``debian:11-slim`` | NGINX App Protect WAF, NGINX Plus JavaScript and OpenTracing modules, OpenTracing tracers for Jaeger, Zipkin and Datadog | `nginx-ic-nap/nginx-plus-ingress:3.1.1` | amd64 | |Debian-based image with NGINX App Protect DoS | ``debian:11-slim`` | NGINX App Protect DoS, NGINX Plus JavaScript and OpenTracing modules, OpenTracing tracers for Jaeger, Zipkin and Datadog | `nginx-ic-dos/nginx-plus-ingress:3.1.1` | amd64 | From b3a2f82e5a1428b460e44f074f4d13538378a316 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Fri, 23 Jun 2023 08:59:21 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Alan Dooley Signed-off-by: Luca Comellini --- docs/content/installation/building-ingress-controller-image.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index 53989d40ed..127968d1b2 100644 --- a/docs/content/installation/building-ingress-controller-image.md +++ b/docs/content/installation/building-ingress-controller-image.md @@ -4,7 +4,6 @@ description: "This document explains how to build an NGINX Ingress Controller im weight: 2200 doctypes: [""] toc: true -docs: "DOCS-601" --- This document explains how to build an NGINX 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/) and [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress). @@ -19,7 +18,7 @@ Before you can build the image, make sure that the following software is install * [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server. * For NGINX Plus, you must have the NGINX Plus license -- the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`). -Although the NGINX Ingress Controller is written in golang, golang is not required, you have the option to download the binary or to build the NGINX Ingress Controller in a Docker container. +Although the NGINX Ingress Controller is written in golang, golang is not required: you can download the binary file or build the NGINX Ingress Controller in a Docker container. ## Building the Image and Pushing It to the Private Registry From 3c83791a905e3728c5a03d0fbfe2dd14c01d3bc4 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Fri, 23 Jun 2023 09:51:31 -0700 Subject: [PATCH 3/3] fix operator version --- docs/content/technical-specifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 73d9c1a4c7..ff727f2b9b 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -23,7 +23,7 @@ We explicitly test the NGINX Ingress Controller (NIC) on a range of Kubernetes p {{% table %}} | NIC Version | Supported Kubernetes Version | NIC Helm Chart Version | NIC Operator Version | NGINX / NGINX Plus version | | --- | --- | --- | --- | --- | -| 3.1.1 | 1.26 - 1.22 | 0.17.1 | 1.4.1 | 1.23.4 / R29 | +| 3.1.1 | 1.26 - 1.22 | 0.17.1 | 1.4.2 | 1.23.4 / R29 | | 3.0.2 | 1.26 - 1.21 | 0.16.2 | 1.3.1 | 1.23.3 / R28 | | 2.4.2 | 1.25 - 1.19 | 0.15.2 | 1.2.1 | 1.23.2 / R28 | | 2.3.1 | 1.24 - 1.19 | 0.14.1 | 1.1.0 | 1.23.1 / R27 |