Upgrade NGINX Gateway Fabric

This document describes how to upgrade NGINX Gateway Fabric when a new version releases.

It covers the necessary steps for minor versions as well as major versions (such as 1.x to 2.x).

Many of the nuances in upgrade paths relate to how custom resource definitions (CRDs) are managed.

Tip: To avoid interruptions, review the Delay pod termination for zero downtime upgrades section.

Minor NGINX Gateway Fabric upgrades

Important

NGINX Plus users need a JWT secret before upgrading from version 1.4.0 to 1.5.x.

Follow the steps in Set up the JWT to create the Secret.

Upgrade Gateway resources

To upgrade your Gateway API resources, take the following steps:

  • Use Technical specifications to verify your Gateway API resources are compatible with your NGINX Gateway Fabric version.
  • Review the release notes for any important upgrade-specific information.

To upgrade the Gateway API resources, run the following command:

kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.0.0" | kubectl apply -f -

If you installed NGINX Gateway from the experimental channel, use this instead:

kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v2.0.0" | kubectl apply -f -

Upgrade NGINX Gateway Fabric CRDs

Run the following command to upgrade the CRDs:

kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.0.0/deploy/crds.yaml
Note:

Ignore the following warning, as it is expected.

Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply.

Upgrade NGINX Gateway Fabric release

Important If you are using NGINX Plus and have a different Secret name than the default nplus-license name, specify the Secret name by setting --set nginx.usage.secretName=<secret-name> when running helm upgrade.

To upgrade the release with Helm, you can use the OCI registry, or download the chart and upgrade from the source.

If needed, replace ngf with your chosen release name.

Upgrade from the OCI registry

helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric -n nginx-gateway

Upgrade from sources

helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar
cd nginx-gateway-fabric

For the latest version from the main branch, add –version 0.0.0-edge to your pull command.

To upgrade, run the following command:

helm upgrade ngf . -n nginx-gateway

Select the deployment manifest that matches your current deployment from options available in the Deploy NGINX Gateway Fabric section and apply it.

Upgrade from v1.x to v2.x

This section provides step-by-step instructions for upgrading NGINX Gateway Fabric from version 1.x to 2.x, highlighting key architectural changes, expected downtime, and important considerations for CRDs.

To upgrade NGINX Gateway Fabric from version 1.x to the new architecture in version 2.x, you must uninstall the existing NGINX Gateway Fabric CRDs and deployment, and perform a fresh installation. This will cause brief downtime during the upgrade process.

Note: You do not need to uninstall the Gateway API CRDs during the upgrade. These resources are compatible with the new NGINX Gateway Fabric version.

Uninstall NGINX Gateway Fabric v1.x

To remove the previous version 1.x of NGINX Gateway Fabric, follow these steps:

First, run the following command to uninstall NGINX Gateway Fabric from the nginx-gateway namespace, and update ngf to your release name if it is different:

helm uninstall ngf -n nginx-gateway

Afterwards, remove CRDs associated with NGINX Gateway Fabric version 1.x with the following command:

kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.2/deploy/crds.yaml

Install NGINX Gateway Fabric 2.x

Important

Before installing 2.x, we recommend following Add certificates for secure authentication.

By default, NGINX Gateway Fabric installs self-signed certificates, which may be unsuitable for a production environment.

Use the following helm install command to install the latest stable NGINX Gateway Fabric release in the nginx-gateway namespace. It will also install the CRDs required for the deployment:

helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway

For customization options during the Helm installation process, view the Install NGINX Gateway Fabric with Helm topic.

Apply the new CRDs with the following command:

kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.0.0/deploy/crds.yaml

Next, install the latest stable release of NGINX Gateway Fabric in the nginx-gateway namespace with the following command:

kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.0.0/deploy/default/deploy.yaml

For customization options during the Manifest installation process, view the Install NGINX Gateway Fabric with Manifests topic.

Architecture changes

With this release, NGINX Gateway Fabric adopts a new architecture that separates the control plane and data plane into independent deployments. This separation improves scalability, security, and operational clarity.

The control plane is a Kubernetes controller that watches Gateway API and Kubernetes resources (e.g., Services, Endpoints, Secrets) and dynamically provisions NGINX data plane deployments for each Gateway.

