Installation with Helm
Overview
Learn how to install, upgrade, and uninstall NGINX Gateway Fabric in a Kubernetes cluster using Helm.
Before you begin
To complete this guide, you’ll need to install:
- kubectl, a command-line tool for managing Kubernetes clusters.
- Helm 3.0 or later, for deploying and managing applications on Kubernetes.
- If you’d like to use NGINX Plus:
- To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from here. Make sure to specify the secret using
nginxGateway.serviceAccount.imagePullSecret
ornginxGateway.serviceAccount.imagePullSecrets
parameter. - Alternatively, pull an NGINX Gateway Fabric image with NGINX Plus and push it to your private registry by following the instructions from here.
- Update the
nginxGateway.image.repository
field of thevalues.yaml
accordingly.
- To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from here. Make sure to specify the secret using
Deploy NGINX Gateway Fabric
Installing the Gateway API resources
Note:
The Gateway API resources from the standard channel must be installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure they are the correct version as supported by the NGINX Gateway Fabric - see the Technical Specifications.
To install the Gateway API resources, run the following:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl apply -f -
Note:
If you plan to use theedge
version of NGINX Gateway Fabric, you can replace the version inref
withmain
, for exampleref=main
.
Alternatively, you can install the Gateway API resources from the experimental channel. We support a subset of the additional features provided by the experimental channel. To install from the experimental channel, run the following:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.4.0" | kubectl apply -f -
Install from the OCI registry
To install the latest stable release of NGINX Gateway Fabric in the nginx-gateway namespace, run the following command:
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
Note:
If applicable, replace the F5 Container registryprivate-registry.nginx.com
with your internal registry for your NGINX Plus image, and replacenginx-plus-registry-secret
with your Secret name containing the registry credentials.
Important:
Ensure that you Enable Usage Reporting when installing.
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set serviceAccount.imagePullSecret=nginx-plus-registry-secret --create-namespace -n nginx-gateway
ngf
is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name.
If the namespace already exists, you can omit the optional --create-namespace
flag. If you want the latest version from the main branch, add --version 0.0.0-edge
to your install command.
You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for NGINX Plus, for example:
$ curl https://private-registry.nginx.com/v2/nginx-gateway-fabric/nginx-plus/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
{
"name": "nginx-gateway-fabric/nginx-plus",
"tags": ["edge"]
}
To wait for the Deployment to be ready, you can either add the --wait
flag to the helm install
command, or run the following after installing:
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
Install from sources
-
Pull the latest stable release of the NGINX Gateway Fabric chart:
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar cd nginx-gateway-fabric
If you want the latest version from the main branch, add
--version 0.0.0-edge
to your pull command. -
To install the chart into the nginx-gateway namespace, run the following command.
helm install ngf . --create-namespace -n nginx-gateway
ngf
is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name.If the namespace already exists, you can omit the optional
--create-namespace
flag.To wait for the Deployment to be ready, you can either add the
--wait
flag to thehelm install
command, or run the following after installing:kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
Custom installation options
Service type
By default, the NGINX Gateway Fabric helm chart deploys a LoadBalancer Service.
To use a NodePort Service instead:
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.type=NodePort
To disable the creation of a Service:
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false
Experimental features
We support a subset of the additional features provided by the Gateway API experimental channel. To enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric:
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginxGateway.gwAPIExperimentalFeatures.enable=true
Note:
Requires the Gateway APIs installed from the experimental channel.
Examples
You can find several examples of configuration options of the values.yaml
file in the helm examples directory.
Access NGINX Gateway Fabric
There are two options for accessing NGINX Gateway Fabric depending on the type of LoadBalancer service you chose during installation:
-
If the LoadBalancer type is
NodePort
, Kubernetes will randomly allocate two ports on every node of the cluster. To access the NGINX Gateway Fabric, use an IP address of any node of the cluster along with the two allocated ports.Tip:
Read more about the type NodePort in the Kubernetes documentation. -
If the LoadBalancer type is
LoadBalancer
:- For GCP or Azure, Kubernetes will allocate a cloud load balancer for load balancing the NGINX Gateway Fabric pods. Use the public IP of the load balancer to access NGINX Gateway Fabric.
- For AWS, Kubernetes will allocate a Network Load Balancer (NLB) in TCP mode with the PROXY protocol enabled to pass the client’s information (the IP address and the port).
Use the public IP of the load balancer to access NGINX Gateway Fabric. To get the public IP which is reported in the
EXTERNAL-IP
column:-
For GCP or Azure, run:
kubectl get svc nginx-gateway -n nginx-gateway
-
In AWS, the NLB (Network Load Balancer) DNS (directory name system) name will be reported by Kubernetes instead of a public IP. To get the DNS name, run:
kubectl get svc nginx-gateway -n nginx-gateway
Note:
We recommend using the NLB DNS whenever possible, but for testing purposes, you can resolve the DNS name to get the IP address of the load balancer:
nslookup <dns-name>
Tip:
Learn more about type LoadBalancer in the Kubernetes documentation.
For AWS, additional options regarding an allocated load balancer are available, such as its type and SSL termination. Read the Kubernetes documentation to learn more.
NGINX Gateway Fabric uses the created service to update the Addresses field in the Gateway Status resource. Using a LoadBalancer service sets this field to the IP address and/or hostname of that service. Without a service, the pod IP address is used.
This gateway is associated with the NGINX Gateway Fabric through the gatewayClassName field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name nginx. NGINX Gateway Fabric will only configure gateways with a gatewayClassName of nginx unless you change the name via the --gatewayclass
command-line flag.
Upgrade NGINX Gateway Fabric
Tip:
For guidance on zero downtime upgrades, see the Delay Pod Termination section below.
To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps:
Upgrade Gateway resources
To upgrade your Gateway API resources, take the following steps:
-
Verify the Gateway API resources are compatible with your NGINX Gateway Fabric version. Refer to the Technical Specifications for details.
-
Review the release notes for any important upgrade-specific information.
-
To upgrade the Gateway API resources, run:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl apply -f -
or, if you installed the from the experimental channel:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.4.0" | kubectl apply -f -
Upgrade NGINX Gateway Fabric CRDs
Helm’s upgrade process does not automatically upgrade the NGINX Gateway Fabric CRDs (Custom Resource Definitions).
To upgrade the CRDs, take the following steps:
-
Pull the latest stable release of the NGINX Gateway Fabric chart:
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar cd nginx-gateway-fabric
If you want the latest version from the main branch, add
--version 0.0.0-edge
to your pull command. -
Upgrade the CRDs:
kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.4.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
Upgrade from the OCI registry
-
To upgrade to the latest stable release of NGINX Gateway Fabric, run:
helm upgrade ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric -n nginx-gateway
If needed, replace
ngf
with your chosen release name.
Upgrade from sources
-
Pull the latest stable release of the NGINX Gateway Fabric chart:
helm pull oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --untar cd nginx-gateway-fabric
If you want 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
If needed, replace
ngf
with your chosen release name.
How to upgrade from NGINX OSS to NGINX Plus
-
To upgrade from NGINX OSS to NGINX Plus, update the Helm command to include the necessary values for Plus:
Note:
If applicable, replace the F5 Container registryprivate-registry.nginx.com
with your internal registry for your NGINX Plus image, and replacenginx-plus-registry-secret
with your Secret name containing the registry credentials.Important:
Ensure that you Enable Usage Reporting when installing.helm upgrade ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set serviceAccount.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway
If needed, replace
ngf
with your chosen release name.
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:
-
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:
Uninstall NGINX Gateway Fabric
Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster:
-
Uninstall NGINX Gateway Fabric:
-
To uninstall NGINX Gateway Fabric, run:
helm uninstall ngf -n nginx-gateway
If needed, replace
ngf
with your chosen release name.
-
-
Remove namespace and CRDs:
-
To remove the nginx-gateway namespace and its custom resource definitions (CRDs), run:
kubectl delete ns nginx-gateway kubectl delete -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.4.0/deploy/crds.yaml
-
-
Remove the Gateway API resources:
- Warning:
This will remove all corresponding custom resources in your entire cluster, across all namespaces. Double-check to make sure you don’t have any custom resources you need to keep, and confirm that there are no other Gateway API implementations active in your cluster.To uninstall the Gateway API resources, run the following:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl delete -f -
Alternatively, if you installed the Gateway APIs from the experimental channel, run the following:
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.4.0" | kubectl delete -f -
Additional configuration
For a full list of the Helm Chart configuration parameters, read the NGINX Gateway Fabric Helm Chart.