Install NGINX Gateway Fabric 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 will need:

Important
If you’d like to use NGINX Plus, some additional setup is also required:
NGINX Plus JWT setup

For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history:

  1. JWTs: JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access.

  2. Shell history: Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your ~/.bash_history file. Alternatively, you can run the history -c command to erase your shell history.

Follow these practices to help ensure the security of your system and data.

  1. Log in to MyF5.
  2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
  3. Find your NGINX products or services subscription, and select the Subscription ID for details.
  4. Download the JSON Web Token (JWT) from the subscription page.
The Connectivity Stack for Kubernetes JWT does not work with NGINX Plus reporting. A regular NGINX Plus instance JWT must be used.

If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow this step.

If the nginx-gateway namespace does not yet exist, create it:

kubectl create namespace nginx-gateway

Create a Kubernetes docker-registry secret type using the contents of the JWT as the username and none for password (as the password is not used). The name of the docker server is private-registry.nginx.com.

kubectl create secret docker-registry nginx-plus-registry-secret --docker-server=private-registry.nginx.com --docker-username=<JWT Token> --docker-password=none -n nginx-gateway

It is important that the --docker-username=<JWT Token> contains the contents of the token and is not pointing to the token itself. When you copy the contents of the JWT, ensure there are no additional characters such as extra whitespaces. This can invalidate the token, causing 401 errors when trying to authenticate to the registry.

Place the JWT in a file called license.jwt. Create a Kubernetes Secret using the contents of the JWT file.

kubectl create secret generic nplus-license --from-file license.jwt -n nginx-gateway

You can now delete the license.jwt file.

If you need to update the JWT at any time, update the license.jwt field in the Secret using kubectl edit and apply the changes.

For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the NGINX Plus Image and JWT Requirement document.

Deploy NGINX Gateway Fabric

Installing the Gateway API resources

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/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.2.1" | kubectl apply -f -
If you plan to use the edge version of NGINX Gateway Fabric, you can replace the version in ref with main, for example ref=main.

Alternatively, you can install the Gateway API resources from the experimental channel. Installing Gateway API resources from the experimental channel includes everything in the standard release channel plus additional experimental resources and fields. NGINX Gateway Fabric currently supports 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/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v2.2.1" | kubectl apply -f -
To learn more about what Gateway API resources NGINX Gateway Fabric currently supports, visit our Gateway API Compatibility document.

Install from the OCI registry

The following steps install NGINX Gateway Fabric directly from the OCI helm registry. If you prefer, you can install from sources instead.

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/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
If applicable, replace the F5 Container registry private-registry.nginx.com with your internal registry for your NGINX Plus image, and replace nginx-plus-registry-secret with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default nplus-license, then define that name using the nginx.usage.secretName flag.

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/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

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

If you prefer to install directly from sources, instead of through the OCI helm registry, use the following steps.

shell
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 install the chart into the nginx-gateway namespace, run the following command:

helm install ngf . --create-namespace -n nginx-gateway
If applicable, replace the F5 Container registry private-registry.nginx.com with your internal registry for your NGINX Plus image, and replace nginx-plus-registry-secret with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default nplus-license, then define that name using the nginx.usage.secretName flag.

To install the chart into the nginx-gateway namespace, run the following command:

helm install ngf . --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

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.

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 control plane deploys a LoadBalancer Service when a Gateway is created.

To use a NodePort Service instead:

helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginx.service.type=NodePort

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/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginxGateway.gwAPIExperimentalFeatures.enable=true
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

The Service that is provisioned when NGINX Gateway Fabric is first installed is a ClusterIP Service used only for internal communication between the control plane and data planes. To deploy NGINX itself and get a LoadBalancer Service, you now need to create a Gateway.

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:

      shell
      kubectl delete ns nginx-gateway
kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.2.1/deploy/crds.yaml

  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 kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.2.1" | kubectl delete -f -

      Alternatively, if you installed the Gateway APIs from the experimental channel, run the following:

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

Next steps

For a full list of the Helm Chart configuration parameters, read the NGINX Gateway Fabric Helm Chart.

View source
Edit this page
Create a new issue