Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add FIPS to the list of images #4048

Merged
merged 4 commits into from
Jun 23, 2023
Merged

Add FIPS to the list of images #4048

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
10011bb
Add FIPS to the list of images
lucacome Jun 23, 2023
b3a2f82
Apply suggestions from code review
lucacome Jun 23, 2023
dc8f401
Merge branch 'main' into docs/fips
lucacome Jun 23, 2023
3c83791
fix operator version
lucacome Jun 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 44 additions & 27 deletions docs/content/installation/building-ingress-controller-image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,74 +1,86 @@
---
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"
lucacome marked this conversation as resolved.
Show resolved Hide resolved
---

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.
lucacome marked this conversation as resolved.
Show resolved Hide resolved

## 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`.

1. Make sure to run the `docker login` command first to log in to the registry.

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.

**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.

Expand All @@ -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.
Expand All @@ -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.
Expand Down
1 change: 1 addition & 0 deletions docs/content/technical-specifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down