Installation with Helm

Learn how to install, upgrade, and uninstall NGINX Gateway Fabric in a Kubernetes cluster with Helm.

Prerequisites

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.

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 apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml

If you are running on Kubernetes 1.23 or 1.24, you also need to install the validating webhook. To do so, run:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
Important:
The validating webhook is not needed if you are running Kubernetes 1.25+. Validation is done using CEL on the CRDs. See the resource validation doc for more information.

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
    

    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.

    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

  1. 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.

  2. 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 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
    

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

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 apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
    

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:

  1. 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.

  2. Upgrade the CRDs:

    kubectl apply -f crds/
    
    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

  1. 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.

  2. To upgrade, run: the following command:

    helm upgrade ngf . -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:

  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:

Uninstall NGINX Gateway Fabric

Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster:

  1. 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.

  2. Remove namespace and CRDs:

    • To remove the nginx-gateway namespace and its custom resource definitions (CRDs), run:

      kubectl delete ns nginx-gateway
      kubectl delete crd nginxgateways.gateway.nginx.org
      
  3. 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 delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
      

      If you are running on Kubernetes 1.23 or 1.24, you also need to delete the validating webhook. To do so, run:

      kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
      

Next steps

Expose NGINX Gateway Fabric

After installing NGINX Gateway Fabric, the next step is to make it accessible. Detailed instructions can be found in Expose the NGINX Gateway Fabric.