NGINX configurations are generated by the control plane and securely delivered to the data planes via gRPC, using the NGINX Agent. TLS is enabled by default, with optional integration with cert-manager.

Each data plane pod runs NGINX alongside the Agent, which applies config updates and handles reloads without shared volumes or signals. This design ensures dynamic, per-Gateway traffic management and operational isolation.

New fields have been added to the NginxProxy resource to configure infrastructure-related settings for data plane deployments. The NginxProxy resource is now a namespaced-scoped resource, instead of a cluster-scoped resource, and can be modified at either the Gateway or GatewayClass level. These new fields provide the flexibility to customize deployment and service configurations.

For detailed instructions on how to modify these settings, refer to the Configure infrastructure-related settings guide.

Access NGINX Gateway Fabric 1.x documentation

The documentation website is intended for the latest version of NGINX Gateway Fabric.

To review documentation prior to 2.x, check out the desired release branch (such as release-1.6):

git clone git@github.com:nginx/nginx-gateway-fabric.git
git checkout release-1.6

To review the documentation in a local webserver, run make watch in the /site folder:

cd site
make watch
Hugo is available and has a version greater than 133. Proceeding with build.
hugo --bind 0.0.0.0 -p 1313 server --disableFastRender
Watching for changes in /home/<your-user>/nginx-gateway-fabric/site/{content,layouts,static}
Watching for config changes in /home/<your-user>/nginx-gateway-fabric/site/config/_default, /home/<your-user>/nginx-gateway-fabric/site/config/development, /home/<your-user>/nginx-gateway-fabric/site/go.mod
Start building sites …
hugo v0.135.0-f30603c47f5205e30ef83c70419f57d7eb7175ab linux/amd64 BuildDate=2024-09-27T13:17:08Z VendorInfo=gohugoio


                   | EN
-------------------+------
  Pages            |  72
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 176
  Processed images |   0
  Aliases          |   9
  Cleaned          |   0

Built in 213 ms
Environment: "development"
Serving pages from disk
Web Server is available

You can then follow this localhost link for 1.x NGINX Gateway Fabric documentation.

Upgrade from NGINX Open Source to NGINX Plus

Important Ensure that you Set up the JWT before upgrading. These instructions only apply to Helm.

To upgrade from NGINX Open Source to NGINX Plus, update the Helm command to include the necessary values for Plus:

Note:

If applicable:

  • Replace the F5 Container registry private-registry.nginx.com with your internal registry for your NGINX Plus image
  • Replace nginx-plus-registry-secret with your Secret name containing the registry credentials
  • Replace ngf with your chosen release name.
helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric  --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set nginx.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway

Delay pod termination for zero downtime upgrades

To avoid client service interruptions when upgrading NGINX Gateway Fabric, you can configure PreStop hooks to delay terminating the NGINX Gateway Fabric pod, allowing the pod to complete certain actions before shutting down. This ensures a smooth upgrade without any downtime, also known as a zero downtime upgrade.

For an in-depth explanation of how Kubernetes handles pod termination, see the Termination of Pods topic on their official website.

Note: Keep in mind that NGINX won’t shut down while WebSocket or other long-lived connections are open. NGINX will only stop when these connections are closed by the client or the backend. If these connections stay open during an upgrade, Kubernetes might need to shut down NGINX forcefully. This sudden shutdown could interrupt service for clients.

Follow these steps to configure delayed pod termination:

  1. Open the values.yaml for editing.

  2. Add delayed shutdown hooks:

    • In the values.yaml file, add lifecycle: preStop hooks to both the nginx and nginx-gateway container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the sleep value to what works for your environment.

       nginxGateway:
 <...>
 lifecycle:
     preStop:
     exec:
         command:
         - /usr/bin/gateway
         - sleep
         - --duration=40s # This flag is optional, the default is 30s

 nginx:
 <...>
 lifecycle:
     preStop:
     exec:
         command:
         - /bin/sleep
         - "40"

  3. Set the termination grace period:

    • Set terminationGracePeriodSeconds to a value that is equal to or greater than the sleep duration specified in the preStop hook (default is 30). This setting prevents Kubernetes from terminating the pod before before the preStop hook has completed running.

      terminationGracePeriodSeconds: 50

  4. Save the changes.

See Also:

For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation: