diff --git a/_banners/ngf-2.0-release.md b/_banners/ngf-2.0-release.md index 60d957137..135681553 100644 --- a/_banners/ngf-2.0-release.md +++ b/_banners/ngf-2.0-release.md @@ -1,7 +1,7 @@ {{< banner "notice" "NGINX Gateway Fabric 2.0 is now available" >}} -NGINX Gateway Fabric 2.0 has released! Follow [this guide]({{< ref "/ngf/upgrading-ngf.md" >}}) to upgrade from 1.x to 2.0. +NGINX Gateway Fabric 2.0 has released! Follow [these instructions]({{< ref "/ngf/install/upgrade-version.md#upgrade-from-v1x-to-v2x" >}}) to upgrade from 1.x to 2.0. -For 1.x, checkout [an older version](https://github.com/nginx/documentation/commit/0be97114d93be0f44acff8711f31bf0b6448dd94) of documentation. +For 1.x, checkout [an older version]({{< ref "/ngf/install/upgrade-version.md#access-nginx-gateway-fabric-1x-documentation" >}}) of documentation. {{< /banner >}} \ No newline at end of file diff --git a/content/includes/ngf/installation/helm/pulling-the-chart.md b/content/includes/ngf/installation/helm/pulling-the-chart.md index 0d0a5071a..b82b2f809 100644 --- a/content/includes/ngf/installation/helm/pulling-the-chart.md +++ b/content/includes/ngf/installation/helm/pulling-the-chart.md @@ -2,11 +2,9 @@ docs: "DOCS-1439" --- -Pull the latest stable release of the NGINX Gateway Fabric chart: +```shell +helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar +cd nginx-gateway-fabric +``` - ```shell - helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar - cd nginx-gateway-fabric - ``` - - If you want the latest version from the **main** branch, add `--version 0.0.0-edge` to your pull command. +For the latest version from the **main** branch, add _--version 0.0.0-edge_ to your pull command. diff --git a/content/includes/ngf/installation/install-gateway-api-experimental-features.md b/content/includes/ngf/installation/install-gateway-api-experimental-features.md index db70cc083..aa95d1eb9 100644 --- a/content/includes/ngf/installation/install-gateway-api-experimental-features.md +++ b/content/includes/ngf/installation/install-gateway-api-experimental-features.md @@ -17,7 +17,7 @@ kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gate To enable experimental features on NGINX Gateway Fabric: Using Helm: Set `nginxGateway.gwAPIExperimentalFeatures.enable` to true. An example can be found -in the [Installation with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md#custom-installation-options" >}}) guide. +in the [Installation with Helm]({{< ref "/ngf/install/helm.md#custom-installation-options" >}}) guide. Using Kubernetes manifests: Add the `--gateway-api-experimental-features` command-line flag to the deployment manifest args. -An example can be found in the [Installation with Kubernetes manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md#3-deploy-nginx-gateway-fabric" >}}) guide. +An example can be found in the [Installation with Kubernetes manifests]({{< ref "/ngf/install/manifests.md#3-deploy-nginx-gateway-fabric" >}}) guide. diff --git a/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md b/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md index 6c5902604..c6d666b6d 100644 --- a/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md +++ b/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md @@ -2,7 +2,7 @@ docs: "DOCS-000" --- -{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/installation/nginx-plus-jwt.md#pulling-an-image-for-local-use" >}}). {{< /note >}} +{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/install/nginx-plus.md#pulling-an-image-for-local-use" >}}). {{< /note >}} If the `nginx-gateway` namespace does not yet exist, create it: diff --git a/content/ngf/releases.md b/content/ngf/changelog.md similarity index 52% rename from content/ngf/releases.md rename to content/ngf/changelog.md index 2dabcd11e..5453d1b8f 100644 --- a/content/ngf/releases.md +++ b/content/ngf/changelog.md @@ -1,11 +1,10 @@ --- -title: Releases -description: "NGINX Gateway Fabric releases." -weight: 800 +title: Changelog toc: true -type: reference -product: NGF -docs: "DOCS-1359" +weight: 900 +nd-content-type: reference +nd-product: NGF +nd-docs: "DOCS-1359" --- See the NGINX Gateway Fabric changelog page: diff --git a/content/ngf/get-started.md b/content/ngf/get-started.md index 202d9ebe2..c6a03bd0c 100644 --- a/content/ngf/get-started.md +++ b/content/ngf/get-started.md @@ -2,15 +2,15 @@ title: Get started weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- {{< important >}} This document is for trying out NGINX Gateway Fabric, and not intended for a production environment. -For standard deployments, you should read the [Install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}) section. +For standard deployments, you should read the [Install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}) section. {{< /important >}} This is a guide for getting started with NGINX Gateway Fabric. It explains how to: @@ -21,8 +21,6 @@ This is a guide for getting started with NGINX Gateway Fabric. It explains how t By following the steps in order, you will finish with a functional NGINX Gateway Fabric cluster. ---- - ## Before you begin To complete this guide, you need the following prerequisites installed: @@ -84,8 +82,6 @@ make create-kind-cluster {{< /note >}} ---- - ## Install NGINX Gateway Fabric ### Add Gateway API resources @@ -104,8 +100,6 @@ customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s. customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created ``` ---- - ### Install the Helm chart Use `helm` to install NGINX Gateway Fabric, specifying the NodePort configuration that will be set on the @@ -128,8 +122,6 @@ REVISION: 1 TEST SUITE: None ``` ---- - ## Create an example application In the previous section, you deployed NGINX Gateway Fabric to a local cluster. This section shows you how to deploy a simple web application to test that NGINX Gateway Fabric works. @@ -138,8 +130,6 @@ In the previous section, you deployed NGINX Gateway Fabric to a local cluster. T The YAML code in the following sections can be found in the [cafe-example folder](https://github.com/nginx/nginx-gateway-fabric/tree/main/examples/cafe-example) of the GitHub repository. {{< /note >}} ---- - ### Create the application resources Create the file _cafe.yaml_ with the following contents: @@ -171,8 +161,6 @@ coffee-676c9f8944-k2bmd 1/1 Running 0 9s tea-6fbfdcb95d-9lhbj 1/1 Running 0 9s ``` ---- - ### Create Gateway and HTTPRoute resources Create the file _gateway.yaml_ with the following contents: @@ -217,8 +205,6 @@ httproute.gateway.networking.k8s.io/coffee created httproute.gateway.networking.k8s.io/tea created ``` ---- - ### Verify the configuration You can check that all of the expected services are available using `kubectl get`: @@ -431,8 +417,6 @@ Status: Events: ``` ---- - ## Test NGINX Gateway Fabric By configuring the cluster with the port `31437`, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service. @@ -463,10 +447,8 @@ URI: /tea Request ID: 1b5c8f3a4532ea7d7510cf14ffeb27af ``` ---- - -## See also +## Next steps -- [Install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf/" >}}), for additional ways to install NGINX Gateway Fabric -- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster -- [Traffic management]({{< ref "/ngf/how-to/traffic-management/" >}}), for more in-depth traffic management configuration +- [Install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}), for additional ways to install NGINX Gateway Fabric +- [Traffic management]({{< ref "/ngf/traffic-management/" >}}), for more in-depth traffic management configuration +- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster \ No newline at end of file diff --git a/content/ngf/how-to/_index.md b/content/ngf/how-to/_index.md index 3d0b4588a..c6717f894 100644 --- a/content/ngf/how-to/_index.md +++ b/content/ngf/how-to/_index.md @@ -1,5 +1,5 @@ --- title: "How-to guides" url: /nginx-gateway-fabric/how-to/ -weight: 500 +weight: 550 --- diff --git a/content/ngf/how-to/control-plane-configuration.md b/content/ngf/how-to/control-plane-configuration.md index 15db1c714..c7ca856b4 100644 --- a/content/ngf/how-to/control-plane-configuration.md +++ b/content/ngf/how-to/control-plane-configuration.md @@ -13,7 +13,7 @@ Learn how to dynamically update the NGINX Gateway Fabric control plane configura NGINX Gateway Fabric can dynamically update the control plane configuration without restarting. The control plane configuration is stored in the NginxGateway custom resource, created during the installation of NGINX Gateway Fabric. -NginxGateway is deployed in the same namespace as the controller (Default: `nginx-gateway`). The resource's default name is based on your [installation method]({{< ref "/ngf/installation/installing-ngf" >}}): +NginxGateway is deployed in the same namespace as the controller (Default: `nginx-gateway`). The resource's default name is based on your [installation method]({{< ref "/ngf/install/" >}}): - Helm: `-config` - Manifests: `nginx-gateway-config` diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index ad70d1879..994a86faa 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -178,7 +178,9 @@ By default, an `NginxProxy` resource is created in the same namespace where NGIN When installed using the Helm chart, the NginxProxy resource is named `-proxy-config` and is created in the release Namespace. -{{< note >}} Some global configuration also requires an [associated policy]({{< ref "/ngf/overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}), for example). {{< /note >}} +**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).** + +{{< note >}} Some global configuration also requires an [associated policy]({{< ref "/ngf/overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< ref "/ngf/monitoring/tracing.md" >}}), for example). {{< /note >}} --- @@ -272,15 +274,14 @@ of a few arguments. {{}} ### Run NGINX Gateway Fabric with NGINX in debug mode -To run NGINX Gateway Fabric with NGINX in debug mode, follow the [installation document]({{< ref "/ngf/installation/installing-ngf" >}}) with these additional steps: - -Using Helm: Set `nginx.debug` to true. +To run NGINX Gateway Fabric with NGINX in debug mode, during [installation]({{< ref "/ngf/install/" >}}), follow these additional steps: -Using Kubernetes Manifests: In the deployment manifest, set the `spec.kubernetes.deployment.container.debug` field in the `NginxProxy` resource to true. +- **Helm**: Set _nginx.debug_ to _true_. +- **Manifests**: Set _spec.kubernetes.deployment.container.debug_ field in the _NginxProxy_ resource to _true_. -If you want to change the NGINX mode after deploying NGINX Gateway Fabric, you can do so through the `NginxProxy` `spec.kubernetes.deployment.container.debug` field. +To change NGINX mode **after** deploying NGINX Gateway Fabric, use the _NginxProxy_ _spec.kubernetes.deployment.container.debug_ field. -The following command creates a basic `NginxProxy` configuration that both sets the NGINX log level to `debug` and runs NGINX in `debug` mode. +The following command creates a basic _NginxProxy_ configuration that sets both the NGINX mode and log level to _debug_. ```yaml kubectl apply -f - <}} When modifying any `deployment` field in the `NginxProxy` resource, any corresponding NGINX instances will be restarted. {{< /note >}} +{{< note >}} When modifying any _deployment_ field in the _NginxProxy_ resource, any corresponding NGINX instances will be restarted. {{< /note >}} --- diff --git a/content/ngf/how-to/monitoring/_index.md b/content/ngf/how-to/monitoring/_index.md deleted file mode 100644 index 81673a4df..000000000 --- a/content/ngf/how-to/monitoring/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Monitoring and troubleshooting" -url: /nginx-gateway-fabric/how-to/monitoring/ -weight: 300 ---- diff --git a/content/ngf/how-to/monitoring/dashboard.md b/content/ngf/how-to/monitoring/dashboard.md deleted file mode 100644 index 8019aa8a8..000000000 --- a/content/ngf/how-to/monitoring/dashboard.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: NGINX Plus dashboard -weight: 300 -toc: true -type: how-to -product: NGF -docs: DOCS-1417 ---- - -Learn how to view the NGINX Plus dashboard to see real-time metrics. - ---- - -## Overview - -The NGINX Plus dashboard offers a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. The dashboard is enabled by default for NGINX Gateway Fabric deployments that use NGINX Plus as the data plane. The dashboard is available on port 8765. - -To access the dashboard: - -1. Use port-forwarding to forward connections to port 8765 on your local machine to port 8765 on the NGINX Plus pod (replace `` with the actual name of the pod). - - ```shell - kubectl port-forward 8765:8765 -n - ``` - -1. Open your browser to [http://127.0.0.1:8765/dashboard.html](http://127.0.0.1:8765/dashboard.html) to access the dashboard. - -The dashboard will look like this: - -{{< img src="/ngf/img/nginx-plus-dashboard.png" alt="">}} - -{{< note >}} The [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) used by the dashboard for metrics is also accessible using the `/api` path. {{< /note >}} - -### Configure dashboard access through NginxProxy - -To allow access to the NGINX Plus dashboard from different sources than the default `127.0.0.1`, we can use the NginxProxy resource -to allow access to other IP Addresses or CIDR blocks. - -The following NginxProxy configuration allows access to the NGINX Plus dashboard from the IP Addresses `192.0.2.8` and -`192.0.2.0` and the CIDR block `198.51.100.0/24`: - -```yaml -apiVersion: gateway.nginx.org/v1alpha1 -kind: NginxProxy -metadata: - name: ngf-proxy-config -spec: - nginxPlus: - allowedAddresses: - - type: IPAddress - value: 192.0.2.8 - - type: IPAddress - value: 192.0.2.0 - - type: CIDR - value: 198.51.100.0/24 -``` - -For more information on configuring the NginxProxy resource, visit our [data plane configuration]({{< ref "data-plane-configuration.md" >}}) document -which explains how to either configure an NginxProxy resource on installation, manually create an NginxProxy resource, or edit an existing NginxProxy resource. \ No newline at end of file diff --git a/content/ngf/how-to/traffic-management/_index.md b/content/ngf/how-to/traffic-management/_index.md deleted file mode 100644 index f94f827ce..000000000 --- a/content/ngf/how-to/traffic-management/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Traffic management" -url: /nginx-gateway-fabric/how-to/traffic-management/ -weight: 100 ---- diff --git a/content/ngf/how-to/traffic-security/_index.md b/content/ngf/how-to/traffic-security/_index.md deleted file mode 100644 index eaea647d8..000000000 --- a/content/ngf/how-to/traffic-security/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Traffic security" -url: /nginx-gateway-fabric/how-to/traffic-security -weight: 200 ---- \ No newline at end of file diff --git a/content/ngf/install/_index.md b/content/ngf/install/_index.md new file mode 100644 index 000000000..64db7a6ee --- /dev/null +++ b/content/ngf/install/_index.md @@ -0,0 +1,5 @@ +--- +title: "Install" +url: /nginx-gateway-fabric/install/ +weight: 300 +--- diff --git a/content/ngf/installation/building-the-images.md b/content/ngf/install/build-image.md similarity index 83% rename from content/ngf/installation/building-the-images.md rename to content/ngf/install/build-image.md index 5c81a28a1..7e229f4c1 100644 --- a/content/ngf/installation/building-the-images.md +++ b/content/ngf/install/build-image.md @@ -1,17 +1,15 @@ --- title: Build NGINX Gateway Fabric -weight: 500 +weight: 400 toc: true -type: how-to -product: NGF -docs: DOCS-1431 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1431 --- ## Overview -While most users will install NGINX Gateway Fabric [with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md" >}}) or [Kubernetes manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md" >}}), manually building the [NGINX Gateway Fabric and NGINX images]({{< ref "/ngf/overview/gateway-architecture.md#the-nginx-gateway-fabric-pod" >}}) can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images. - ---- +While most users will install NGINX Gateway Fabric [with Helm]({{< ref "/ngf/install/helm.md" >}}) or [Kubernetes manifests]({{< ref "/ngf/install/manifests.md" >}}), manually building the [NGINX Gateway Fabric and NGINX images]({{< ref "/ngf/overview/gateway-architecture.md#the-nginx-gateway-fabric-pod" >}}) can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images. ## Before you begin @@ -25,7 +23,6 @@ installed on your machine: If building the NGINX Plus image, you will also need a valid NGINX Plus license certificate (`nginx-repo.crt`) and key (`nginx-repo.key`) in the root of the repo. ---- ## Steps diff --git a/content/ngf/installation/installing-ngf/deploy-data-plane.md b/content/ngf/install/deploy-data-plane.md similarity index 95% rename from content/ngf/installation/installing-ngf/deploy-data-plane.md rename to content/ngf/install/deploy-data-plane.md index 92d04248b..114613026 100644 --- a/content/ngf/installation/installing-ngf/deploy-data-plane.md +++ b/content/ngf/install/deploy-data-plane.md @@ -1,10 +1,10 @@ --- title: Deploy a Gateway for data plane instances -weight: 500 +weight: 600 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- ## Overview @@ -19,7 +19,7 @@ A single GatewayClass can have multiple Gateways: each Gateway will create a sep ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Create a Gateway @@ -98,7 +98,7 @@ cafe-nginx LoadBalancer 10.96.125.117 80:30180/TCP 5m2s The Service type can be changed, as explained in the next section. -## How to modify provisioned NGINX instances +## Modify provisioned NGINX instances The NginxProxy custom resource can modify the provisioning of the Service object and NGINX deployment when a Gateway is created. @@ -180,7 +180,7 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE cafe-nginx NodePort 10.96.172.204 80:32615/TCP 3h5m ``` -### How to set annotations and labels on provisioned resources +### Set annotations and labels on provisioned resources While the majority of configuration will happen on the NginxProxy resource, that is not always the case. Uniquely, if you want to set any annotations or labels on the NGINX Deployment or Service, you need to set those annotations on the Gateway which @@ -236,7 +236,7 @@ Annotations: annotationKey: annotationValue For more guides on routing traffic to applications and more information on Data Plane configuration, check out the following resources: -- [Routing traffic to applications]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) -- [Application routes using HTTP matching conditions]({{< ref "/ngf/how-to/traffic-management/advanced-routing.md" >}}) +- [Routing traffic to applications]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) +- [Application routes using HTTP matching conditions]({{< ref "/ngf/traffic-management/advanced-routing.md" >}}) - [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) - [API reference]({{< ref "/ngf/reference/api.md" >}}) \ No newline at end of file diff --git a/content/ngf/installation/installing-ngf/helm.md b/content/ngf/install/helm.md similarity index 53% rename from content/ngf/installation/installing-ngf/helm.md rename to content/ngf/install/helm.md index 8e6fadaea..7c997fb3e 100644 --- a/content/ngf/installation/installing-ngf/helm.md +++ b/content/ngf/install/helm.md @@ -1,25 +1,24 @@ --- -title: Installation with Helm -weight: 100 +title: Install NGINX Gateway Fabric with Helm +weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-1430 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1430 --- ## Overview Learn how to install, upgrade, and uninstall NGINX Gateway Fabric in a Kubernetes cluster using Helm. ---- ## Before you begin -To complete this guide, you'll need to install: +To complete this guide, you will need: - [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line tool for managing Kubernetes clusters. - [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes. -- If deploying into a production environment, we highly recommend [installing custom certificates]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}) for securing the connection between the NGINX Gateway Fabric control plane and NGINX data plane Pods. **This should be done _before_ you install NGINX Gateway Fabric.** The default certificates are self-signed and will expire after 3 years. +- [Add certificates for secure authentication]({{< ref "/ngf/install/secure-certificates.md" >}}) in a production environment. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} @@ -40,19 +39,16 @@ To complete this guide, you'll need to install: {{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}} -{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/installation/nginx-plus-jwt.md" >}}) document. {{< /note >}} +{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/install/nginx-plus.md" >}}) document. {{< /note >}} ---- - ## Deploy NGINX Gateway Fabric ### Installing the Gateway API resources {{< include "/ngf/installation/install-gateway-api-resources.md" >}} ---- ### Install from the OCI registry @@ -94,8 +90,6 @@ To wait for the Deployment to be ready, you can either add the `--wait` flag to 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. @@ -136,8 +130,6 @@ To wait for the Deployment to be ready, you can either add the `--wait` flag to kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available ``` ---- - ### Custom installation options #### Service type @@ -150,8 +142,6 @@ To use a NodePort Service instead: helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginx.service.type=NodePort ``` ---- - #### Experimental features We support a subset of the additional features provided by the Gateway API experimental channel. To enable the @@ -163,161 +153,15 @@ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namesp {{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}} ---- #### Examples You can find several examples of configuration options of the `values.yaml` file in the [helm examples](https://github.com/nginx/nginx-gateway-fabric/tree/v{{< version-ngf >}}/examples/helm) directory. ---- - ### Access NGINX Gateway Fabric {{< include "/ngf/installation/expose-nginx-gateway-fabric.md" >}} ---- - -## Upgrade NGINX Gateway Fabric - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=` when running `helm upgrade`. {{< /important >}} - -{{< tip >}} For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below. {{< /tip >}} - -{{< note >}} To upgrade from version 1.x to 2.x, please refer to this [guide]({{< ref "/ngf/upgrading-ngf.md" >}}). {{< /note >}} - -To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps: - ---- - -### Upgrade Gateway resources - -{{< include "/ngf/installation/upgrade-api-resources.md" >}} - ---- - -### Upgrade NGINX Gateway Fabric CRDs - -Helm's upgrade process does not automatically upgrade the NGINX Gateway Fabric CRDs (Custom Resource Definitions). - -To upgrade the CRDs, take the following steps: - -1. {{< include "/ngf/installation/helm/pulling-the-chart.md" >}} - -2. Upgrade the CRDs: - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml - ``` - - {{}}Ignore the following warning, as it is expected.{{}} - - ```text - Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply. - ``` - ---- - -### Upgrade NGINX Gateway Fabric release - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=` when running `helm upgrade`. {{< /important >}} - -There are two possible ways to upgrade NGINX Gateway Fabric. You can either upgrade from the OCI registry, or download the chart and upgrade from the source. - ---- - -#### Upgrade from the OCI registry - -To upgrade to the latest stable release of NGINX Gateway Fabric, run: - -```shell -helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric -n nginx-gateway -``` - -If needed, replace `ngf` with your chosen release name. - ---- - -#### Upgrade from sources - -{{< include "/ngf/installation/helm/pulling-the-chart.md" >}} - -To upgrade, run: the following command: - -```shell -helm upgrade ngf . -n nginx-gateway -``` - -If needed, replace `ngf` with your chosen release name. - ---- - -## How to upgrade from NGINX OSS to NGINX Plus - -To upgrade from NGINX OSS to NGINX Plus, update the Helm command to include the necessary values for 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.{{< /note >}} - -{{< important >}} Ensure that you [Create the required JWT Secrets]({{< ref "/ngf/installation/nginx-plus-jwt.md" >}}) before installing.{{< /important >}} - -```shell -helm upgrade 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 -``` - -If needed, replace `ngf` with your chosen release name. - ---- - -## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} - -{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}} - -Follow these steps to configure delayed pod termination: - -1. Open the `values.yaml` for editing. - -1. **Add delayed shutdown hooks**: - - - In the `values.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment. - - ```yaml - nginxGateway: - <...> - lifecycle: - preStop: - exec: - command: - - /usr/bin/gateway - - sleep - - --duration=40s # This flag is optional, the default is 30s - - nginx: - <...> - lifecycle: - preStop: - exec: - command: - - /bin/sleep - - "40" - ``` - -1. **Set the termination grace period**: - - - {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md">}} - -1. Save the changes. - -{{}} -For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation: - -- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) -- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination) - -{{}} - ---- - ## Uninstall NGINX Gateway Fabric Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster: @@ -345,8 +189,9 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K - {{< include "/ngf/installation/uninstall-gateway-api-resources.md" >}} ---- +## Next steps -## Additional configuration +- [Deploy a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}) +- [Routing traffic to applications]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) For a full list of the Helm Chart configuration parameters, read [the NGINX Gateway Fabric Helm Chart](https://github.com/nginx/nginx-gateway-fabric/blob/v{{< version-ngf >}}/charts/nginx-gateway-fabric/README.md#configuration). diff --git a/content/ngf/installation/installing-ngf/manifests.md b/content/ngf/install/manifests.md similarity index 64% rename from content/ngf/installation/installing-ngf/manifests.md rename to content/ngf/install/manifests.md index e62c38d16..59ca928b5 100644 --- a/content/ngf/installation/installing-ngf/manifests.md +++ b/content/ngf/install/manifests.md @@ -1,24 +1,22 @@ --- -title: Installation with Manifests +title: Install NGINX Gateway Fabric with Manifests weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-1429 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1429 --- ## Overview Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernetes manifests. ---- - ## Before you begin To complete this guide, you'll need to install: - [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters. -- If deploying into a production environment, we highly recommend [installing custom certificates]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}) for securing the connection between the NGINX Gateway Fabric control plane and NGINX data plane Pods. **This should be done _before_ you install NGINX Gateway Fabric.** The default certificates are self-signed and will expire after 3 years. +- [Add certificates for secure authentication]({{< ref "/ngf/install/secure-certificates.md" >}}) in a production environment. {{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} @@ -39,24 +37,18 @@ To complete this guide, you'll need to install: {{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}} -{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/installation/nginx-plus-jwt.md" >}}) document. {{< /note >}} +{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< ref "/ngf/install/nginx-plus.md" >}}) document. {{< /note >}} ---- - ## 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. ---- - ### Install the Gateway API resources {{< include "/ngf/installation/install-gateway-api-resources.md" >}} ---- - ### Deploy the NGINX Gateway Fabric CRDs #### Stable release @@ -71,8 +63,6 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml ``` ---- - ### 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. {{< /note >}} @@ -179,8 +169,6 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{ {{}} ---- - ### Verify the Deployment To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace: @@ -196,94 +184,10 @@ NAME READY STATUS RESTARTS AGE nginx-gateway-5d4f4c7db7-xk2kq 1/1 Running 0 112s ``` ---- - ### Access NGINX Gateway Fabric {{< include "/ngf/installation/expose-nginx-gateway-fabric.md" >}} ---- - -## Upgrade NGINX Gateway Fabric - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret, which is referenced in the updated deployment manifest for the newest version. {{< /important >}} - -{{< tip >}} For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section. {{}} - -{{< note >}} To upgrade from version 1.x to 2.x, please refer to this [guide]({{< ref "/ngf/upgrading-ngf.md" >}}). {{< /note >}} - -To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps: - -### Upgrade Gateway API resources - -{{< include "/ngf/installation/upgrade-api-resources.md" >}} - -### Upgrade NGINX Gateway Fabric CRDs - -To upgrade the Custom Resource Definitions (CRDs), run: - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml -``` - -### Upgrade NGINX Gateway Fabric deployment - -Select the deployment manifest that matches your current deployment from the table above in the [Deploy NGINX Gateway Fabric](#deploy-nginx-gateway-fabric) section and apply it. - ---- - -## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} - -{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}} - -Follow these steps to configure delayed pod termination: - -1. Open the `deploy.yaml` for editing. - -1. **Add delayed shutdown hooks**: - - - In the `deploy.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment. - - ```yaml - <...> - 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" - <...> - ``` - -1. **Set the termination grace period**: - - - {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md" >}} - -1. 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: - -- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) -- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination) - -{{< /see-also >}} - ---- - ## Uninstall NGINX Gateway Fabric Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster: @@ -305,3 +209,8 @@ Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your K 1. **Remove the Gateway API resources:** - {{< include "/ngf/installation/uninstall-gateway-api-resources.md" >}} + +## Next steps + +- [Deploy a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}) +- [Routing traffic to applications]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) \ No newline at end of file diff --git a/content/ngf/installation/nginx-plus-jwt.md b/content/ngf/install/nginx-plus.md similarity index 92% rename from content/ngf/installation/nginx-plus-jwt.md rename to content/ngf/install/nginx-plus.md index b1422fd3c..4c7eb0e17 100644 --- a/content/ngf/installation/nginx-plus-jwt.md +++ b/content/ngf/install/nginx-plus.md @@ -1,10 +1,10 @@ --- -title: NGINX Plus and JWT +title: Install NGINX Gateway Fabric with NGINX Plus weight: 300 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- ## Overview @@ -13,26 +13,20 @@ NGINX Gateway Fabric with NGINX Plus requires a valid JSON Web Token (JWT) to do This requirement is part of F5’s broader licensing program and aligns with industry best practices. The JWT will streamline subscription renewals and usage reporting, helping you manage your NGINX Plus subscription more efficiently. The [telemetry](#telemetry) data we collect helps us improve our products and services to better meet your needs. -The JWT is required for validating your subscription and reporting telemetry data. For environments connected to the internet, telemetry is automatically sent to F5’s licensing endpoint. In offline environments, telemetry is routed through [NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/). Usage is reported every hour and on startup whenever NGINX is reloaded. +The JWT is required for validating your subscription and reporting telemetry data. For environments connected to the internet, telemetry is automatically sent to F5’s licensing endpoint. In offline environments, telemetry is routed through [NGINX Instance Manager]({{< ref "/nim/" >}}). Usage is reported every hour and on startup whenever NGINX is reloaded. {{< note >}} The following Secrets should be created in the same namespace as the NGINX Gateway Fabric control plane (default: nginx-gateway). The control plane will copy these Secrets into any namespaces where NGINX gets deployed. If you need to update the Secrets, update the originals that you created in the control plane namespace, and the control plane will propagate those updates to all duplicated Secrets. {{< /note >}} ---- - ## Set up the JWT The JWT needs to be configured before deploying NGINX Gateway Fabric. The JWT will be stored in two Kubernetes Secrets: one for downloading the NGINX Plus container image, and the other for running NGINX Plus. {{< include "/ngf/installation/jwt-password-note.md" >}} ---- - ### Download the JWT from MyF5 {{< include "/ngf/installation/nginx-plus/download-jwt.md" >}} ---- - ### Docker Registry Secret {{< include "/ngf/installation/nginx-plus/docker-registry-secret.md" >}} @@ -55,8 +49,6 @@ Specify the Secret name in the `nginx-docker-secret` command-line argument of th {{}} ---- - ### NGINX Plus Secret {{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}} @@ -79,9 +71,7 @@ Specify the Secret name in the `--usage-report-secret` command-line flag on the {{}} -{{< note >}} If you are reporting to the default licensing endpoint, then you can now proceed with [installing NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}). Otherwise, follow the steps below to configure reporting to NGINX Instance Manager. {{< /note >}} - ---- +{{< note >}} If you are reporting to the default licensing endpoint, then you can now proceed with [installing NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}). Otherwise, follow the steps below to configure reporting to NGINX Instance Manager. {{< /note >}} ### Reporting to NGINX Instance Manager {#nim} @@ -105,8 +95,6 @@ Specify the endpoint in the `--usage-report-endpoint` command-line flag on the ` {{}} ---- - #### CA and Client certificate/key {#nim-cert} To configure a CA cert and/or client certificate and key, a few extra steps are needed. @@ -141,9 +129,7 @@ Specify the CA Secret name in the `--usage-report-ca-secret` command-line flag o
-{{< note >}} Once these Secrets are created and configuration options are set, you can now [install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}). {{< /note >}} - ---- +{{< note >}} Once these Secrets are created and configuration options are set, you can now [install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}). {{< /note >}} ## Installation flags to configure usage reporting {#flags} @@ -167,8 +153,6 @@ If using manifests, the following command-line options should be set as necessar - `--usage-report-ca-secret` is the name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). - `--usage-report-client-ssl-secret` is the name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). ---- - ## What’s reported and how it’s protected {#telemetry} NGINX Plus reports the following data every hour by default: @@ -184,8 +168,6 @@ NGINX Plus reports the following data every hour by default: - **Usage report timestamps**: Start and end times for each usage report. - **Kubernetes node details**: Information about Kubernetes nodes. ---- - ### Security and privacy of reported data All communication between your NGINX Plus instances, NGINX Instance Manager, and F5’s licensing endpoint (`product.connect.nginx.com`) is protected using **SSL/TLS** encryption. @@ -210,10 +192,13 @@ docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:{{< versi Once you have successfully pulled the image, you can tag it as needed, then push it to a different container registry. ---- - ## Alternative installation options There are alternative ways to get an NGINX Plus image for NGINX Gateway Fabric: -- [Build the Gateway Fabric image]({{< ref "/ngf/installation/building-the-images.md">}}) describes how to use the source code with an NGINX Plus subscription certificate and key to build an image. +- [Build the Gateway Fabric image]({{< ref "/ngf/install/build-image.md">}}) describes how to use the source code with an NGINX Plus subscription certificate and key to build an image. + +## Next steps + +- [Deploy a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}) +- [Routing traffic to applications]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) \ No newline at end of file diff --git a/content/ngf/installation/installing-ngf/control-plane-certs.md b/content/ngf/install/secure-certificates.md similarity index 83% rename from content/ngf/installation/installing-ngf/control-plane-certs.md rename to content/ngf/install/secure-certificates.md index 763405e94..01283eabf 100644 --- a/content/ngf/installation/installing-ngf/control-plane-certs.md +++ b/content/ngf/install/secure-certificates.md @@ -1,23 +1,28 @@ --- -title: Add secure authentication to the control and data planes -weight: 300 +title: Add certificates for secure authentication +weight: 100 toc: true -type: how-to -product: NGF -docs: DOCS-0000 +nd-content-type: how-to +nd-product: NGF --- -## Overview +By default, NGINX Gateway Fabric installs self-signed certificates to secure the connection between the NGINX Gateway Fabric control plane and the NGINX data plane pods. These certificates are created by a `cert-generator` job when NGINX Gateway Fabric is first installed. -By default, NGINX Gateway Fabric installs self-signed certificates to secure the connection between the NGINX Gateway Fabric control plane and the NGINX data plane pods. These certificates are created by a `cert-generator` job when NGINX Gateway Fabric is first installed. However, because these certificates are self-signed and will expire after 3 years, it is recommended to use a solution such as [cert-manager](https://cert-manager.io) to create and manage these certificates in a production environment. +However, because these certificates are self-signed and will expire after 3 years, we recommend a solution such as [cert-manager](https://cert-manager.io) to create and manage these certificates in a production environment. -This guide will step through how to install and use `cert-manager` to secure this connection. **This should be done _before_ you install NGINX Gateway Fabric.** +This guide will step through how to install and use `cert-manager` to secure this connection. + +{{< caution >}} + +These steps should be completed before you install NGINX Gateway Fabric. + +{{< /caution >}} --- ## Before you begin -You need: +To complete this guide, you will need the following prerequisites: - Administrator access to a Kubernetes cluster. - [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally. @@ -44,7 +49,7 @@ helm install \ --set crds.enabled=true ``` -This also enables Gateway API features for cert-manager, which can be useful for [securing your workload traffic]({{< ref "/ngf/how-to/traffic-security/integrating-cert-manager.md" >}}). +This also enables Gateway API features for cert-manager, which can be useful for [securing your workload traffic]({{< ref "/ngf/traffic-security/integrate-cert-manager.md" >}}). ## Create the CA issuer @@ -180,7 +185,7 @@ Specify the Secret name using the `agent-tls-secret` command-line argument. {{}} -## Final steps +## Confirm the Secrets have been created You should see the Secrets created in the `nginx-gateway` namespace: @@ -194,4 +199,10 @@ nginx-gateway-ca kubernetes.io/tls 3 15s server-tls kubernetes.io/tls 3 8s ``` -**You can now [install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}).** +You can now [install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}). + +## Next steps + +- [Install NGINX Gateway Fabric with Helm]({{< ref "/ngf/install/helm.md" >}}) +- [Install NGINX Gateway Fabric with Manifests]({{< ref "/ngf/install/manifests.md" >}}) +- [Install NGINX Gateway Fabric with NGINX Plus]({{< ref "/ngf/install/nginx-plus.md" >}}) diff --git a/content/ngf/install/upgrade-version.md b/content/ngf/install/upgrade-version.md new file mode 100644 index 000000000..0096285f1 --- /dev/null +++ b/content/ngf/install/upgrade-version.md @@ -0,0 +1,308 @@ +--- +title: Upgrade NGINX Gateway Fabric +weight: 700 +toc: true +type: how-to +product: NGF +docs: DOCS-0000 +--- + +This document describes how to upgrade NGINX Gateway Fabric when a new version releases. + +It covers the necessary steps for minor versions as well as major versions (such as 1.x to 2.x). + +Many of the nuances in upgrade paths relate to how custom resource definitions (CRDs) are managed. + +{{< tip >}} + +To avoid interruptions, review the [Delay pod termination for zero downtime upgrades](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section. + +{{< /tip >}} + + +## Minor NGINX Gateway Fabric upgrades + +{{< important >}} NGINX Plus users need a JWT secret before upgrading from version 1.4.0 to 1.5.x. + +Follow the steps in [Set up the JWT]({{< ref "/ngf/install/nginx-plus.md#set-up-the-jwt" >}}) to create the Secret. + +{{< /important >}} + + +### Upgrade Gateway resources + +To upgrade your Gateway API resources, take the following steps: + +- Use [Technical specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) to verify your Gateway API resources are compatible with your NGINX Gateway Fabric version. +- Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information. + +To upgrade the Gateway API resources, run the following command: + +```shell +kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v{{< version-ngf >}}" | kubectl apply -f - +``` + +If you installed NGINX Gateway from the experimental channel, use this instead: + +```shell +kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v{{< version-ngf >}}" | kubectl apply -f - +``` + +### Upgrade NGINX Gateway Fabric CRDs + +Run the following command to upgrade the CRDs: + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml +``` + +{{< note >}} + +Ignore the following warning, as it is expected. + +```text +Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply. +``` + +{{< /note >}} + +### Upgrade NGINX Gateway Fabric release + +{{< tabs name="upgrade-release" >}} + +{{% tab name="Helm" %}} + +{{< important >}} If you are using NGINX Plus and have a different Secret name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=` when running `helm upgrade`. {{< /important >}} + +To upgrade the release with Helm, you can use the OCI registry, or download the chart and upgrade from the source. + +If needed, replace `ngf` with your chosen release name. + +**Upgrade from the OCI registry** + +```shell +helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric -n nginx-gateway +``` + +**Upgrade from sources** + +{{< include "/ngf/installation/helm/pulling-the-chart.md" >}} + +To upgrade, run the following command: + +```shell +helm upgrade ngf . -n nginx-gateway +``` + +{{% /tab %}} + +{{% tab name="Manifests" %}} + +Select the deployment manifest that matches your current deployment from options available in the [Deploy NGINX Gateway Fabric]({{< ref "/ngf/install/manifests.md#deploy-nginx-gateway-fabric-1">}}) section and apply it. + +{{% /tab %}} + +{{< /tabs>}} + +## Upgrade from v1.x to v2.x + +This section provides step-by-step instructions for upgrading NGINX Gateway Fabric from version 1.x to 2.x, highlighting key architectural changes, expected downtime, and important considerations for CRDs. + +To upgrade NGINX Gateway Fabric from version 1.x to the new architecture in version 2.x, you must uninstall the existing NGINX Gateway Fabric CRDs and deployment, and perform a fresh installation. This will cause brief downtime during the upgrade process. + +{{}} You do not need to uninstall the Gateway API CRDs during the upgrade. These resources are compatible with the new NGINX Gateway Fabric version. {{}} + +### Uninstall NGINX Gateway Fabric v1.x + +To remove the previous version 1.x of NGINX Gateway Fabric, follow these steps: + +First, run the following command to uninstall NGINX Gateway Fabric from the `nginx-gateway` namespace, and update `ngf` to your release name if it is different: + +```shell +helm uninstall ngf -n nginx-gateway +``` + +Afterwards, remove CRDs associated with NGINX Gateway Fabric version 1.x with the following command: + +```shell +kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.2/deploy/crds.yaml +``` + +### Install NGINX Gateway Fabric 2.x + +{{< important >}} + +Before installing 2.x, we recommend following [Add certificates for secure authentication]({{< ref "/ngf/install/secure-certificates.md" >}}). + +By default, NGINX Gateway Fabric installs self-signed certificates, which may be unsuitable for a production environment. + +{{< /important >}} + +{{}} + +{{%tab name="Helm"%}} + +Use the following `helm install` command to install the latest stable NGINX Gateway Fabric release in the `nginx-gateway` namespace. It will also install the CRDs required for the deployment: + +```shell +helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway +``` + +For customization options during the Helm installation process, view the [Install NGINX Gateway Fabric with Helm]({{< ref "/ngf/install/helm.md" >}}) topic. + +{{% /tab %}} + +{{%tab name="Manifests"%}} + +Apply the new CRDs with the following command: + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml +``` + +Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command: + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml +``` + +For customization options during the Manifest installation process, view the [Install NGINX Gateway Fabric with Manifests]({{< ref "/ngf/install/manifests.md" >}}) topic. + +{{% /tab %}} + +{{}} + +### Architecture changes + +With this release, NGINX Gateway Fabric adopts a new architecture that separates the control plane and data plane into independent deployments. This separation improves scalability, security, and operational clarity. + +The control plane is a Kubernetes controller that watches Gateway API and Kubernetes resources (e.g., Services, Endpoints, Secrets) and dynamically provisions NGINX data plane deployments for each Gateway. + +NGINX configurations are generated by the control plane and securely delivered to the data planes via gRPC, using the NGINX Agent. TLS is enabled by default, with optional integration with `cert-manager`. + +Each data plane pod runs NGINX alongside the Agent, which applies config updates and handles reloads without shared volumes or signals. This design ensures dynamic, per-Gateway traffic management and operational isolation. + +New fields have been added to the `NginxProxy` resource to configure infrastructure-related settings for data plane deployments. The `NginxProxy` resource is now a namespaced-scoped resource, instead of a cluster-scoped resource, and can be modified at either the Gateway or GatewayClass level. These new fields provide the flexibility to customize deployment and service configurations. + +For detailed instructions on how to modify these settings, refer to the [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}) guide. + +### Key links for the version 2.x update + +- To read more on [modifying data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}). +- To learn more about [deploying a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}). +- To adding secure [authentication to control plane and data planes]({{< ref "/ngf/install/secure-certificates.md" >}}). +- To read more about [architecture changes]({{< ref "/ngf/overview/gateway-architecture.md" >}}). +- For detailed [API reference]({{< ref "/ngf/reference/api.md" >}}). + +## Access NGINX Gateway Fabric 1.x documentation + +The documentation website is intended for the latest version of NGINX Gateway Fabric. + +To review documentation prior to 2.x, check out the desired release branch (Such as _release-1.6_): + +```shell +git clone git@github.com:nginx/nginx-gateway-fabric.git +git checkout release-1.6 +``` + +To review the documentation in a local webserver, run _make watch_ in the _/site_ folder: + +```shell +cd site +make watch +``` +```text +Hugo is available and has a version greater than 133. Proceeding with build. +hugo --bind 0.0.0.0 -p 1313 server --disableFastRender +Watching for changes in /home//nginx-gateway-fabric/site/{content,layouts,static} +Watching for config changes in /home//nginx-gateway-fabric/site/config/_default, /home//nginx-gateway-fabric/site/config/development, /home//nginx-gateway-fabric/site/go.mod +Start building sites … +hugo v0.135.0-f30603c47f5205e30ef83c70419f57d7eb7175ab linux/amd64 BuildDate=2024-09-27T13:17:08Z VendorInfo=gohugoio + + + | EN +-------------------+------ + Pages | 72 + Paginator pages | 0 + Non-page files | 0 + Static files | 176 + Processed images | 0 + Aliases | 9 + Cleaned | 0 + +Built in 213 ms +Environment: "development" +Serving pages from disk +Web Server is available +``` + +You can then follow [this localhost link](http://localhost:1313/nginx-gateway-fabric/) for 1.x NGINX Gateway Fabric documentation. + +## Upgrade from NGINX Open Source to NGINX Plus + +{{< important >}} + +Ensure that you [Set up the JWT]({{< ref "/ngf/install/nginx-plus.md#set-up-the-jwt" >}}) before upgrading. These instructions only apply to Helm. + +{{< /important >}} + +To upgrade from NGINX Open Source to NGINX Plus, update the Helm command to include the necessary values for Plus: + +{{< note >}} If applicable: + +- Replace the F5 Container registry `private-registry.nginx.com` with your internal registry for your NGINX Plus image +- Replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials +- Replace `ngf` with your chosen release name. +{{< /note >}} + + +```shell +helm upgrade 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 +``` + +## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} + +{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}} + +Follow these steps to configure delayed pod termination: + +1. Open the `values.yaml` for editing. + +1. **Add delayed shutdown hooks**: + + - In the `values.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment. + + ```yaml + nginxGateway: + <...> + lifecycle: + preStop: + exec: + command: + - /usr/bin/gateway + - sleep + - --duration=40s # This flag is optional, the default is 30s + + nginx: + <...> + lifecycle: + preStop: + exec: + command: + - /bin/sleep + - "40" + ``` + +1. **Set the termination grace period**: + + - {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md">}} + +1. Save the changes. + +{{}} +For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation: + +- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) +- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination) + +{{}} \ No newline at end of file diff --git a/content/ngf/installation/_index.md b/content/ngf/installation/_index.md deleted file mode 100644 index b49ab026b..000000000 --- a/content/ngf/installation/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Installation" -url: /nginx-gateway-fabric/installation/ -weight: 300 ---- diff --git a/content/ngf/installation/installing-ngf/_index.md b/content/ngf/installation/installing-ngf/_index.md deleted file mode 100644 index 814e9ae02..000000000 --- a/content/ngf/installation/installing-ngf/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Install NGINX Gateway Fabric" -url: /nginx-gateway-fabric/installation/installing-ngf/ -weight: 100 ---- diff --git a/content/ngf/monitoring/_index.md b/content/ngf/monitoring/_index.md new file mode 100644 index 000000000..8f7bfadcc --- /dev/null +++ b/content/ngf/monitoring/_index.md @@ -0,0 +1,5 @@ +--- +title: "Monitoring" +url: /nginx-gateway-fabric/monitoring/ +weight: 600 +--- diff --git a/content/ngf/monitoring/dashboard.md b/content/ngf/monitoring/dashboard.md new file mode 100644 index 000000000..56cfc31d2 --- /dev/null +++ b/content/ngf/monitoring/dashboard.md @@ -0,0 +1,55 @@ +--- +title: Access the NGINX Plus dashboard +weight: 300 +toc: true +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1417 +--- + +This topic describes how to view the NGINX Plus dashboard to see real-time metrics. + +The NGINX Plus dashboard offers a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. + +The dashboard is enabled by default for NGINX Gateway Fabric deployments that use NGINX Plus as the data plane, and is available on port 8765. + +## Connect to the dashboard + +To access the dashboard, you will first need to forward connections to port 8765 on your local machine to port 8765 on the NGINX Plus pod (replace `` with the actual name of the pod). + +```shell +kubectl port-forward 8765:8765 -n +``` + +Afterwards, use a browser to access [http://127.0.0.1:8765/dashboard.html](http://127.0.0.1:8765/dashboard.html) to view the dashboard. + +The dashboard will look like this: + +{{< img src="/ngf/img/nginx-plus-dashboard.png" alt="">}} + +{{< note >}} The [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) used by the dashboard for metrics is also accessible using the `/api` path. {{< /note >}} + +### Configure dashboard access through NginxProxy + +To access the NGINX Plus dashboard from sources than the default `127.0.0.1`, you can use the NginxProxy resource to allow access to other IP Addresses or CIDR blocks. + +The following example configuration allows access to the NGINX Plus dashboard from the IP Addresses `192.0.2.8` and +`192.0.2.0` and the CIDR block `198.51.100.0/24`: + +```yaml +apiVersion: gateway.nginx.org/v1alpha1 +kind: NginxProxy +metadata: + name: ngf-proxy-config +spec: + nginxPlus: + allowedAddresses: + - type: IPAddress + value: 192.0.2.8 + - type: IPAddress + value: 192.0.2.0 + - type: CIDR + value: 198.51.100.0/24 +``` + +For more information on configuring the NginxProxy resource, visit the [data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) document. \ No newline at end of file diff --git a/content/ngf/how-to/monitoring/prometheus.md b/content/ngf/monitoring/prometheus.md similarity index 99% rename from content/ngf/how-to/monitoring/prometheus.md rename to content/ngf/monitoring/prometheus.md index 9be5bd3e6..369789dcd 100644 --- a/content/ngf/how-to/monitoring/prometheus.md +++ b/content/ngf/monitoring/prometheus.md @@ -2,24 +2,22 @@ title: Monitoring with Prometheus and Grafana weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-1418 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1418 --- This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available. ---- - ## Overview NGINX Gateway Fabric metrics are displayed in [Prometheus](https://prometheus.io/) format. These metrics are served through a metrics server orchestrated by the controller-runtime package on HTTP port `9113`. When installed, Prometheus automatically scrapes this port and collects metrics. [Grafana](https://grafana.com/) can be used for rich visualization of these metrics. {{< call-out "important" "Security note for metrics" >}} + Metrics are served over HTTP by default. Enabling HTTPS will secure the metrics endpoint with a self-signed certificate. When using HTTPS, adjust the Prometheus Pod scrape settings by adding the `insecure_skip_verify` flag to handle the self-signed certificate. For further details, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#tls_config). -{{< /call-out >}} ---- +{{< /call-out >}} ## Installing Prometheus and Grafana @@ -41,8 +39,6 @@ kubectl port-forward -n monitoring svc/prometheus-server 9090:80 & Visit [http://127.0.0.1:9090](http://127.0.0.1:9090) to view the dashboard. ---- - ### Grafana ```shell @@ -65,8 +61,6 @@ The username for login is `admin`. The password can be acquired by running: kubectl get secret -n monitoring grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo ``` ---- - #### Configuring Grafana In the Grafana UI menu, go to `Connections` then `Data sources`. Add your Prometheus service (`http://prometheus-server.monitoring.svc`) as a data source. @@ -75,8 +69,6 @@ Download the following sample dashboard and Import as a new Dashboard in the Gra - {{< download "ngf/grafana-dashboard.json" "ngf-grafana-dashboard.json" >}} ---- - ## Available metrics in NGINX Gateway Fabric NGINX Gateway Fabric provides a variety of metrics for monitoring and analyzing performance. These metrics are categorized as follows: @@ -126,8 +118,6 @@ In addition to the previous metrics provided by NGINX Open Source, NGINX Plus in - `nginx_ssl_certificate_verify_failures_certificates_total`: The total number of SSL certificate verification failures. - `nginx_ssl_handshakes_total`: The total number of SSL handshakes. ---- - ### NGINX Gateway Fabric metrics Metrics specific to NGINX Gateway Fabric include: @@ -136,8 +126,6 @@ Metrics specific to NGINX Gateway Fabric include: All these metrics are under the `nginx_gateway_fabric` namespace and include a `class` label set to the GatewayClass of NGINX Gateway Fabric. For example, `nginx_gateway_fabric_event_batch_processing_milliseconds_sum{class="nginx"}`. ---- - ### Controller-runtime metrics Provided by the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) library, these metrics include: @@ -146,8 +134,6 @@ Provided by the [controller-runtime](https://github.com/kubernetes-sigs/controll - Go runtime metrics such as the number of Go routines, garbage collection duration, and Go version. - Controller-specific metrics, including reconciliation errors per controller, length of the reconcile queue, and reconciliation latency. ---- - ## Change the default metrics configuration You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Manifests. @@ -156,14 +142,10 @@ You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Mani If you're setting up NGINX Gateway Fabric with Helm, you can adjust the `metrics.*` parameters to fit your needs. For detailed options and instructions, see the [Helm README](https://github.com/nginx/nginx-gateway-fabric/blob/v{{< version-ngf >}}/charts/nginx-gateway-fabric/README.md). ---- - ### Using Kubernetes manifests For setups using Kubernetes manifests, change the metrics configuration by editing the NGINX Gateway Fabric manifest that you want to deploy. You can find some examples in the [deploy](https://github.com/nginx/nginx-gateway-fabric/tree/v{{< version-ngf >}}/deploy) directory. ---- - #### Disabling metrics If you need to disable metrics: @@ -205,8 +187,6 @@ To change the default port for metrics: <...> ``` ---- - #### Enabling HTTPS for metrics For enhanced security with HTTPS: diff --git a/content/ngf/how-to/monitoring/tracing.md b/content/ngf/monitoring/tracing.md similarity index 97% rename from content/ngf/how-to/monitoring/tracing.md rename to content/ngf/monitoring/tracing.md index 90718ade0..fe241cad5 100644 --- a/content/ngf/how-to/monitoring/tracing.md +++ b/content/ngf/monitoring/tracing.md @@ -2,15 +2,13 @@ title: Configure tracing weight: 100 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- This guide explains how to enable tracing on HTTPRoutes in NGINX Gateway Fabric using the OpenTelemetry Collector. Jaeger is used to process and collect the traces. ---- - ## Overview NGINX Gateway Fabric supports tracing using [OpenTelemetry](https://opentelemetry.io/). @@ -19,8 +17,6 @@ The official [NGINX OpenTelemetry Module](https://github.com/nginxinc/nginx-otel This collector can then export data to one or more upstream collectors like [Jaeger](https://www.jaegertracing.io/), [DataDog](https://docs.datadoghq.com/tracing/), and many others. This is called the [Agent model](https://opentelemetry.io/docs/collector/deployment/agent/). ---- - ## Install the collectors The first step is to install the collectors. NGINX Gateway Fabric will be configured to export to the OpenTelemetry Collector, which is configured to export to Jaeger. This model allows the visualization collector (Jaeger) to be swapped with something else, or to add more collectors without needing to reconfigure NGINX Gateway Fabric. It is also possible to configure NGINX Gateway Fabric to export directly to Jaeger. @@ -64,8 +60,6 @@ kubectl port-forward -n tracing svc/jaeger 16686:16686 & Visit [http://127.0.0.1:16686](http://127.0.0.1:16686) to view the dashboard. ---- - ## Enable tracing To enable tracing, you must configure two resources: @@ -82,11 +76,9 @@ When installed using the Helm chart, the NginxProxy resource is named `}}). ---- - ### Install NGINX Gateway Fabric with global tracing configuration -{{< note >}}Ensure that you [install the Gateway API resources]({{< ref "/ngf/installation/installing-ngf/helm.md#installing-the-gateway-api-resources" >}}).{{< /note >}} +{{< note >}} Ensure that you [install the Gateway API resources]({{< ref "/ngf/install/helm.md#installing-the-gateway-api-resources" >}}).{{< /note >}} Referencing the previously deployed collector, create the following `values.yaml` file for installing NGINX Gateway Fabric: @@ -176,8 +168,6 @@ kubectl edit nginxproxies.gateway.nginx.org ngf-proxy-config -n nginx-gateway You can now create the application, route, and tracing policy. ---- - ### Create the application and route Create the basic **coffee** application: @@ -281,8 +271,6 @@ URI: /coffee You shouldn't see any information from the [Jaeger dashboard](http://127.0.0.1:16686) yet: you need to create the `ObservabilityPolicy`. ---- - ### Create the ObservabilityPolicy To enable tracing for the coffee HTTPRoute, create the following policy: @@ -351,8 +339,6 @@ Select a trace to view the attributes. The trace includes the attribute from the global NginxProxy resource as well as the attribute from the ObservabilityPolicy. ---- - ## See also - [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}): learn how to dynamically update the NGINX Gateway Fabric global data plane configuration, including how to override the telemetry configuration for a particular Gateway. diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index 5aeb99fce..02c04d899 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -2,9 +2,9 @@ title: Custom policies weight: 600 toc: true -type: reference -product: NGF -docs: "DOCS-000" +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-000 --- ## Overview @@ -19,9 +19,9 @@ The following table summarizes NGINX Gateway Fabric custom policies: | Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | |---------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | -| [UpstreamSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | +| [ClientSettingsPolicy]({{< ref "/ngf/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | +| [ObservabilityPolicy]({{< ref "/ngf/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | +| [UpstreamSettingsPolicy]({{< ref "/ngf/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | {{< /bootstrap-table >}} @@ -29,8 +29,6 @@ The following table summarizes NGINX Gateway Fabric custom policies: If attaching a Policy to a Route, that Route must not share a hostname:port/path combination with any other Route that is not referenced by the same Policy. If it does, the Policy will be rejected. This is because the Policy would end up affecting other Routes that it is not attached to. {{< /important >}} ---- - ## Terminology - _Attachment Type_. How the policy attaches to an object. Attachment type can be "direct" or "inherited". @@ -38,8 +36,6 @@ If attaching a Policy to a Route, that Route must not share a hostname:port/path - _Supports Multiple Target Refs_. Whether a single policy can target multiple objects. - _Mergeable_. Whether policies that target the same object can be merged. ---- - ## Direct Policy Attachment A Direct Policy Attachment is a policy that references a single object, such as a Gateway or HTTPRoute. It is tightly bound to one instance of a particular Kind within a single Namespace or an instance of a single Kind at the cluster-scope. It affects _only_ the object specified in its TargetRef. @@ -50,8 +46,6 @@ This diagram uses a fictional retry policy to show how Direct Policy Attachment The policy targets the HTTPRoute `baz` and sets `retries` to `3` and `timeout` to `60s`. Since this policy is a Direct Policy Attachment, its settings are only applied to the `baz` HTTPRoute. ---- - ## Inherited Policy Attachment Inherited Policy Attachment allows settings to cascade down a hierarchy. The hierarchy for Gateway API resources looks like this: @@ -80,8 +74,6 @@ The `baz-policy` and `foo-policy` are attached to the `baz` and `foo` HTTPRoutes Since the `foo-policy` only defines the `retries` setting, it still inherits the `timeout` setting from `dev-policy`. The `bar` HTTPRoute has no policy attached to it and inherits all the settings from `dev-policy`. ---- - ## Merging Policies With some NGINX Gateway Fabric Policies, it is possible to create multiple policies that target the same resource as long as the fields in those policies do not conflict. @@ -129,8 +121,6 @@ However, if both policies had the `retries` field set, then the policies cannot If a policy conflicts with a configured policy, NGINX Gateway Fabric will set the policy `Accepted` status to false with a reason of `Conflicted`. See [Policy Status](#policy-status) for more details. ---- - ## Policy Status NGINX Gateway Fabric sets the [PolicyStatus](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyStatus) on all policies. diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index c09218f03..fc04731cc 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -2,9 +2,9 @@ title: Gateway API Compatibility weight: 200 toc: true -type: reference -product: NGF -docs: DOCS-1412 +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-1412 --- Learn which Gateway API resources NGINX Gateway Fabric supports and to which level. @@ -28,8 +28,6 @@ Learn which Gateway API resources NGINX Gateway Fabric supports and to which lev {{< /bootstrap-table >}} ---- - ## Terminology Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/concepts/conformance/#2-support-levels): Core, Extended and Implementation-specific. We use the following terms to describe the support status for each level and resource field: @@ -42,7 +40,6 @@ Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/ {{< note >}} It's possible that NGINX Gateway Fabric will never support some resources or fields of the Gateway API. They will be documented on a case by case basis. {{< /note >}} ---- ## Resources @@ -78,8 +75,6 @@ NGINX Gateway Fabric supports a single GatewayClass resource configured with the - `SupportedVersion/True/SupportedVersion` - `SupportedVersion/False/UnsupportedVersion` ---- - ### Gateway {{< bootstrap-table "table table-striped table-bordered" >}} @@ -145,8 +140,6 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma - `Conflicted/True/HostnameConflict` - `Conflicted/False/NoConflicts` ---- - ### HTTPRoute {{< bootstrap-table "table table-striped table-bordered" >}} @@ -198,8 +191,6 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma - `ResolvedRefs/False/InvalidIPFamily`: Custom reason for when one of the HTTPRoute rules has a backendRef that has an invalid IPFamily. - `PartiallyInvalid/True/UnsupportedValue` ---- - ### GRPCRoute {{< bootstrap-table "table table-striped table-bordered" >}} @@ -245,8 +236,6 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the GRPCRoute rules has a backendRef with an unsupported value. - `PartiallyInvalid/True/UnsupportedValue` ---- - ### ReferenceGrant {{< bootstrap-table "table table-striped table-bordered" >}} @@ -269,8 +258,6 @@ Fields: - `kind` - supports `Gateway` and `HTTPRoute`. - `namespace`- supported. ---- - ### TLSRoute {{< bootstrap-table "table table-striped table-bordered" >}} @@ -321,8 +308,6 @@ Fields: {{< /bootstrap-table >}} ---- - ### UDPRoute {{< bootstrap-table "table table-striped table-bordered" >}} @@ -333,8 +318,6 @@ Fields: {{< /bootstrap-table >}} ---- - ### BackendTLSPolicy {{< bootstrap-table "table table-striped table-bordered" >}} diff --git a/content/ngf/overview/gateway-architecture.md b/content/ngf/overview/gateway-architecture.md index 613fafa03..fa45758e7 100644 --- a/content/ngf/overview/gateway-architecture.md +++ b/content/ngf/overview/gateway-architecture.md @@ -2,9 +2,9 @@ title: Gateway architecture weight: 100 toc: true -type: reference -product: NGF -docs: DOCS-1413 +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-1413 --- Learn about the architecture and design principles of NGINX Gateway Fabric. @@ -240,7 +240,7 @@ The figure shows: - A _Kubernetes cluster_. - Users _Cluster Operator_, _Application Developer A_, _B_ and _C_. These users interact with the cluster through the Kubernetes API by creating Kubernetes objects. - _Clients A_, _B_, and _C_ connect to _Applications A_, _B_, and _C_ respectively, which the developers have deployed. -- The _NGF Pod_, [deployed by _Cluster Operator_]({{< ref "/ngf/installation">}}) in the namespace _nginx-gateway_. For scalability and availability, you can have multiple replicas. The _NGF_ container interacts with the Kubernetes API to retrieve the most up-to-date Gateway API resources created within the cluster. When a new Gateway resource is provisioned, the control plane dynamically creates and manages a corresponding NGINX data plane Deployment and Service. It watches the Kubernetes API and dynamically configures these _NGINX_ deployments based on the Gateway API resources, ensuring proper alignment between the cluster state and the NGINX configuration. +- The _NGF Pod_, [deployed by _Cluster Operator_]({{< ref "/ngf/install/">}}) in the namespace _nginx-gateway_. For scalability and availability, you can have multiple replicas. The _NGF_ container interacts with the Kubernetes API to retrieve the most up-to-date Gateway API resources created within the cluster. When a new Gateway resource is provisioned, the control plane dynamically creates and manages a corresponding NGINX data plane Deployment and Service. It watches the Kubernetes API and dynamically configures these _NGINX_ deployments based on the Gateway API resources, ensuring proper alignment between the cluster state and the NGINX configuration. - The _NGINX Pod_ consists of an NGINX container and the integrated NGINX agent, which securely communicates with the control plane over gRPC. The control plane translates Gateway API resources into NGINX configuration, and sends the configuration to the agent. - Gateways _Gateway AB_ and _Gateway C_, created by _Cluster Operator_, request points where traffic can be translated to Services within the cluster. _Gateway AB_, includes a listener with a hostname `*.example.com`. _Gateway C_, includes a listener with a hostname `*.other-example.com`. Application Developers have the ability to attach their application's routes to the _Gateway AB_ if their application's hostname matches `*.example.com`, or to _Gateway C_ if their application's hostname matches `*.other-example.com` - _Application A_ with two pods deployed in the _applications_ namespace by _Application Developer A_. To expose the application to its clients (_Clients A_) via the host `a.example.com`, _Application Developer A_ creates _HTTPRoute A_ and attaches it to `Gateway AB`. diff --git a/content/ngf/overview/nginx-plus.md b/content/ngf/overview/nginx-plus.md index 47aa8d8cc..30543eca3 100644 --- a/content/ngf/overview/nginx-plus.md +++ b/content/ngf/overview/nginx-plus.md @@ -10,7 +10,7 @@ NGINX Gateway Fabric can use NGINX Open Source or NGINX Plus as its data plane. ## Benefits of NGINX Plus -- **Robust metrics**: A plethora of [additional Prometheus metrics]({{< ref "/ngf/how-to/monitoring/prometheus.md#nginxnginx-plus-metrics" >}}) are available. -- **Live activity monitoring**: The [NGINX Plus dashboard]({{< ref "/ngf/how-to/monitoring/dashboard.md" >}}) shows real-time metrics and information about your server infrastructure. +- **Robust metrics**: A plethora of [additional Prometheus metrics]({{< ref "/ngf/monitoring/prometheus.md" >}}) are available. +- **Live activity monitoring**: The [NGINX Plus dashboard]({{< ref "/ngf/monitoring/dashboard.md" >}}) shows real-time metrics and information about your server infrastructure. - **Dynamic upstream configuration**: NGINX Plus can dynamically reconfigure upstream servers when applications in Kubernetes scale up and down, preventing the need for an NGINX reload. - **Support**: With an NGINX Plus license, you can take advantage of full [support](https://my.f5.com/manage/s/article/K000140156/) from NGINX, Inc. diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index ae0858c37..680ce73a0 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -1,9 +1,9 @@ --- title: Product telemetry weight: 500 -type: reference -product: NGF -docs: DOCS-000 +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-000 --- Learn why, what and how NGINX Gateway Fabric collects telemetry. @@ -16,8 +16,6 @@ Telemetry data is collected once every 24 hours and sent to a service managed by **If you would prefer to not have data collected, you can [opt-out](#opt-out) when installing NGINX Gateway Fabric.** ---- - ## Collected data - **Kubernetes:** diff --git a/content/ngf/overview/resource-validation.md b/content/ngf/overview/resource-validation.md index f7c7fbb85..3c11f9b18 100644 --- a/content/ngf/overview/resource-validation.md +++ b/content/ngf/overview/resource-validation.md @@ -2,17 +2,15 @@ title: Resource validation weight: 400 toc: true -type: reference -product: NGF -docs: DOCS-1414 +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-1414 --- ## Overview This document describes how NGINX Gateway Fabric validates Gateway API and NGINX Gateway Fabric Kubernetes resources. ---- - ## Gateway API resource validation NGINX Gateway Fabric validates Gateway API resources for several reasons: @@ -23,8 +21,6 @@ NGINX Gateway Fabric validates Gateway API resources for several reasons: The process involves four different steps, explained in detail in this document, with the goal of making sure that NGINX continues to handle traffic even if invalid Gateway API resources were created. ---- - ### Step 1 - OpenAPI Scheme validation by Kubernetes API Server The Kubernetes API server validates Gateway API resources against the OpenAPI schema embedded in the Gateway API CRDs. For example, if you create an HTTPRoute with an invalid hostname "cafe.!@#$%example.com", the API server will reject it with the following error: @@ -39,8 +35,6 @@ The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$% {{< note >}}While unlikely, bypassing this validation step is possible if the Gateway API CRDs are modified to remove the validation. If this happens, Step 4 will reject any invalid values (from NGINX perspective).{{< /note >}} ---- - ### Step 2 - CEL validation by Kubernetes API Server The Kubernetes API server validates Gateway API resources using CEL validation embedded in the Gateway API CRDs. It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation. For example, if you create a Gateway resource with a TCP listener that configures a hostname, the CEL validation will reject it with the following error: @@ -55,8 +49,6 @@ The Gateway "some-gateway" is invalid: spec.listeners: Invalid value: "array": h More information on CEL in Kubernetes can be found [here](https://kubernetes.io/docs/reference/using-api/cel/). ---- - ### Step 3 - Validation by NGINX Gateway Fabric This step catches the following cases of invalid values: @@ -93,8 +85,6 @@ Status: {{< note >}} This validation step always runs and cannot be bypassed. {{< /note >}} ---- - ### Confirm validation To confirm that a resource is valid and accepted by NGINX Gateway Fabric, check that the **Accepted** condition in the resource status has the Status field set to **True**. For example, in a status of a valid HTTPRoute, if NGINX Gateway Fabric accepts a parentRef, the status of that parentRef will look like this: @@ -120,8 +110,6 @@ Status: {{< note >}} Make sure the reported observed generation is the same as the resource generation. {{< /note >}} ---- - ## NGINX Gateway Fabric Resource validation ### Step 1 - OpenAPI Scheme validation by Kubernetes API Server @@ -138,8 +126,6 @@ The NginxGateway "nginx-gateway-config" is invalid: spec.logging.level: Unsuppor {{< note >}}While unlikely, bypassing this validation step is possible if the NGINX Gateway Fabric CRDs are modified to remove the validation. If this happens, Step 2 will report an error in the resource's status.{{< /note >}} ---- - ### Step 2 - Validation by NGINX Gateway Fabric This step validates the settings in the NGINX Gateway Fabric CRDs and rejects invalid resources. The validation error is reported via the status and as an Event. For example: @@ -168,8 +154,6 @@ Event: Warning UpdateFailed 1s (x2 over 1s) nginx-gateway-fabric-nginx Failed to update control plane configuration: logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error" ``` ---- - ### Confirm validation To confirm that a resource is valid and accepted by NGINX Gateway Fabric, check that the **Valid** condition in the resource status has the Status field set to **True**. For example, the status of a valid NginxGateway will look like this: diff --git a/content/ngf/reference/_index.md b/content/ngf/reference/_index.md index 075c35741..0a5299d6b 100644 --- a/content/ngf/reference/_index.md +++ b/content/ngf/reference/_index.md @@ -1,5 +1,5 @@ --- title: "Reference" -weight: 600 +weight: 700 url: /nginx-gateway-fabric/reference/ --- diff --git a/content/ngf/support.md b/content/ngf/support.md index 6fc9caeaf..29f671a44 100644 --- a/content/ngf/support.md +++ b/content/ngf/support.md @@ -1,18 +1,16 @@ --- title: Support -weight: 700 +weight: 800 toc: true -type: reference -product: NGF -docs: DOCS-1411 +nd-content-type: reference +nd-product: NGF +nd-docs: DOCS-1411 --- F5 NGINX Gateway Fabric adheres to the support policy detailed in the following knowledge base article: [K000140156](https://my.f5.com/manage/s/article/K000140156). After opening a support ticket, F5 staff will request additional information to better understand the problem. ---- - ## Kubernetes support plugin The [nginx-supportpkg-for-k8s](https://github.com/nginx/nginx-supportpkg-for-k8s) plugin collects the information needed by F5 Technical Support to assist with troubleshooting your issue. @@ -32,8 +30,6 @@ This plugin **does not** collect secrets or coredumps. Visit the [project’s GitHub repository](https://github.com/nginx/nginx-supportpkg-for-k8s) for further details. ---- - ## Support channels - If you experience issues with NGINX Gateway Fabric, please [open an issue](https://github.com/nginx/nginx-gateway-fabric/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=) in GitHub. diff --git a/content/ngf/traffic-management/_index.md b/content/ngf/traffic-management/_index.md new file mode 100644 index 000000000..d87b77402 --- /dev/null +++ b/content/ngf/traffic-management/_index.md @@ -0,0 +1,5 @@ +--- +title: "Traffic management" +url: /nginx-gateway-fabric/traffic-management/ +weight: 400 +--- diff --git a/content/ngf/how-to/traffic-management/advanced-routing.md b/content/ngf/traffic-management/advanced-routing.md similarity index 95% rename from content/ngf/how-to/traffic-management/advanced-routing.md rename to content/ngf/traffic-management/advanced-routing.md index 2709961e0..bfbc54bef 100644 --- a/content/ngf/how-to/traffic-management/advanced-routing.md +++ b/content/ngf/traffic-management/advanced-routing.md @@ -2,18 +2,16 @@ title: Application routes using HTTP matching conditions weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-1422 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1422 --- Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters ---- - ## Overview -In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request matching by path, headers, query parameters, and method. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. +In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request matching by path, headers, query parameters, and method. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) first. The following image shows the traffic flow that we will be creating with these rules. @@ -21,13 +19,9 @@ The following image shows the traffic flow that we will be creating with these r The goal is to create a set of rules that will result in client requests being sent to specific backends based on the request attributes. In this diagram, we have two versions of the `coffee` service. Traffic for v1 needs to be directed to the old application, while traffic for v2 needs to be directed towards the new application. We also have two `tea` services, one that handles GET operations and one that handles POST operations. Both the `tea` and `coffee` applications share the same Gateway. ---- - ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Coffee applications @@ -39,8 +33,6 @@ Begin by deploying the `coffee-v1`, `coffee-v2` and `coffee-v3` applications: kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/advanced-routing/coffee.yaml ``` ---- - ### Deploy the Gateway API Resources for the Coffee applications The [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the gateway: @@ -65,12 +57,16 @@ After creating the Gateway resource, NGINX Gateway Fabric will provision an NGIN Save the public IP address and port of the NGINX Service into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + +{{< note >}} + +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< /note >}} The [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) is typically deployed by the [application developer](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the `coffee` HTTPRoute: @@ -152,8 +148,6 @@ This HTTPRoute has a few important properties: If you want both conditions to be required, you can define headers and queryParams in the same match object. ---- - ### Send traffic to Coffee Using the external IP address and port for the NGINX Service, we can send traffic to our coffee applications. @@ -209,22 +203,16 @@ Server address: 10.244.0.104:8080 Server name: coffee-v3-66d58645f4-6zsl2 ``` ---- - ## Tea applications Let's deploy a different set of applications now called `tea` and `tea-post`. These applications will have their own set of rules, but will still attach to the same gateway listener as the `coffee` apps. ---- - ### Deploy the Tea applications ```shell kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/advanced-routing/tea.yaml ``` ---- - ### Deploy the HTTPRoute for the Tea services We are reusing the previous gateway for these applications, so all we need to create is the HTTPRoute. @@ -267,8 +255,6 @@ The properties of this HTTPRoute include: - The first rule defines that a POST request to the `/tea` path is routed to the `tea-post` Service. - The second rule defines that a GET request to the `/tea` path is routed to the `tea` Service. ---- - ### Send traffic to Tea Using the external IP address and port for the NGINX Service, we can send traffic to our tea applications. @@ -299,13 +285,11 @@ Server name: tea-post-b59b8596b-g586r This request should receive a response from the `tea-post` pod. Any other type of method, such as PATCH, will result in a `404 Not Found` response. ---- - ## Troubleshooting If you have any issues while sending traffic, try the following to debug your configuration and setup: -- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX Service. Refer to the [Installation]({{< ref "/ngf/installation/" >}}) guides for more information. +- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX service. Refer to the [Installation]({{< ref "/ngf/install/" >}}) guides for more information. - Check the status of the Gateway: @@ -403,8 +387,6 @@ If you have any issues while sending traffic, try the following to debug your co Check for any error messages in the conditions. ---- - ## See also To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources: diff --git a/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md b/content/ngf/traffic-management/basic-routing.md similarity index 97% rename from content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md rename to content/ngf/traffic-management/basic-routing.md index 904b21650..41a81cc81 100644 --- a/content/ngf/how-to/traffic-management/routing-traffic-to-your-app.md +++ b/content/ngf/traffic-management/basic-routing.md @@ -2,26 +2,20 @@ title: Routing traffic to applications weight: 100 toc: true -type: how-to -product: NGF -docs: DOCS-1426 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1426 --- Learn how to route external traffic to your Kubernetes applications using NGINX Gateway Fabric. ---- - ## Overview You can route traffic to your Kubernetes applications using the Gateway API and NGINX Gateway Fabric. Whether you're managing a web application or a REST backend API, you can use NGINX Gateway Fabric to expose your application outside the cluster. ---- - ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Example application @@ -148,7 +142,11 @@ Save the public IP address and port of the NGINX Service into shell variables: GW_PORT= ``` -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< note >}} + +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. + +{{< /note >}} This Gateway is associated with NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a GatewayClass with the name **nginx**. NGINX Gateway Fabric will only configure Gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< ref "/ngf/reference/cli-help.md#static-mode" >}}). @@ -253,7 +251,7 @@ You should receive a 404 Not Found error: If you have any issues while testing the configuration, try the following to debug your configuration and setup: -- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX Service. Refer to the [Installation]({{< ref "/ngf/installation/" >}}) guides for more information. +- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX Service. Refer to the [Installation]({{< ref "/ngf/install/" >}}) guides for more information. - Check the status of the gateway: diff --git a/content/ngf/how-to/traffic-management/client-settings.md b/content/ngf/traffic-management/client-settings.md similarity index 82% rename from content/ngf/how-to/traffic-management/client-settings.md rename to content/ngf/traffic-management/client-settings.md index 518f01bcc..61de5de79 100644 --- a/content/ngf/how-to/traffic-management/client-settings.md +++ b/content/ngf/traffic-management/client-settings.md @@ -1,16 +1,14 @@ --- title: Client Settings Policy API -weight: 800 -type: how-to -product: NGF toc: true -docs: DOCS-000 +weight: 800 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- Learn how to use the `ClientSettingsPolicy` API. ---- - ## Overview The `ClientSettingsPolicy` API allows Cluster Operators and Application Developers to configure the connection behavior between the client and NGINX. @@ -34,72 +32,72 @@ This guide will show you how to use the `ClientSettingsPolicy` API to configure For all the possible configuration options for `ClientSettingsPolicy`, see the [API reference]({{< ref "/ngf/reference/api.md" >}}). ---- - ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. + +Create the coffee and tea example applications: -- Create the coffee and tea example applications: +```yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/app.yaml +``` - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/app.yaml - ``` +Create a Gateway: -- Create a Gateway: +```yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/gateway.yaml +``` - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/gateway.yaml - ``` After creating the Gateway resource, NGINX Gateway Fabric will provision an NGINX Pod and Service fronting it to route traffic. -- Create HTTPRoutes for the coffee and tea applications: +Create HTTPRoutes for the coffee and tea applications: - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/httproutes.yaml - ``` +```yaml +kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/client-settings-policy/httproutes.yaml +``` -- Save the public IP address and port of the NGINX Service into shell variables: +Save the public IP address and port of the NGINX Service into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` - {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< note >}} +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. -- Test the configuration: +{{< /note >}} - You can send traffic to the coffee and tea applications using the external IP address and port for the NGINX Service. +Test the configuration: - Send a request to coffee: +You can send traffic to the coffee and tea applications using the external IP address and port for the NGINX Service. - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee - ``` +Send a request to coffee: - This request should receive a response from the coffee Pod: +```shell +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee +``` - ```text - Server address: 10.244.0.9:8080 - Server name: coffee-76c7c85bbd-cf8nz - ``` +This request should receive a response from the coffee Pod: - Send a request to tea: +```text +Server address: 10.244.0.9:8080 +Server name: coffee-76c7c85bbd-cf8nz +``` - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - ``` +Send a request to tea: - This request should receive a response from the tea Pod: +```shell +curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea +``` - ```text - Server address: 10.244.0.9:8080 - Server name: tea-76c7c85bbd-cf8nz - ``` +This request should receive a response from the tea Pod: ---- +```text +Server address: 10.244.0.9:8080 +Server name: tea-76c7c85bbd-cf8nz +``` ## Configure client max body size @@ -186,8 +184,6 @@ Server name: coffee-56b44d4c55-7ldjc You can repeat this test with the tea application to confirm that the policy affects both HTTPRoutes. ---- - ### Set a different client max body size for a route To set a different client max body size for a particular route, you can create another `ClientSettingsPolicy` that targets the route: @@ -287,8 +283,6 @@ spec: EOF ``` ---- - ## See also - [Custom policies]({{< ref "/ngf/overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work. diff --git a/content/ngf/how-to/traffic-management/https-termination.md b/content/ngf/traffic-management/https-termination.md similarity index 96% rename from content/ngf/how-to/traffic-management/https-termination.md rename to content/ngf/traffic-management/https-termination.md index 7d6e4da62..9c2736f5b 100644 --- a/content/ngf/how-to/traffic-management/https-termination.md +++ b/content/ngf/traffic-management/https-termination.md @@ -2,15 +2,13 @@ title: HTTPS termination weight: 500 toc: true -type: how-to -product: NGF -docs: DOCS-1421 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1421 --- Learn how to terminate HTTPS traffic using NGINX Gateway Fabric. ---- - ## Overview In this guide, we will show how to configure HTTPS termination for your application, using an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) redirect filter, secret, and [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/). @@ -19,9 +17,7 @@ In this guide, we will show how to configure HTTPS termination for your applicat ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Set up @@ -81,8 +77,6 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/coffee ClusterIP 10.96.189.37 80/TCP 40s ``` ---- - ## Configure HTTPS termination and routing For the HTTPS, we need a certificate and key that are stored in a secret. This secret will live in a separate namespace, so we will need a ReferenceGrant in order to access it. @@ -170,7 +164,11 @@ Save the public IP address and ports of the NGINX Service into shell variables: GW_HTTPS_PORT= ``` -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< note >}} + +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. + +{{< /note >}} To create the httproute resources, copy and paste the following into your terminal: @@ -216,8 +214,6 @@ EOF The first route issues a `requestRedirect` from the `http` listener on port 80 to `https` on port 443. The second route binds the `coffee` route to the `https` listener. ---- - ## Send traffic Using the external IP address and ports for the NGINX Service, we can send traffic to our coffee application. @@ -250,8 +246,6 @@ Server address: 10.244.0.6:80 Server name: coffee-6b8b6d6486-7fc78 ``` ---- - ## See also To learn more about redirects using the Gateway API, see the following resource: diff --git a/content/ngf/how-to/traffic-management/mirror.md b/content/ngf/traffic-management/mirror.md similarity index 92% rename from content/ngf/how-to/traffic-management/mirror.md rename to content/ngf/traffic-management/mirror.md index e6a5c0bd0..03ab98793 100644 --- a/content/ngf/how-to/traffic-management/mirror.md +++ b/content/ngf/traffic-management/mirror.md @@ -1,16 +1,14 @@ --- title: Configure Request Mirroring -weight: 700 toc: true -type: how-to -product: NGF -docs: DOCS-000 +weight: 700 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- Learn how to mirror your HTTP or gRPC traffic using NGINX Gateway Fabric. ---- - ## Overview [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) and [GRPCRoute](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) filters can be used to configure request mirroring. Mirroring copies a request to another backend. @@ -18,13 +16,9 @@ Learn how to mirror your HTTP or gRPC traffic using NGINX Gateway Fabric. In this guide, we will set up two applications, **coffee** and **tea**, and mirror requests between them. All requests sent to the **coffee** application will also be sent to the **tea** application automatically. ---- - ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Set up @@ -143,12 +137,16 @@ After creating the Gateway resource, NGINX Gateway Fabric will provision an NGIN Save the public IP address and port of the NGINX Service into shell variables: - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` +```text +GW_IP=XXX.YYY.ZZZ.III +GW_PORT= +``` + +{{< note >}} + +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< /note >}} Now create an HTTPRoute that defines a RequestMirror filter that copies all requests sent to `/coffee` to be sent to the **coffee** backend and mirrored to the **tea** backend. Use the following command: diff --git a/content/ngf/how-to/traffic-management/redirects-and-rewrites.md b/content/ngf/traffic-management/redirects-and-rewrites.md similarity index 96% rename from content/ngf/how-to/traffic-management/redirects-and-rewrites.md rename to content/ngf/traffic-management/redirects-and-rewrites.md index 60df195f8..a29ca6a1f 100644 --- a/content/ngf/how-to/traffic-management/redirects-and-rewrites.md +++ b/content/ngf/traffic-management/redirects-and-rewrites.md @@ -2,37 +2,29 @@ title: HTTP redirects and rewrites weight: 400 toc: true -type: how-to -product: NGF -docs: DOCS-1424 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1424 --- Learn how to redirect or rewrite your HTTP traffic using NGINX Gateway Fabric. ---- - ## Overview [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) filters can be used to configure HTTP redirects or rewrites. Redirects return HTTP 3XX responses to a client, instructing it to retrieve a different resource. Rewrites modify components of a client request (such as hostname and/or path) before proxying it upstream. -In this guide, we will set up the coffee application to demonstrate path URL rewriting, and the tea and soda applications to showcase path-based request redirection. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. +In this guide, we will set up the coffee application to demonstrate path URL rewriting, and the tea and soda applications to showcase path-based request redirection. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) first. -To see an example of a redirect using scheme and port, see the [HTTPS Termination]({{< ref "/ngf/how-to/traffic-management/https-termination.md" >}}) guide. - ---- +To see an example of a redirect using scheme and port, see the [HTTPS Termination]({{< ref "/ngf/traffic-management/https-termination.md" >}}) guide. ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## HTTP rewrites and redirects examples We will configure a common gateway for the `URLRewrite` and `RequestRedirect` filter examples mentioned below. ---- - ### Deploy the Gateway resource for the applications The [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [Cluster Operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: @@ -61,17 +53,16 @@ GW_IP=XXX.YYY.ZZZ.III GW_PORT= ``` -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} +{{< note >}} +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. ---- +{{< /note >}} ## URLRewrite example This examples demonstrates how to rewrite the traffic URL for a simple coffee application. An HTTPRoute resource is used to define two `URLRewrite` filters that will rewrite requests. You can verify the server responds with the rewritten URL. ---- - ### Deploy the coffee application Create the **coffee** application in Kubernetes by copying and pasting the following block into your terminal: @@ -130,8 +121,6 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/coffee ClusterIP 10.96.189.37 80/TCP 40s ``` ---- - ### Configure a path rewrite The following HTTPRoute defines two filters that will rewrite requests such as the following: @@ -184,8 +173,6 @@ spec: EOF ``` ---- - ### Send traffic Using the external IP address and port for the NGINX Service, we can send traffic to our coffee application. @@ -262,14 +249,10 @@ Server name: coffee-6db967495b-twn6x URI: /prices?test=v1&test=v2 ``` ---- - ## RequestRedirect example This example demonstrates how to redirect the traffic to a new location for the tea and soda applications, using `RequestRedirect` filters. ---- - ### Setup Create the **tea** and **soda** application in Kubernetes by copying and pasting the following block into your terminal: @@ -363,8 +346,6 @@ service/soda ClusterIP 10.96.230.208 80/TCP 89m service/tea ClusterIP 10.96.151.194 80/TCP 120m ``` ---- - ### Configure a path redirect In this section, we'll define two HTTPRoutes for the tea and soda applications to demonstrate different types of request redirection using the `RequestRedirect` filter. @@ -431,8 +412,6 @@ spec: EOF ``` ---- - ### Send traffic Using the external IP address and port for the NGINX Service, we can send traffic to our tea and soda applications to verify the redirect is successful. We will use curl's `--include` option to print the response headers (we are interested in the `Location` header). @@ -515,8 +494,6 @@ HTTP/1.1 302 Moved Temporarily Location: http://cafe.example.com:8080/flavors?test=v1 ``` ---- - ## See also To learn more about redirects and rewrites using the Gateway API, see the following resource: diff --git a/content/ngf/how-to/traffic-management/request-response-headers.md b/content/ngf/traffic-management/request-response-headers.md similarity index 96% rename from content/ngf/how-to/traffic-management/request-response-headers.md rename to content/ngf/traffic-management/request-response-headers.md index 6d41a07d2..24740cbb1 100644 --- a/content/ngf/how-to/traffic-management/request-response-headers.md +++ b/content/ngf/traffic-management/request-response-headers.md @@ -2,9 +2,9 @@ title: Modify HTTP request and response headers weight: 600 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- Learn how to modify the request and response headers of your application using NGINX Gateway Fabric. @@ -13,22 +13,16 @@ Learn how to modify the request and response headers of your application using N [HTTP Header Modifiers](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/?h=request#http-header-modifiers) can be used to add, modify or remove headers during the request-response lifecycle. The [RequestHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-request-header-modifier) is used to alter headers in a request sent by client and [ResponseHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-response-header-modifier) is used to alter headers in a response to the client. -This guide describes how to configure the headers application to modify the headers in the request. Another version of the headers application is then used to modify response headers when client requests are made. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. - ---- +This guide describes how to configure the headers application to modify the headers in the request. Another version of the headers application is then used to modify response headers when client requests are made. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) first. ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## HTTP Header Modifiers examples We will configure a common gateway for the `RequestHeaderModifier` and `ResponseHeaderModifier` examples mentioned below. ---- - ### Deploy the Gateway API resources for the Header application The [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [Cluster Operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: @@ -57,10 +51,11 @@ GW_IP=XXX.YYY.ZZZ.III GW_PORT= ``` -{{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for .{{< /note >}} +{{< note >}} +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. ---- +{{< /note >}} ## RequestHeaderModifier example @@ -87,8 +82,6 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/headers ClusterIP 10.96.26.161 80/TCP 23s ``` ---- - ### Configure the HTTPRoute with RequestHeaderModifier filter Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. Use the following command: @@ -140,8 +133,6 @@ This HTTPRoute has a few important properties: 1. Appends the value `compress` to the `Accept-Encoding` header and `this-is-an-appended-value` to the `My-Cool-header`. 1. Removes `User-Agent` header. ---- - ### Send traffic to the Headers application To access the application, use `curl` to send requests to the `headers` Service, which includes headers within the request. @@ -172,8 +163,6 @@ In the output above, you can see that the headers application modifies the follo - The header `My-Overwrite-Header` gets overwritten from `dont-see-this` to `this-is-the-only-value`. - The header `Accept-encoding` remains unchanged as we did not modify it in the curl request sent. ---- - ### Delete the resources Delete the headers application and HTTPRoute: another instance will be used for the next examples. @@ -186,14 +175,10 @@ kubectl delete httproutes.gateway.networking.k8s.io headers kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/examples/http-request-header-filter/headers.yaml ``` ---- - ## ResponseHeaderModifier example Begin by configuring an application with custom headers and a simple HTTPRoute. The server response can be observed see its headers. The next step is to modify some of the headers using HTTPRoute filters to modify responses. Finally, verify the server responds with the modified headers. ---- - ### Deploy the Headers application Begin by deploying the example application `headers`. It is a simple application that adds response headers that will be modified later. @@ -216,8 +201,6 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/headers ClusterIP 10.96.15.12 80/TCP 95s ``` ---- - ### Configure the basic HTTPRoute Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. You can do this with the following command: @@ -251,8 +234,6 @@ This HTTPRoute has a few important properties: - `cafe.example.com` is the hostname that is matched for all requests to the backends defined in this HTTPRoute. - The `match` rule defines that all requests with the path prefix `/headers` are sent to the `headers` Service. ---- - ### Send traffic to the Headers application Use `curl` with the `-i` flag to access the application and include the response headers in the output: @@ -285,8 +266,6 @@ In the output above, you can see that the headers application adds the following The next section will modify these headers by adding a ResponseHeaderModifier filter to the headers HTTPRoute. ---- - ### Update the HTTPRoute to modify the Response headers Update the HTTPRoute by adding a `ResponseHeaderModifier` filter: @@ -331,8 +310,6 @@ Notice that this HTTPRoute has a `ResponseHeaderModifier` filter defined for the - Adds the value `this-is-the-appended-value` to the header `X-Header-Add`. - Removes `X-Header-Remove` header. ---- - ### Send traffic to the modified Headers application Send a curl request to the modified `headers` application to verify the response headers are modified. @@ -358,8 +335,6 @@ ok In the output above you can notice the modified response headers as the `X-Header-Unmodified` remains unchanged as we did not include it in the filter and `X-Header-Remove` header is absent. The header `X-Header-Add` gets appended with the new value and `X-Header-Set` gets overwritten to `overwritten-value` as defined in the _HttpRoute_. ---- - ## See also To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources: diff --git a/content/ngf/how-to/traffic-management/snippets.md b/content/ngf/traffic-management/snippets.md similarity index 98% rename from content/ngf/how-to/traffic-management/snippets.md rename to content/ngf/traffic-management/snippets.md index 2c91deb93..0112d01a5 100644 --- a/content/ngf/how-to/traffic-management/snippets.md +++ b/content/ngf/traffic-management/snippets.md @@ -2,15 +2,13 @@ title: "Use the SnippetsFilter API" weight: 800 toc: true -type: how-to -product: NGF -docs: "DOCS-000" +nd-content-type: how-to +nd-product: NGF +nd-docs: "DOCS-000" --- This topic introduces Snippets, how to implement them using the `SnippetsFilter` API, and provides an example of how to use `SnippetsFilter` for rate limiting. ---- - ## Overview Snippets allow users to insert NGINX configuration into different contexts of the @@ -22,8 +20,6 @@ and only in cases where Gateway API resources or NGINX extension policies don't Users can configure Snippets through the `SnippetsFilter` API. `SnippetsFilter` can be an [HTTPRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter) or [GRPCRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GRPCRouteFilter), that can be defined in an HTTPRoute/GRPCRoute rule and is intended to modify NGINX configuration specifically for that Route rule. `SnippetsFilter` is an `extensionRef` type filter. ---- - ## Disadvantages of Snippets {{< warning >}} We recommend managing NGINX configuration through Gateway API resources, [first-class policies]({{< ref "/ngf/overview/custom-policies.md" >}}), and other existing [NGINX extensions]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}) @@ -41,8 +37,6 @@ Snippets have the following disadvantages: {{< note >}} If the NGINX configuration includes an invalid Snippet, NGINX will continue to operate with the last valid configuration. No new configuration will be applied until the invalid Snippet is fixed. {{< /note >}} ---- - ## Best practices for SnippetsFilters There are endless ways to use `SnippetsFilters` to modify NGINX configuration, and equal ways to generate invalid or undesired NGINX configuration. @@ -54,11 +48,9 @@ We have outlined a few best practices to keep in mind when using `SnippetsFilter 1. In a `SnippetsFilter`, only one Snippet per NGINX context is allowed, however multiple `SnippetsFilters` can be referenced in the same routing rule. As such, `SnippetsFilters` should not conflict with each other. If `SnippetsFilters` do conflict, they should not be referenced on the same routing rule. 1. `SnippetsFilters` that define Snippets targeting NGINX contexts `main`, `http`, or `http.server`, can potentially affect more than the routing rule they are referenced by. Proceed with caution and verify the behavior of the NGINX configuration before creating those `SnippetsFilters` in a production scenario. ---- - ## Setup -- To enable Snippets, [install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric with these modifications: +- To enable Snippets, [install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with these modifications: - Using Helm: set the `nginxGateway.snippetsFilters.enable=true` Helm value. - Using Kubernetes manifests: set the `--snippets-filters` flag in the nginx-gateway container argument, add `snippetsfilters` to the RBAC @@ -132,8 +124,6 @@ After creating the Gateway resource, NGINX Gateway Fabric will provision an NGIN You should see all successful responses in quick succession as we have not configured any rate limiting rules yet. ---- - ## Create Rate Limiting SnippetsFilters Configure a rate limiting `SnippetsFilter` named `rate-limiting-sf` by adding the following `SnippetsFilter`: @@ -222,8 +212,6 @@ Status: Events: ``` ---- - ## Configure coffee to reference rate-limiting-sf SnippetsFilter To use the `rate-limiting-sf` `SnippetsFilter`, update the coffee HTTPRoute to reference it: @@ -306,8 +294,6 @@ for i in `seq 1 10`; do curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://c You should see all successful responses from the coffee Pod, but they should be spaced apart roughly one second each as expected through the rate limiting configuration. ---- - ## Configure tea to reference no-delay-rate-limiting-sf SnippetsFilter Update the tea HTTPRoute to reference the `no-delay-rate-limting-sf` `SnippetsFilter`: @@ -403,8 +389,6 @@ Request ID: 890c17df930ef1ef573feed3c6e81290 This is the default error response given by NGINX when the rate limit burst is exceeded, meaning our `SnippetsFilter` correctly applied our rate limiting NGINX configuration changes. ---- - ## Conclusion You've successfully used Snippets with the `SnippetsFilter` resource to configure two distinct rate limiting rules to different backend applications. @@ -417,8 +401,6 @@ This follows our recommended Role and Persona separation described in the [Best For an alternative method of modifying the NGINX configuration NGINX Gateway Fabric generates through Gateway API resources, check out our supported [first-class policies]({{< ref "/ngf/overview/custom-policies.md" >}}) which don't carry many of the aforementioned disadvantages of Snippets. ---- - ## Troubleshooting If a `SnippetsFilter` is defined in a Route and contains a Snippet which includes an invalid NGINX configuration, NGINX will continue to operate @@ -476,8 +458,6 @@ Conditions: {{< note >}} If you run into situations where an NGINX directive fails to be applied and the troubleshooting information here isn't sufficient, please create an issue in the [NGINX Gateway Fabric Github repository](https://github.com/nginx/nginx-gateway-fabric). {{< /note >}} ---- - ## See also - [API reference]({{< ref "/ngf/reference/api.md" >}}): all configuration fields for the `SnippetsFilter` API. diff --git a/content/ngf/how-to/traffic-management/tls-passthrough.md b/content/ngf/traffic-management/tls-passthrough.md similarity index 96% rename from content/ngf/how-to/traffic-management/tls-passthrough.md rename to content/ngf/traffic-management/tls-passthrough.md index 52cf11f58..82637e353 100644 --- a/content/ngf/how-to/traffic-management/tls-passthrough.md +++ b/content/ngf/traffic-management/tls-passthrough.md @@ -2,34 +2,26 @@ title: Configure TLS passthrough weight: 800 toc: true -type: how-to -product: NGF -docs: DOCS-000 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-000 --- Learn how to use TLSRoutes to configure TLS passthrough load-balancing with NGINX Gateway Fabric. ---- - ## Overview In this guide, we will show how to configure TLS passthrough for your application, using a [TLSRoute](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute). ---- - ## Note on Gateway API Experimental Features {{< important >}} TLSRoute is a Gateway API resource from the experimental release channel. {{< /important >}} {{< include "/ngf/installation/install-gateway-api-experimental-features.md" >}} ---- - ## Before you begin -- [Install]({{< relref "/ngf/installation/" >}}) NGINX Gateway Fabric with experimental features enabled. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with experimental features enabled. ## Set up @@ -172,7 +164,11 @@ GW_IP=XXX.YYY.ZZZ.III GW_TLS_PORT= ``` -{{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the Gateway will forward for. {{< /note >}} +{{< note >}} + +In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the Gateway will forward for. + +{{< /note >}} Create a TLSRoute that attaches to the Gateway and routes requests to `app.example.com` to the `secure-app` Service: @@ -198,8 +194,6 @@ EOF {{< note >}}To route to a Service in a Namespace different from the TLSRoute Namespace, create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1beta1.ReferenceGrant) to permit the cross-namespace reference. {{< /note >}} ---- - ## Send traffic Using the external IP address and port for the NGINX Service, send traffic to the `secure-app` application. diff --git a/content/ngf/how-to/traffic-management/upstream-settings.md b/content/ngf/traffic-management/upstream-settings.md similarity index 99% rename from content/ngf/how-to/traffic-management/upstream-settings.md rename to content/ngf/traffic-management/upstream-settings.md index 8f99f3d2d..f57d4d13f 100644 --- a/content/ngf/how-to/traffic-management/upstream-settings.md +++ b/content/ngf/traffic-management/upstream-settings.md @@ -34,9 +34,7 @@ For all the possible configuration options for `UpstreamSettingsPolicy`, see the ## Before you begin -- [Install]({{< relref "/ngf/installation/" >}}) NGINX Gateway Fabric. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric. ## Setup diff --git a/content/ngf/traffic-security/_index.md b/content/ngf/traffic-security/_index.md new file mode 100644 index 000000000..70eb63d81 --- /dev/null +++ b/content/ngf/traffic-security/_index.md @@ -0,0 +1,5 @@ +--- +title: "Traffic security" +url: /nginx-gateway-fabric/traffic-security +weight: 500 +--- \ No newline at end of file diff --git a/content/ngf/how-to/traffic-security/integrating-cert-manager.md b/content/ngf/traffic-security/integrate-cert-manager.md similarity index 99% rename from content/ngf/how-to/traffic-security/integrating-cert-manager.md rename to content/ngf/traffic-security/integrate-cert-manager.md index 6c17cd145..575ced75a 100644 --- a/content/ngf/how-to/traffic-security/integrating-cert-manager.md +++ b/content/ngf/traffic-security/integrate-cert-manager.md @@ -2,9 +2,9 @@ title: Secure traffic using Let's Encrypt and cert-manager weight: 100 toc: true -type: how-to -product: NGF -docs: DOCS-1425 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1425 --- Learn how to issue and manage certificates using Let's Encrypt and cert-manager. @@ -27,7 +27,7 @@ You need: - Administrator access to a Kubernetes cluster. - [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally. -- [NGINX Gateway Fabric deployed]({{< ref "/ngf/installation/" >}}) in the Kubernetes cluster. +- [NGINX Gateway Fabric deployed]({{< ref "/ngf/install/" >}}) in the Kubernetes cluster. - A DNS-resolvable domain name is required. It must resolve to the public endpoint of the NGINX Gateway Fabric deployment, and this public endpoint must be an external IP address or alias accessible over the internet. The process here will depend on your DNS provider. This DNS name will need to be resolvable from the Let’s Encrypt servers, which may require that you wait for the record to propagate before it will work. --- diff --git a/content/ngf/how-to/traffic-security/securing-backend-traffic.md b/content/ngf/traffic-security/secure-backend.md similarity index 95% rename from content/ngf/how-to/traffic-security/securing-backend-traffic.md rename to content/ngf/traffic-security/secure-backend.md index e8ce86ec8..d532bdbc3 100644 --- a/content/ngf/how-to/traffic-security/securing-backend-traffic.md +++ b/content/ngf/traffic-security/secure-backend.md @@ -2,20 +2,18 @@ title: Securing backend traffic weight: 200 toc: true -type: how-to -product: NGF -docs: DOCS-1423 +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1423 --- Learn how to encrypt HTTP traffic between NGINX Gateway Fabric and your backend pods. ---- - ## Overview -In this guide, we will show how to specify the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/). This covers the use-case where the service or backend owner is doing their own TLS and NGINX Gateway Fabric needs to know how to connect to this backend pod that has its own certificate over HTTPS. +In this guide, we will show how to specify the TLS configuration of the connection from the Gateway to a backend pod with the Service API object using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/). ---- +The intended use-case is when a service or backend owner is managing their own TLS and NGINX Gateway Fabric needs to know how to connect to this backend pod that has its own certificate over HTTPS. ## Note on Gateway API Experimental Features @@ -23,13 +21,9 @@ In this guide, we will show how to specify the TLS configuration of the connecti {{< include "/ngf/installation/install-gateway-api-experimental-features.md" >}} ---- - ## Before you begin -- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric with experimental features enabled. - ---- +- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric with experimental features enabled. ## Set up @@ -133,11 +127,9 @@ NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/secure-app ClusterIP 10.96.213.57 8443/TCP 9s ``` ---- - ## Configure routing rules -First, we will create the Gateway resource with an HTTP listener: +First, create the Gateway resource with an HTTP listener: ```yaml kubectl apply -f - < -- /bin/sh ``` ---- - #### Logs Logs from the NGINX Gateway Fabric control plane and data plane can contain information that isn't available to status or events. These can include errors in processing or passing traffic. @@ -138,8 +128,6 @@ You can see logs for a crashed or killed container by adding the `-p` flag to th To modify log levels for the control plane in NGINX Gateway Fabric, edit the `NginxGateway` configuration. This can be done either before or after deploying NGINX Gateway Fabric. Refer to this [guide](https://docs.nginx.com/nginx-gateway-fabric/how-to/control-plane-configuration/) to do so. To check error logs, modify the log level to `error` to view error logs. Similarly, change the log level to `debug` and `grep` for the word `debug` to view debug logs. ---- - #### Understanding the generated NGINX configuration Understanding the NGINX configuration is key for fixing issues because it shows how NGINX handles requests. This helps tweak settings to make sure NGINX behaves the way you want it to for your application. To see your current configuration, you can open a shell in the _nginx_ container by following these [steps](#get-shell-access-to-nginx-container) and run `nginx -T`. To understand the usage of NGINX directives in the configuration file, consult this list of [NGINX directives](https://nginx.org/en/docs/dirindex.html). @@ -284,21 +272,15 @@ Handling connection for 8080 The configuration may change in future releases. This configuration is valid for version 1.3. {{< /warning >}} ---- - #### Metrics for troubleshooting -Metrics can be useful to identify performance bottlenecks and pinpoint areas of high resource consumption within NGINX Gateway Fabric. To set up metrics collection, refer to the [Prometheus Metrics guide]({{< ref "prometheus.md" >}}). The metrics dashboard will help you understand problems with the way NGINX Gateway Fabric is set up or potential issues that could show up with time. - ---- +Metrics can be useful to identify performance bottlenecks and pinpoint areas of high resource consumption within NGINX Gateway Fabric. To set up metrics collection, refer to the [Prometheus Metrics guide]({{< ref "/ngf/monitoring/prometheus.md" >}}). The metrics dashboard will help you understand problems with the way NGINX Gateway Fabric is set up or potential issues that could show up with time. #### Access the NGINX Plus Dashboard If you have NGINX Gateway Fabric installed with NGINX Plus, you can access the NGINX Plus dashboard at `http://localhost:8080/dashboard.html`. Verify that the port number (for example, `8080`) matches the port number you have port-forwarded to your NGINX Gateway Fabric Pod. For further details, see the [dashboard guide]({{< ref "dashboard.md" >}}) ---- - ### Common errors {{< bootstrap-table "table table-striped table-bordered" >}} @@ -308,13 +290,11 @@ Verify that the port number (for example, `8080`) matches the port number you ha | Startup | NGINX Gateway Fabric fails to start. | Check logs for _nginx_ and _nginx-gateway_ containers. | Readiness probe failed. | | Resources not configured | Status missing on resources. | Check referenced resources. | Referenced resources do not belong to NGINX Gateway Fabric. | | NGINX errors | Reload failures on NGINX | Fix permissions for control plane. | Security context not configured. | -| NGINX Plus errors | Failure to start; traffic interruptions | Set up the [NGINX Plus JWT]({{< ref "/ngf/installation/nginx-plus-jwt.md" >}}) | License is not configured or has expired. | -| Client Settings | Request entity too large error | Adjust client settings. Refer to [Client Settings Policy]({{< relref "../traffic-management/client-settings.md" >}}) | Payload is greater than the [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) value.| +| NGINX Plus errors | Failure to start; traffic interruptions | Set up the [NGINX Plus JWT]({{< ref "/ngf/install/nginx-plus.md" >}}) | License is not configured or has expired. | +| Client Settings | Request entity too large error | Adjust client settings. Refer to [Client Settings Policy]({{< ref "/ngf/traffic-management/client-settings.md" >}}) | Payload is greater than the [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) value.| {{< /bootstrap-table >}} ---- - ##### NGINX fails to reload NGINX reload errors can occur for various reasons, including syntax errors in configuration files, permission issues, and more. To determine if NGINX has failed to reload, check logs for your _nginx-gateway_ and _nginx_ containers. @@ -322,8 +302,6 @@ You will see the following error in the _nginx-gateway_ logs: `failed to reload To debug why your reload has failed, start with verifying the syntax of your configuration files by opening a shell in the NGINX container following these [steps](#get-shell-access-to-nginx-container) and running `nginx -T`. If there are errors in your configuration file, the reload will fail and specify the reason for it. ---- - ##### NGINX Gateway Fabric Pod is not running or ready To understand why the NGINX Gateway Fabric Pod has not started running or is not ready, check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`: @@ -376,8 +354,6 @@ Events: Normal Started 20s kubelet Started container nginx-gateway ``` ---- - ##### NGINX Pod is not running or ready To understand why the NGINX Pod has not started running or is not ready, check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`: @@ -428,8 +404,6 @@ Events: Normal Started 2m53s kubelet Started container nginx ``` ---- - ##### NGINX Plus failure to start or traffic interruptions Beginning with NGINX Gateway Fabric 1.5.0, NGINX Plus requires a valid JSON Web Token (JWT) to run. If this is not set up properly, or your JWT token has expired, you may see errors in the NGINX logs that look like the following: @@ -446,9 +420,7 @@ nginx: [emerg] License file is required. Download JWT license from MyF5 and conf nginx: [emerg] license expired ``` -These errors could prevent NGINX Plus from starting or prevent traffic from flowing. To fix these issues, see the [NGINX Plus JWT]({{< ref "/ngf/installation/nginx-plus-jwt.md" >}}) guide. - ---- +These errors could prevent NGINX Plus from starting or prevent traffic from flowing. To fix these issues, see the [NGINX Plus JWT]({{< ref "/ngf/install/nginx-plus.md" >}}) guide. ##### 413 Request Entity Too Large @@ -471,9 +443,7 @@ Or view the following error message in the NGINX logs: ``` The request body exceeds the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size). -To **resolve** this, you can configure the `client_max_body_size` using the `ClientSettingsPolicy` API. Read the [Client Settings Policy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) documentation for more information. - ---- +To **resolve** this, you can configure the `client_max_body_size` using the `ClientSettingsPolicy` API. Read the [Client Settings Policy]({{< ref "/ngf/traffic-management/client-settings.md" >}}) documentation for more information. ##### IP Family Mismatch Errors @@ -509,8 +479,6 @@ To **resolve** this, you can do one of the following: - Adjust the IPFamily of your Service to match that of the NginxProxy configuration. ---- - ##### Policy cannot be applied to target If you `describe` your Policy and see the following error: @@ -530,8 +498,6 @@ This means you are attempting to attach a Policy to a Route that has an overlapp - Combine the Route rules for the overlapping path into a single Route. - If the Policy allows it, specify both Routes in the `targetRefs` list. ---- - ##### Broken Header error If you check your _nginx_ container logs and see the following error: @@ -546,8 +512,6 @@ It indicates that `proxy_protocol` is enabled for the gateway listeners, but the - Send valid proxy information with requests being handled by your application. ---- - ### See also You can view the [Kubernetes Troubleshooting Guide](https://kubernetes.io/docs/tasks/debug/debug-application/) for more debugging guidance. diff --git a/content/ngf/upgrading-ngf.md b/content/ngf/upgrading-ngf.md deleted file mode 100644 index d19aebed7..000000000 --- a/content/ngf/upgrading-ngf.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Upgrade NGINX Gateway Fabric to version 2.x -weight: 400 -toc: true -type: how-to -product: NGF -docs: DOCS-0000 ---- - -This guide provides step-by-step instructions for upgrading NGINX Gateway Fabric from version 1.x to 2.x, highlighting key architectural changes, expected downtime, and important considerations for custom resource definitions (CRDs). - - -### Upgrade from v1.x to v2.x - -To upgrade NGINX Gateway Fabric from version 1.x to the new architecture in version 2.x, you must uninstall the existing NGINX Gateway Fabric CRDs and deployment, and perform a fresh installation. This will cause brief downtime during the upgrade process. - -{{}} You do not need to uninstall the Gateway API CRDs during the upgrade. These resources are compatible with the new NGINX Gateway Fabric version. {{}} - -#### Uninstall NGINX Gateway Fabric v1.x - -To remove the previous version 1.x of NGINX Gateway Fabric, follow these steps: - -First, run the following command to uninstall NGINX Gateway Fabric from the `nginx-gateway` namespace, and update `ngf` to your release name if it is different: - -```shell -helm uninstall ngf -n nginx-gateway -``` - -Afterwards, remove CRDs associated with NGINX Gateway Fabric version 1.x with the following command: - -```shell -kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.2/deploy/crds.yaml -``` - -{{}} - -{{%tab name="Helm"%}} - -Follow these steps to install NGINX Gateway Fabric v2.x using Helm: - -Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace. The following `helm install` command will install the NGINX Gateway Fabric release along with the necessary CRDs required for the deployment: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway -``` - -For additional customization options during the helm installation process, take a look at [Installation with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md" >}}). - -{{% /tab %}} - -{{%tab name="Manifests"%}} - -Follow these steps to install NGINX Gateway Fabric v2.x using Manifests: - -Apply the new CRDs with the following command: - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml -``` - -Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command: - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml -``` - -For additional customization options during the installation process using manifests, take a look at [Installation with Manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md" >}}). - -{{% /tab %}} - -{{}} - - -### Architecture changes - -With this release, NGINX Gateway Fabric adopts a new architecture that separates the control plane and data plane into independent deployments. This separation improves scalability, security, and operational clarity. - -The control plane is a Kubernetes controller that watches Gateway API and Kubernetes resources (e.g., Services, Endpoints, Secrets) and dynamically provisions NGINX data plane deployments for each Gateway. - -NGINX configurations are generated by the control plane and securely delivered to the data planes via gRPC, using the NGINX Agent. TLS is enabled by default, with optional integration with `cert-manager`. - -Each data plane pod runs NGINX alongside the Agent, which applies config updates and handles reloads without shared volumes or signals. This design ensures dynamic, per-Gateway traffic management and operational isolation. - -New fields have been added to the `NginxProxy` resource to configure infrastructure-related settings for data plane deployments. The `NginxProxy` resource is now a namespaced-scoped resource, instead of a cluster-scoped resource, and can be modified at either the Gateway or GatewayClass level. These new fields provide the flexibility to customize deployment and service configurations. - -For detailed instructions on how to modify these settings, refer to the [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}) guide. - - -### Key links for the version 2.x update - -- To read more on [modifying data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}). -- To learn more about [deploying a Gateway for data plane instances]({{< ref "/ngf/installation/installing-ngf/deploy-data-plane.md" >}}). -- To adding secure [authentication to control plane and data planes]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}). -- To read more about [architecture changes]({{< ref "/ngf/overview/gateway-architecture.md" >}}). -- For detailed [API reference]({{< ref "/ngf/reference/api.md" >}}).