Build NGINX Gateway Fabric

Overview

While most users will install NGINX Gateway Fabric with Helm or Kubernetes manifests, manually building the NGINX Gateway Fabric and NGINX images can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images.

Before you begin

Before you can build the NGINX Gateway Fabric and NGINX images, make sure you have the following software installed on your machine:

• git
• GNU Make
• Docker v18.09+
• Go v1.20

If building the NGINX Plus image, you will also need a valid NGINX Plus license certificate (nginx-repo.crt) and key (nginx-repo.key) in the root of the repo.

Steps

1. Clone the repo and change into the nginx-gateway-fabric directory:

   Copy

   git clone https://github.com/nginx/nginx-gateway-fabric.git --branch v2.6.0
   cd nginx-gateway-fabric

2. Build the images:

   • To build both the NGINX Gateway Fabric and NGINX images:

     Copy

     make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images
     

   • To build both the NGINX Gateway Fabric and NGINX Plus images:

     Copy

     make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images-with-plus
     

   • To build just the NGINX Gateway Fabric image:

     Copy

     make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-ngf-image
     

   • To build just the NGINX image:

     Copy

     make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-nginx-image
     

   • To build just the NGINX Plus image:

     Copy

     make PREFIX=myregistry.example.com/nginx-gateway-fabric/nginx-plus build-prod-nginx-plus-image
     

   Set the PREFIX variable to the name of the registry you’d like to push the image to. By default, the images will be named nginx-gateway-fabric:2.6.0 and nginx-gateway-fabric/nginx:2.6.0 or nginx-gateway-fabric/nginx-plus:2.6.0.

3. Push the images to your container registry:

   Copy

   docker push myregistry.example.com/nginx-gateway-fabric:2.6.0
   docker push myregistry.example.com/nginx-gateway-fabric/nginx:2.6.0

   or

   Copy

   docker push myregistry.example.com/nginx-gateway-fabric:2.6.0
   docker push myregistry.example.com/nginx-gateway-fabric/nginx-plus:2.6.0

   Make sure to substitute myregistry.example.com/nginx-gateway-fabric with your registry.

Build a WAF-enabled NGINX Plus image

To use F5 WAF for NGINX with NGINX Gateway Fabric, you need an NGINX Plus image that includes the F5 WAF module. This image is built from the same Dockerfile as the standard NGINX Plus image, with a build argument that includes the app-protect-module-plus package.

Important

The WAF-enabled image can only be built for amd64 architecture. ARM64 is not supported.

Additional prerequisites

In addition to the prerequisites listed above, you need:

• A valid NGINX Plus license certificate (nginx-repo.crt) and key (nginx-repo.key) in the root of the repo.
• Access to the NGINX Plus and F5 WAF for NGINX package repositories.

Build the images

1. Build both the NGINX Gateway Fabric and NGINX Plus WAF images:

   Copy

   make PREFIX=myregistry.example.com/nginx-gateway-fabric build-images-with-nap-waf
   

   The previous make command builds:

   • The NGINX Gateway Fabric control plane image: myregistry.example.com/nginx-gateway-fabric:2.6.0
   • The NGINX Plus WAF data plane image: myregistry.example.com/nginx-gateway-fabric/nginx-plus:2.6.0

   To build only the NGINX Plus WAF image (without the control plane image) use the following command:

   Copy

   make PREFIX=myregistry.example.com/nginx-gateway-fabric build-nginx-plus-image-with-nap-waf
   

2. Push the images to your container registry:

   Copy

   docker push myregistry.example.com/nginx-gateway-fabric:2.6.0
   docker push myregistry.example.com/nginx-gateway-fabric/nginx-plus:2.6.0

Install with the custom WAF image

When installing with Helm, point the NGINX image to your WAF-enabled image and enable NGINX Plus:

helm install nginx-gateway oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --set nginx.plus=true \
  --set nginx.image.repository=myregistry.example.com/nginx-gateway-fabric/nginx-plus \
  --set nginx.image.tag=2.6.0

The WAF sidecar containers (waf-enforcer and waf-config-mgr) are pulled from the NGINX private container registry by default. To use custom images for the sidecars, configure them in the NginxProxy resource. See F5 WAF for NGINX overview for details on enabling WAF on a Gateway.