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.
ImportantNGINX 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.
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 -
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.
Important If you are using NGINX Plus and have a different Secret name than the defaultnplus-license
name, specify the Secret name by setting--set nginx.usage.secretName=<secret-name>
when runninghelm 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.
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.
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
ImportantBefore 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.
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.
- To read more on modifying data plane configuration.
- To learn more about deploying a Gateway for data plane instances.
- To add secure authentication to control plane and data planes.
- To read more about architecture changes.
- For detailed API reference.
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.
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
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:
-
Open the
values.yaml
for editing. -
Add delayed shutdown hooks:
-
In the
values.yaml
file, addlifecycle: preStop
hooks to both thenginx
andnginx-gateway
container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update thesleep
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"
-
-
Set the termination grace period:
Set
terminationGracePeriodSeconds
to a value that is equal to or greater than thesleep
duration specified in thepreStop
hook (default is30
). This setting prevents Kubernetes from terminating the pod before before thepreStop
hook has completed running.terminationGracePeriodSeconds: 50
-
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: