# Connect NGINX Gateway Fabric with Helm

Type of document: How-to guide
Product: NGINX One Console

---


This document explains how to connect F5 NGINX Gateway Fabric to F5 NGINX One Console with Helm.
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

## Before you begin

Log in to NGINX One Console. If you need more information, review our [Get started guide](/nginx-one-console/getting-started.md#before-you-begin).

You also need:

- Administrator access to a Kubernetes cluster.
- If you use [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl), install them locally.

### Create a data plane key

A data plane key is a security token that ensures only trusted NGINX instances can register and communicate with NGINX One.

To generate a data plane key, select **Manage > Instances > Add Instance**:

- **For a new key:** In the **Add Instance** pane, select **Generate Data Plane Key**.
- **To reuse an existing key:** If you already have a data plane key and want to use it again, select **Use existing key**. Then, enter the key's value in the **Data Plane Key** box.

**Note:** 
Data plane keys are displayed only once and cannot be retrieved later. Be sure to copy and store this key securely.

Data plane keys expire after one year. You can change this expiration date later by [editing the key](/nginx-one-console/connect-instances/create-manage-data-plane-keys.md#change-expiration-date). If you [revoke a data plane key](/nginx-one-console/connect-instances/create-manage-data-plane-keys.md#revoke-data-plane-key) you disconnect all instances registered with that key.

For more options associated with data plane keys, see [Create and manage data plane keys](/nginx-one-console/connect-instances/create-manage-data-plane-keys.md).

### Create a Kubernetes secret with the data plane key

To create a Kubernetes secret, you'll need:

- The Data Plane Key
- The `nginx-gateway` namespace must exist. You can create it with the following command: `kubectl create namespace nginx-gateway`

   - Then create the secret with the following command. The key must be named `dataplane.key`:

   ```shell
   kubectl create secret generic dataplane-key \
     --from-literal=dataplane.key=<Your Dataplane Key> \
     -n nginx-gateway
   ```

## Install Gateway API resources
<!-- Corresponds to step 2 in the UX -->
**Note:**  The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) 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](https://github.com/nginx/nginx-gateway-fabric/blob/v/README.md#technical-specifications). 

To install the Gateway API resources, run the following:

```shell
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v" | kubectl apply -f -
```

**Note:**  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:

```shell
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v" | kubectl apply -f -
```

**Note:**  To learn more about what Gateway API resources NGINX Gateway Fabric currently supports, visit our [Gateway API Compatibility](/ngf/overview/gateway-api-compatibility.md) document.

## Install from the OCI registry
<!-- Corresponds to step 3 in the UX -->

The following steps install NGINX Gateway Fabric directly from the OCI helm registry. If you prefer, you can [install from sources](#install-from-sources) instead.

#### NGINX

To install the latest stable release of NGINX Gateway Fabric in the **nginx-gateway** namespace, run the following command:

```shell
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name> \
  -n nginx-gateway
```

#### NGINX Plus

**Note:**  

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:

```shell
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 \
  --set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name> 
```

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

```shell
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
```

### Install from sources {#install-from-sources}
<!-- Corresponds to step 4 in the UX -->
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.

#### NGINX

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

```shell
helm install ngf .  \
  --set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name> \
  -n nginx-gateway
```

#### NGINX Plus

**Note:**  

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:

```shell
helm install ngf . \
  --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus \
  --set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name> \
  --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:

```shell
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
```

## Deploy a Gateway

Now that the control plane is installed, you need to create a Gateway, which will provision NGINX and NGINX Agent. For example:

```yaml
kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP
EOF
```

An NGINX Deployment will be created in the `default` namespace (same namespace as the Gateway). Once `Running`, it should report to the NGINX One Console.

## Verify a connection to NGINX One Console

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, select **Manage > Control Planes**.  You should see your Control Planes listed by name, product, and version. Each control plane is associated with one or more instances.
- Select the name of the Control Plane. In the **Instances** section, select the instance of your choice. You can review instance details, including the name of the **Control Plane**.

## Troubleshooting

If you encounter issues connecting your instances to NGINX One Console, try the following commands:

Check the NGINX Agent version:

```shell
kubectl exec -it -n <namespace> <nginx_pod_name> -- nginx-agent -v
```

Check the NGINX Agent configuration:

```shell
kubectl exec -it -n <namespace> <nginx_pod_name> -- cat /etc/nginx-agent/nginx-agent.conf
```

Check NGINX Agent logs:

```shell
kubectl exec -it -n <namespace> <nginx_pod_name> -- nginx-agent
```