Upgrade NGINX Gateway Fabric to version 2.x

This guide 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 custom resource definitions (CRDs).

Upgrade from v1.x to v2.x

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

Follow these steps to install NGINX Gateway Fabric v2.x using Helm:

Next, install the latest stable release of NGINX Gateway Fabric in the nginx-gateway namespace. The following helm install command will install the NGINX Gateway Fabric release along with the necessary CRDs required for the deployment:

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

For additional customization options during the helm installation process, take a look at Installation with Helm.

Follow these steps to install NGINX Gateway Fabric v2.x using Manifests:

Apply the new CRDs with the following command:

kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.2/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/v1.6.2/deploy/default/deploy.yaml

For additional customization options during the installation process using manifests, take a look at Installation with Manifests.

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.