diff --git a/content/includes/ngf/installation/deploy-ngf-crds.md b/content/includes/ngf/installation/deploy-ngf-crds.md new file mode 100644 index 000000000..14161e06c --- /dev/null +++ b/content/includes/ngf/installation/deploy-ngf-crds.md @@ -0,0 +1,18 @@ +--- +nd-docs: "DOCS-000" +files: +- content/ngf/install/manifests.md +- content/nginx-one/ngf/add-ngf-manifests.md +--- + +#### Stable release + +```shell +kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml +``` + +#### Edge version + +```shell +kubectl apply --server-side -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml +``` diff --git a/content/includes/ngf/installation/deploy-ngf-manifests.md b/content/includes/ngf/installation/deploy-ngf-manifests.md new file mode 100644 index 000000000..17183bbad --- /dev/null +++ b/content/includes/ngf/installation/deploy-ngf-manifests.md @@ -0,0 +1,115 @@ +--- +nd-docs: "DOCS-000" +files: +- content/ngf/install/manifests.md +- content/nginx-one/ngf/add-ngf-manifests.md +--- + +{{< call-out "note" >}} By default, NGINX Gateway Fabric is installed in the **nginx-gateway** namespace. You can deploy in another namespace by modifying the manifest files. {{< /call-out >}} + +{{}} + +{{%tab name="Default"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml +``` + +{{% /tab %}} + +{{%tab name="AWS NLB"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml +``` + +To set up an AWS Network Load Balancer service, add these annotations to your Gateway infrastructure field: + +```yaml +spec: + infrastructure: + annotations: + service.beta.kubernetes.io/aws-load-balancer-type: "external" + service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip" +``` + +{{% /tab %}} + +{{%tab name="Azure"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS and `nodeSelector` to deploy on Linux nodes. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/azure/deploy.yaml +``` + +{{% /tab %}} + +{{%tab name="NGINX Plus"%}} + +Deploys NGINX Gateway Fabric with NGINX Plus. The image is pulled from the +NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Secret to use to pull the image. +The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/nginx-plus/deploy.yaml +``` + +{{% /tab %}} + +{{%tab name="Experimental"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS and experimental features. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/experimental/deploy.yaml +``` + +{{< call-out "note" >}} Requires the Gateway APIs installed from the experimental channel. {{< /call-out >}} + +{{% /tab %}} + +{{%tab name="NGINX Plus Experimental"%}} + +Deploys NGINX Gateway Fabric with NGINX Plus and experimental features. The image is pulled from the +NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Secret to use to pull the image. +The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/nginx-plus-experimental/deploy.yaml +``` + +{{< call-out "note" >}} Requires the Gateway APIs installed from the experimental channel. {{< /call-out >}} + +{{% /tab %}} + +{{%tab name="NodePort"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS using a Service type of `NodePort`. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/nodeport/deploy.yaml +``` + +{{% /tab %}} + +{{%tab name="OpenShift"%}} + +Deploys NGINX Gateway Fabric with NGINX OSS on OpenShift. + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/openshift/deploy.yaml +``` + +{{% /tab %}} + +{{}} + +### Provision an NGINX data plane + +To deploy the NGINX data plane to connect to the NGINX One Console, follow this guide: [Deploy a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}). + diff --git a/content/includes/ngf/installation/install-manifests-prereqs.md b/content/includes/ngf/installation/install-manifests-prereqs.md new file mode 100644 index 000000000..0385a4399 --- /dev/null +++ b/content/includes/ngf/installation/install-manifests-prereqs.md @@ -0,0 +1,13 @@ +--- +nd-docs: "DOCS-000" +files: +- content/ngf/install/manifests.md +- content/nginx-one/ngf/add-ngf-manifests.md +--- + +To complete this guide, you'll need to install: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters. +- [Add certificates for secure authentication]({{< ref "/ngf/install/secure-certificates.md" >}}) in a production environment. + +{{< call-out "important" >}} If you’d like to use NGINX Plus, some additional setup is also required: {{< /call-out >}} diff --git a/content/includes/nginx-one/how-to/generate-data-plane-key.md b/content/includes/nginx-one/how-to/generate-data-plane-key.md index f9ec47016..ff227ee69 100644 --- a/content/includes/nginx-one/how-to/generate-data-plane-key.md +++ b/content/includes/nginx-one/how-to/generate-data-plane-key.md @@ -3,6 +3,9 @@ docs: files: - content/nginx-one/secure-your-fleet/set-up-security-alerts.md - content/nginx-one/getting-started.md + - content/nginx-one/ngf/add-nic.md + - content/nginx-one/ngf/add-ngf-helm.md + - content/nginx-one/ngf/add-ngf-manifests.md --- A data plane key is a security token that ensures only trusted NGINX instances can register and communicate with NGINX One. @@ -17,3 +20,5 @@ 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]({{< ref "nginx-one/connect-instances/create-manage-data-plane-keys.md#change-expiration-date" >}}). If you [revoke a data plane key]({{< ref "nginx-one/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]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}). diff --git a/content/includes/nginx-one/how-to/k8s-secret-dp-key.md b/content/includes/nginx-one/how-to/k8s-secret-dp-key.md new file mode 100644 index 000000000..bb9db5f75 --- /dev/null +++ b/content/includes/nginx-one/how-to/k8s-secret-dp-key.md @@ -0,0 +1,20 @@ +--- +nd-docs: "DOCS-000" +files: +- content/nginx-one/k8s/add-ngf-manifests.md +- content/nginx-one/k8s/add-ngf-helm.md +--- + +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= \ + -n nginx-gateway + ``` + diff --git a/content/includes/nginx-one/how-to/ngf-troubleshooting.md b/content/includes/nginx-one/how-to/ngf-troubleshooting.md new file mode 100644 index 000000000..52a9db7a0 --- /dev/null +++ b/content/includes/nginx-one/how-to/ngf-troubleshooting.md @@ -0,0 +1,26 @@ +--- +nd-docs: "DOCS-000" +files: +- content/nginx-one/k8s/add-ngf-manifests.md +- content/nginx-one/k8s/add-ngf-helm.md +--- + +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 -- nginx-agent -v +``` + +Check the NGINX Agent configuration: + +```shell +kubectl exec -it -n -- cat /etc/nginx-agent/nginx-agent.conf +``` + +Check NGINX Agent logs: + +```shell +kubectl exec -it -n -- nginx-agent +``` diff --git a/content/includes/nginx-one/how-to/verify-connection.md b/content/includes/nginx-one/how-to/verify-connection.md new file mode 100644 index 000000000..189176a6d --- /dev/null +++ b/content/includes/nginx-one/how-to/verify-connection.md @@ -0,0 +1,14 @@ +--- +nd-docs: "DOCS-000" +files: +- content/nginx-one/k8s/add-ngf-manifests.md +- content/nginx-one/k8s/add-ngf-helm.md +--- + +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**. + diff --git a/content/nginx-one/connect-instances/create-manage-data-plane-keys.md b/content/nginx-one/connect-instances/create-manage-data-plane-keys.md index 0052e684c..f12585911 100644 --- a/content/nginx-one/connect-instances/create-manage-data-plane-keys.md +++ b/content/nginx-one/connect-instances/create-manage-data-plane-keys.md @@ -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. {{}} ## Create a new data plane key diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index 3f273ef24..c5f0cf60e 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -110,20 +110,9 @@ The following instructions include minimal information, sufficient to "get start ### Generate a data plane key {#generate-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: - -- **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. - -{{}} -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]({{< ref "nginx-one/connect-instances/create-manage-data-plane-keys.md#change-expiration-date" >}}). +{{< include "/nginx-one/how-to/generate-data-plane-key.md" >}} [Revoking a data plane key]({{< ref "nginx-one/connect-instances/create-manage-data-plane-keys.md#revoke-data-plane-key" >}}) disconnects all instances that were registered with that key. -{{}} ### Add an instance @@ -132,7 +121,6 @@ Depending on whether this is your first time using NGINX One Console or you've u - **For first-time users:** On the welcome screen, select **Add Instance**. - **For returning users:** If you've added instances previously and want to add more, select **Instances** on the left menu, then select **Add Instance**. - ### Install NGINX Agent After entering your data plane key, you'll see a `curl` command similar to the one below. Copy and run this command on each NGINX instance to install NGINX Agent. Once installed, NGINX Agent typically registers with NGINX One within a few seconds. diff --git a/content/nginx-one/k8s/add-ngf-helm.md b/content/nginx-one/k8s/add-ngf-helm.md new file mode 100644 index 000000000..4309ff988 --- /dev/null +++ b/content/nginx-one/k8s/add-ngf-helm.md @@ -0,0 +1,139 @@ +--- +title: Connect NGINX Gateway Fabric with Helm +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 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]({{< ref "/nginx-one/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 + +{{< include "/nginx-one/how-to/generate-data-plane-key.md" >}} + +### Create a Kubernetes secret with the data plane key + +{{< include "/nginx-one/how-to/k8s-secret-dp-key.md" >}} + +## Install Gateway API resources + +{{< include "/ngf/installation/install-gateway-api-resources.md" >}} + +## 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](#install-from-sources) instead. + +{{}} + +{{%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 \ + --set nginx.nginxOneConsole.dataplaneKeySecretName= \ + -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 \ + --set nginx.nginxOneConsole.dataplaneKeySecretName= +``` + +{{% /tab %}} + +{{}} + +`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} + +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" >}} + +{{}} + +{{%tab name="NGINX"%}} + +To install the chart into the **nginx-gateway** namespace, run the following command: + +```shell +helm install ngf . \ + --set nginx.nginxOneConsole.dataplaneKeySecretName= \ + -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.nginxOneConsole.dataplaneKeySecretName= \ + --set nginx.plus=true \ + --set nginx.imagePullSecret=nginx-plus-registry-secret \ + -n nginx-gateway +``` + +{{% /tab %}} + +{{}} + +`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 + +{{< include "/nginx-one/how-to/verify-connection.md" >}} + +## Troubleshooting + +{{< include "/nginx-one/how-to/ngf-troubleshooting.md" >}} diff --git a/content/nginx-one/k8s/add-ngf-manifests.md b/content/nginx-one/k8s/add-ngf-manifests.md new file mode 100644 index 000000000..b7d675331 --- /dev/null +++ b/content/nginx-one/k8s/add-ngf-manifests.md @@ -0,0 +1,59 @@ +--- +title: Connect NGINX Gateway Fabric with Manifests +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 with Manifests. +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" >}}). + +{{< include "/ngf/installation/install-manifests-prereqs.md" >}} + +### Create a data plane key + +{{< include "/nginx-one/how-to/generate-data-plane-key.md" >}} + +### Create a Kubernetes secret with the data plane key + +{{< include "/nginx-one/how-to/k8s-secret-dp-key.md" >}} + +## Install Gateway API resources + +{{< include "/ngf/installation/install-gateway-api-resources.md" >}} + +## Deploy NGINX Gateway Fabric CRDs + + +{{< include "/ngf/installation/deploy-ngf-crds.md" >}} + +## Deploy NGINX Gateway Fabric + +Specify the data plane key Secret name in the `--nginx-one-dataplane-key-secret` command-line argument of the nginx-gateway container. + +{{< include "/ngf/installation/deploy-ngf-manifests.md" >}} + +## Verify a connection to NGINX One Console + +{{< include "/nginx-one/how-to/verify-connection.md" >}} + +## Troubleshooting + +{{< include "/nginx-one/how-to/ngf-troubleshooting.md" >}} + +## References + +For more details, see: + +- [Install NGINX Gateway Fabric with Manifests]({{< ref "/ngf/install/manifests.md" >}}) + diff --git a/content/nginx-one/k8s/add-nic.md b/content/nginx-one/k8s/add-nic.md index 7c55d6eb8..efe6a5f53 100644 --- a/content/nginx-one/k8s/add-nic.md +++ b/content/nginx-one/k8s/add-nic.md @@ -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 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: @@ -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