Connect NGINX Gateway Fabric
This document explains how to connect F5 NGINX Gateway Fabric to F5 NGINX One Console using NGINX Agent. Connecting NGINX Gateway Fabric to NGINX One Console enables centralized monitoring of all controller instances.
Once connected, you’ll see a read-only configuration of NGINX Gateway Fabric. For each instance, you can review:
- Read-only configuration file
- Unmanaged SSL/TLS certificates for Control Planes
Log in to NGINX One Console. If you need more information, review our Get started guide.
You also need:
Data plane keys are displayed only once, when you create that key, and cannot be retrieved later.
If you’ve created and recorded one or more data plane keys, you can edit or revoke those keys. To do so, select Manage > Data Plane Keys. NGINX One Console does not store your actual data plane key.
If you’ve forgotten your data plane key, you can create a new one. Select Manage > Data Plane Keys > Add Data Plane Key.
For more options associated with data plane keys, see [Create and manage data plane keys]({{ ref “/nginx-one/connect-instances/create-manage-data-plane-keys” >}}).
To create a Kubernetes secret with the data play key, use the following command:
kubectl create secret generic dataplane-key \
--from-literal=dataplane.key=<Your Dataplane Key> \
-n <namespace>
Add the Helm repository:
helm repo add jetstack https://charts.jetstack.io
helm repo update
Install cert-manager:
helm install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--set config.apiVersion="controller.config.cert-manager.io/v1alpha1" \
--set config.kind="ControllerConfiguration" \
--set config.enableGatewayAPI=true \
--set crds.enabled=true
This also enables Gateway API features for cert-manager, which can be useful for securing your workload traffic.
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/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.0.2" | 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. 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.0.2" | kubectl apply -f -
Note: To learn more about what Gateway API resources NGINX Gateway Fabric currently supports, visit our Gateway API Compatibility document.
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
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. If your NGINX Plus JWT Secret has a different name than the defaultnplus-license
, then define that name using thenginx.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
If you prefer to install directly from sources, instead of through the OCI helm registry, use the following steps.
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
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. If your NGINX Plus JWT Secret has a different name than the defaultnplus-license
, then define that name using thenginx.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
After deploying NGINX Gateway Fabric with NGINX Agent, you can verify the connection to NGINX One Console. Log in to your F5 Distributed Cloud Console account. Select NGINX One > Visit Service. In the dashboard, go to Manage > Instances. You should see your instances listed by name. The instance name matches both the hostname and the pod name.
If you encounter issues connecting your instances to NGINX One Console, try the following commands:
Check the NGINX Agent version:
kubectl exec -it -n <namespace> <nginx_pod_name> -- nginx-agent -v
Check the NGINX Agent configuration:
kubectl exec -it -n <namespace> <nginx_pod_name> -- cat /etc/nginx-agent/nginx-agent.conf
Check NGINX Agent logs:
kubectl exec -it -n <namespace> <nginx_pod_name> -- nginx-agent