Installation with Kubernetes manifests
Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernetes manifests.
Prerequisites
To complete this guide, you’ll need to install:
- kubectl, a command-line interface for managing Kubernetes clusters.
Deploy NGINX Gateway Fabric
Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps. With manifests, you can configure your deployment exactly how you want. Manifests also make it easy to replicate deployments across environments or clusters, ensuring consistency.
- 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 in the
imagePullSecrets
field of thenginx-gateway
ServiceAccount. - 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 nginx container’s
image
field of thenginx-gateway
Deployment 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 in the
1. Install 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
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 apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/experimental-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.
2. Deploy the NGINX Gateway Fabric CRDs
Stable release
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/crds.yaml
Edge version
git clone https://github.com/nginxinc/nginx-gateway-fabric.git
cd nginx-gateway-fabric
kubectl apply -f deploy/manifests/crds
3. Deploy NGINX Gateway Fabric
Note:
By default, NGINX Gateway Fabric is installed in the nginx-gateway namespace. You can deploy in another namespace by modifying the manifest files.
Stable release
For NGINX
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/nginx-gateway.yaml
For NGINX Plus
Download the deployment YAML.
Update the nginx-plus-gateway.yaml
file to include your chosen NGINX Plus image from the F5 Container registry or your custom image.
Important:
Ensure that you Enable Usage Reporting before applying.
kubectl apply -f nginx-plus-gateway.yaml
Edge version
For NGINX
kubectl apply -f deploy/manifests/nginx-gateway.yaml
For NGINX Plus
Important:
Ensure that you Enable Usage Reporting before applying.
kubectl apply -f deploy/manifests/nginx-plus-gateway.yaml
Update the nginx-plus-gateway.yaml file to include your chosen image from the F5 Container registry or your custom container image.
Enable 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:
For NGINX
kubectl apply -f deploy/manifests/nginx-gateway-experimental.yaml
For NGINX Plus
kubectl apply -f deploy/manifests/nginx-plus-gateway-experimental.yaml
Update the nginx-plus-gateway-experimental.yaml file to include your chosen image from the F5 Container registry or your custom container image.
Note:
Requires the Gateway APIs installed from the experimental channel.
4. Verify the Deployment
To confirm that NGINX Gateway Fabric is running, check the pods in the nginx-gateway
namespace:
kubectl get pods -n nginx-gateway
The output should look similar to this (note that the pod name will include a unique string):
NAME READY STATUS RESTARTS AGE
nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s
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 API resources:
-
Verify that your NGINX Gateway Fabric version is compatible with the Gateway API resources. 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
or, if you installed the from the experimental channel:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/experimental-install.yaml
-
If you are running on Kubernetes 1.23 or 1.24, you also need to update the validating webhook:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
-
If you are running on Kubernetes 1.25 or newer and have the validating webhook installed, you should remove the webhook:
kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/webhook-install.yaml
-
-
Upgrade NGINX Gateway Fabric CRDs:
-
To upgrade the Custom Resource Definitions (CRDs), run:
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/crds.yaml
-
-
Upgrade NGINX Gateway Fabric deployment:
-
To upgrade the deployment, run:
kubectl apply -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/nginx-gateway.yaml
-
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
nginx-gateway.yaml
for editing. -
Add delayed shutdown hooks:
-
In the
nginx-gateway.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.<...> name: nginx-gateway <...> lifecycle: preStop: exec: command: - /usr/bin/gateway - sleep - --duration=40s # This flag is optional, the default is 30s <...> name: 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 remove NGINX Gateway Fabric and its custom resource definitions (CRDs), run:
kubectl delete -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/nginx-gateway.yaml
kubectl delete -f https://github.com/nginxinc/nginx-gateway-fabric/releases/download/v1.2.0/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 delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
Alternatively, if you installed the Gateway APIs from the experimental channel, run the following:
kubectl delete -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/experimental-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.