Build NGINX Ingress Controller LTS

This document describes how to build an F5 NGINX Ingress Controller LTS image from source code and upload it to a private Docker registry.

It also includes information on the Makefile targets and variables.

If you do not need to build a custom image, see the pre-built image options at the end of this guide.

Before you begin

To get started, you need the following software installed on your machine:

Docker v19.03 or higher
GNU Make
git
OpenSSL, optionally, if you would like to generate a self-signed certificate and a key for the default server.
For NGINX Plus users, download the certificate (nginx-repo.crt) and key (nginx-repo.key) from MyF5.

Although NGINX Ingress Controller LTS is written in Golang, you don’t need to have Golang installed.

You can download the precompiled binary file or build NGINX Ingress Controller LTS in a Docker container.

Prepare the environment

Get your system ready for building and pushing the NGINX Ingress Controller LTS image.

Sign in to your private registry. Replace <my-docker-registry> with the path to your own private registry.
docker login <my-docker-registry>
Clone the NGINX Ingress Controller LTS GitHub repository. Replace <version_number> with the version of NGINX Ingress Controller LTS you want.
shell
git clone https://github.com/nginx/kubernetes-ingress.git --branch <version_number> cd kubernetes-ingress
For instance if you want to clone version 2026-lts-r1, the commands to run would be:
shell
git clone https://github.com/nginx/kubernetes-ingress.git --branch 2026-lts-r1 cd kubernetes-ingress

Build the NGINX Ingress Controller LTS image

After setting up your environment, follow these steps to build the NGINX Ingress Controller LTS image.

If you have a local Golang environment and want to build the binary yourself, remove TARGET=download from the make commands. If you don’t have Golang but still want to build the binary, use TARGET=container.

For NGINX Plus

Place your NGINX Plus license files (nginx-repo.crt and nginx-repo.key) in the project’s root folder. To verify they’re in place, run:

ls nginx-repo.*

You should see:

nginx-repo.crt  nginx-repo.key

Build the image. Replace <my-docker-registry> with your private registry’s path.

make debian-image-plus PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download

What to expect: The image is built and tagged with a version number, which is derived from the VERSION variable in the Makefile. This version number is used for tracking and deployment purposes.

If a patch for NGINX Plus is released, 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.

Push the image to your private registry

Once you’ve successfully built the NGINX Plus Ingress Controller image, the next step is to upload it to your private Docker registry. This makes the image available for deployment to your Kubernetes cluster.

For NGINX Plus

Upload the NGINX Plus image. If you’re using a custom tag, add TAG=your-tag to the end of the command. Replace <my-docker-registry> with your private registry’s path.

make push PREFIX=<my-docker-registry>/nginx-plus-ingress

Makefile details

This section provides comprehensive information on the targets and variables available in the Makefile. These targets and variables allow you to customize how you build, tag, and push your NGINX Plus images.

Key Makefile targets

To view available Makefile targets, run make with no target or type make help.

Key targets include:

Target	Description
build	Creates the NGINX Ingress Controller LTS binary with your local Go environment.
debian-image-plus	Builds a Debian-based image with NGINX Plus.

Additional useful targets

A few other useful targets:

Target	Description
push	Pushes the built image to the Docker registry. Configures with `PREFIX` and `TAG`.
all	Runs `test`, `lint`, `verify-codegen`, `update-crds`, and `debian-image`. Stops and reports an error if any of these targets fail.
test	Runs unit tests.

Makefile variables you can customize

The Makefile includes several key variables. You have the option to either modify these variables directly in the Makefile or override them when you run the make command.

Variable	Description
ARCH	Defines the architecture for the image and binary. The default is `amd64`, but you can also use `arm64`.
PREFIX	Gives the image its name. The default is `nginx-plus-ingress`.
TAG	Adds a tag to the image. This is often the version of NGINX Ingress Controller LTS.
DOCKER_BUILD_OPTIONS	Allows for additional options during the `docker build` process, like `--pull`.
TARGET	Determines the build environment. NGINX Ingress Controller LTS compiles locally in a Golang environment by default. Ensure the NGINX Ingress Controller LTS repo resides in your `$GOPATH` if you select this option. Alternatively, you can set `TARGET=container` to build using a Docker Golang container. To skip compiling the binary if you’re on a specific tag or the latest `main` branch commit, set `TARGET=download`.

Alternatives to building your own image

If you prefer not to build your own NGINX Ingress Controller LTS image, you can use pre-built images. Here are your options:

NGINX Plus Ingress Controller LTS: You have two options for this:

Download the image using your NGINX Ingress Controller LTS subscription certificate and key. View the Download NGINX Ingress Controller LTS from the F5 Registry topic.
Use your NGINX Ingress Controller LTS subscription JWT token to get the image. View the Add an NGINX Ingress Controller LTS image to your cluster topic.

View source

Edit this page

Create a new issue