Skip to content

feat: Set up NGF integration to N1 Console #902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: Set up NGF integration to N1 Console #902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
57ddc1e
feat: Set up NGF integration to N1 Console
mjang Jul 25, 2025
0975f31
delete unneeded file
mjang Jul 29, 2025
8480284
Apply suggestions from code review
mjang Aug 6, 2025
d602ee7
Apply suggestions from code review
mjang Aug 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions content/includes/ngf/installation/install-oci-registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
nd-docs: "DOCS-0000"
files:
- content/nginx-one/k8s/add-ngf.md
- content/ngf/install/helm.md
---

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.

{{<tabs name="install-helm-oci">}}

{{%tab name="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 --create-namespace -n nginx-gateway
```

{{% /tab %}}

{{%tab name="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. {{< /note >}}

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

{{% /tab %}}

{{</tabs>}}

`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
7 changes: 6 additions & 1 deletion content/nginx-one/connect-instances/create-manage-data-plane-keys.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,12 @@ Data plane keys are displayed only once and cannot be retrieved later. Be sure t

Data plane keys expire after one year. You can change this expiration date later by editing the key.

Revoking a data plane key disconnects all instances that were registered with that key.
You can disconnect all instances associated with a data plane key in the following ways:

- Revoke the data plane key
- Let the data plane key expire

Either action disconnects all instances registered with that key.
{{</call-out>}}

## Create a new data plane key
Expand Down
133 changes: 133 additions & 0 deletions content/nginx-one/k8s/add-ngf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
---
title: Connect NGINX Gateway Fabric
toc: true
weight: 300
nd-content-type: how-to
nd-product: NGINX One
---

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

## Before you begin

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

You also need:

- Administrator access to a Kubernetes cluster.
- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally.


### Create a data plane key

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.md" >}}).

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

To create a Kubernetes secret, you'll need:

- The Data Plane Key
- To set up the secret in the same namespace as NGINX Gateway Fabric
- Use the name `dataplane.key` as shown
- A namespace. The default NGINX Gateway Fabric namespace is `nginx-gateway`

Once you have that information, run the following command:


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


## Install the Gateway API resources
<!-- Corresponds to step 2 in the UX -->
{{< include "/ngf/installation/install-gateway-api-resources.md" >}}

## Install from the OCI registry
<!-- Corresponds to step 3 in the UX -->
{{< include "/ngf/installation/install-oci-registry.md" >}}

### Install from sources {#install-from-sources}
Comment on lines +60 to +64
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll need to include setting the flag specifying the secret name when installing through Helm for all the commands,

--set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name>

Like they do in NIC.

We can also specify through manifests they need to add the --nginx-one-dataplane-key-secret=<data_plane_key_secret_name> argument on the NGF deployment.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bjee19 can you be more specific? I don't see examples where we use

  • --set nginx.nginxOneConsole.dataplaneKeySecretName=<data_plane_key_secret_name>
  • --nginx-one-dataplane-key-secret=<data_plane_key_secret_name>

In our NIC docs

Copy link
Contributor

@sylwang sylwang Aug 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is where we use a similar --set flag to set these parameters in the NIC docs:
https://docs.nginx.com/nginx-one/k8s/add-nic/

Below is the command mentioned in the NIC doc:

helm upgrade --install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version 2.2.1 \
  --set nginxAgent.enable=true \
  --set nginxAgent.dataplaneKeySecretName=<data_plane_key_secret_name> \
  --set nginxAgent.endpointHost=agent.connect.nginx.com

There was also a question about the consistency (using nginx.nginxAgent versus nginx.nginxOneConsole) in this slack discussion: https://f5.slack.com/archives/C07RT2VUTBL/p1755121421428819
We decided that this is not a concern since NGINX Agent has a bigger presence/use in NIC.

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

{{< include "/ngf/installation/helm/pulling-the-chart.md" >}}

{{<tabs name="install-helm-src">}}

{{%tab name="NGINX"%}}

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

```shell
helm install ngf . --create-namespace -n nginx-gateway
```

{{% /tab %}}

{{%tab name="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. {{< /note >}}

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.plus=true --set nginx.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway
```

{{% /tab %}}

{{</tabs>}}

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

## 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
```
8 changes: 6 additions & 2 deletions content/nginx-one/k8s/add-nic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: Connect to NGINX One Console
title: Connect NGINX Ingress Controller
toc: true
weight: 200
nd-content-type: how-to
nd-product: NGINX One
---

This document explains how to connect F5 NGINX Ingress Controller <!-- and F5 NGINX Gateway Fabric -->to F5 NGINX One Console using NGINX Agent.
This document explains how to connect F5 NGINX Ingress Controller to F5 NGINX One Console using NGINX Agent.
Connecting NGINX Ingress Controller to NGINX One Console enables centralized monitoring of all controller instances.

Once connected, you'll see a **read-only** configuration of NGINX Ingress Controller. For each instance, you can review:
Expand All @@ -16,6 +16,10 @@ Once connected, you'll see a **read-only** configuration of NGINX Ingress Contro

## Before you begin

If you do not already have a [data plane key]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}), you can create one. Pay attention to the expiration date of that key. Any instance that's connected to a data plane key that's expired or revoked will stop working.

You can create a data plane key through the NGINX One Console. Once loggged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown.

Before connecting NGINX Ingress Controller to NGINX One Console, you need to create a Kubernetes Secret with the data plane key. Use the following command:

```shell
Expand Down