From ceea1d85c68bc3acd76ee1886b63c5f4baf701e4 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Tue, 28 Jan 2025 16:22:38 -0700 Subject: [PATCH 1/3] Update NGF documentation on how to use NginxProxy Updates the Gateway API Compatibility doc to list Gateway Infrastructure field as partially supported. Also, updates the data plane configuration how-to to describe how to attach NginxProxy resources to Gateways and GatewayClasses. --- .../ngf/how-to/data-plane-configuration.md | 244 +++++++++++++++--- .../ngf/overview/gateway-api-compatibility.md | 4 + 2 files changed, 207 insertions(+), 41 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 90d2070f2..e8e8626ae 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -11,83 +11,205 @@ Learn how to dynamically update the NGINX Gateway Fabric global data plane confi ## Overview -NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration is a global configuration for NGINX that has options that are not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, changing the IP family, or setting the NGINX error log level. +NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration contains configuration for NGINX that are not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, changing the IP family, or setting the NGINX error log level. -The data plane configuration is stored in the NginxProxy custom resource, which is a cluster-scoped resource that is attached to the `nginx` GatewayClass. +The data plane configuration is stored in the NginxProxy custom resource, which is a namespace-scoped resource that can be attached to a GatewayClass or Gateway. When attached to a GatewayClass, the fields in the NginxProxy affect all Gateways that belong to the GatewayClass. +When attached to a Gateway, the fields in the NginxProxy only affect the Gateway. If a GatewayClass and its Gateway both specify an NginxProxy, the GatewayClass NginxProxy provides defaults that can be overridden by the Gateway NginxProxy. See the [Merging Semantics](#merging-semantics) section for more detail. -By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-creating-the-configuration) the resource after NGINX Gateway Fabric is already installed. +--- -When installed using the Helm chart, the NginxProxy resource is named `-proxy-config`. +## Merging Semantics -**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).** +NginxProxy resources are merged when a GatewayClass and a Gateway reference different NginxProxy resources. -{{< 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 fields that are bools, integers, and strings: +- If a field on the Gateway's NginxProxy is unspecified (`nil`), the Gateway __inherits__ the value of the field in the GatewayClass's NginxProxy. +- If a field on the Gateway's NginxProxy is specified, its value __overrides__ the value of the field in the GatewayClass's NginxProxy. ---- +For array fields: +- If the array on the Gateway's NginxProxy is unspecified (`nil`), the Gateway __inherits__ the entire array in the GatewayClass's NginxProxy. +- If the array on the Gateway's NginxProxy is empty, it __overrides__ the entire array in the GatewayClass's NginxProxy, effectively unsetting the field. +- If the array on the Gateway's NginxProxy is specified and not empty, it __overrides__ the entire array in the GatewayClass's NginxProxy. -## Viewing and Updating the Configuration -If the `NginxProxy` resource already exists, you can view and edit it. +### Merging Examples -{{< note >}} For the following examples, the name `ngf-proxy-config` should be updated to the name of the resource created for your installation. {{< /note >}} +This section contains examples of how NginxProxy resources are merged when they are attached to both a Gateway and its GatewayClass. -To view the current configuration: +#### Disable HTTP/2 for a Gateway -```shell -kubectl describe nginxproxies ngf-proxy-config +A GatewayClass references the following NginxProxy which explicitly allows HTTP/2 traffic and sets the IPFamily to ipv4: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-class-enable-http2 + namespace: default +spec: + ipFamily: "ipv4" + disableHTTP: false ``` -To update the configuration: +To disable HTTP/2 traffic for a particular Gateway, reference the following NginxProxy in the Gateway's spec: -```shell -kubectl edit nginxproxies ngf-proxy-config +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-disable-http + namespace: default +spec: + disableHTTP: true ``` -This will open the configuration in your default editor. You can then update and save the configuration, which is applied automatically to the data plane. +These NginxProxy resources are merged and the following settings are applied to the Gateway: -To view the status of the configuration, check the GatewayClass that it is attached to: +```yaml +ipFamily: "ipv4" +disableHTTP: true +``` -```shell -kubectl describe gatewayclasses nginx +#### Change Telemetry configuration for a Gateway + +A GatewayClass references the following NginxProxy which configures telemetry: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-class-telemetry + namespace: default +spec: + telemetry: + exporter: + endpoint: "my.telemetry.collector:9000" + interval: "60s" + batchSize: 20 + serviceName: "my-company" + spanAttributes: + - key: "company-key" + value: "company-value" ``` -```text -... -Status: - Conditions: - ... - Message: parametersRef resource is resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs +To change the telemetry configuration for a particular Gateway, reference the following NginxProxy in the Gateway's spec: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-telemetry-service-name + namespace: default +spec: + telemetry: + exporter: + batchSize: 50 + batchCount: 5 + serviceName: "my-app" + spanAttributes: + - key: "app-key" + value: "app-value" ``` -If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status. +These NginxProxy resources are merged and the following settings are applied to the Gateway: + +```yaml + telemetry: + exporter: + endpoint: "my.telemetry.collector:9000" + interval: "60s" + batchSize: 50 + batchCount: 5 + serviceName: "my-app" + spanAttributes: + - key: "app-key" + value: "app-value" +``` + +#### Disable Tracing for a Gateway + +A GatewayClass references the following NginxProxy which configures telemetry: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-class-telemetry + namespace: default +spec: + telemetry: + exporter: + endpoint: "my.telemetry.collector:9000" + interval: "60s" + serviceName: "my-company" +``` + +To disable tracing for a particular Gateway, reference the following NginxProxy in the Gateway's spec: + +```yaml +apiVersion: gateway.nginx.org/v1alpha2 +kind: NginxProxy +metadata: + name: gateway-disable-tracing + namespace: default +spec: + telemetry: + disabledFeatures: + - DisableTracing +``` + +These NginxProxy resources are merged and the following settings are applied to the Gateway: + +```yaml +telemetry: + exporter: + endpoint: "my.telemetry.collector:9000" + interval: "60s" + serviceName: "my-app" + disabledFeatures: + - DisableTracing +``` --- -## Manually create the configuration +## Configuring the GatewayClass NginxProxy on Install + +By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached to the GatewayClass when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-creating-nginxproxies) the resource after NGINX Gateway Fabric is already installed. + +When installed using the Helm chart, the NginxProxy resource is named `-proxy-config` and is created in the release Namespace. -If the `NginxProxy` resource doesn't exist, you can create it and attach it to the GatewayClass. +**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/how-to/monitoring/tracing.md" >}}), for example). {{< /note >}} + +--- + +## Manually Creating NginxProxies The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`: ```yaml kubectl apply -f - <}}).** + +--- + +### Attaching NginxProxy to GatewayClass + +To attach the `ngf-proxy-config` NginxProxy to the GatewayClass: ```shell -kubectl edit gatewayclass nginx +kubectl edit gatewayclass ``` This will open your default editor, allowing you to add the following to the `spec`: @@ -97,12 +219,54 @@ parametersRef: group: gateway.nginx.org kind: NginxProxy name: ngf-proxy-config + namespace: default ``` After updating, you can check the status of the GatewayClass to see if the configuration is valid: ```shell -kubectl describe gatewayclasses nginx +kubectl describe gatewayclasses +``` + +```text +... +Status: + Conditions: + ... + Message: parametersRef resource is resolved + Observed Generation: 1 + Reason: ResolvedRefs + Status: True + Type: ResolvedRefs +``` + +If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status. + +--- + +### Attaching NginxProxy to Gateway + +To attach the `ngf-proxy-config` NginxProxy to a Gateway: + +```shell +kubectl edit gateway +``` + +This will open your default editor, allowing you to add the following to the `spec`: + +```yaml +infrastructure: + parametersRef: + group: gateway.nginx.org + kind: NginxProxy + name: ngf-proxy-config + namespace: default +``` + +After updating, you can check the status of the Gateway to see if the configuration is valid: + +```shell +kubectl describe gateway ``` ```text @@ -129,7 +293,7 @@ The following command creates a basic `NginxProxy` configuration that sets the l ```yaml kubectl apply -f - <}}). {{< note >}}For `debug` logging to work, NGINX needs to be built with `--with-debug` or "in debug mode". NGINX Gateway Fabric can easily @@ -189,7 +351,7 @@ The following command creates an `NginxProxy` resource with `RewriteClientIP` se ```yaml kubectl apply -f - <}}) comma - `spec` - `gatewayClassName`: Supported. + - `infrastructure`: Partially Supported. + - `parametersRef`: NginxProxy resource supported. + - `labels`: Not supported. + - `annotations`: Not supported. - `listeners` - `name`: Supported. - `hostname`: Supported. From f1b68ab3d420a97501e0517c56896add7341ecc1 Mon Sep 17 00:00:00 2001 From: Kate Osborn <50597707+kate-osborn@users.noreply.github.com> Date: Wed, 29 Jan 2025 09:30:25 -0700 Subject: [PATCH 2/3] Update content/ngf/how-to/data-plane-configuration.md Co-authored-by: Saylor Berman --- content/ngf/how-to/data-plane-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index e8e8626ae..4578cbdcd 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -11,7 +11,7 @@ Learn how to dynamically update the NGINX Gateway Fabric global data plane confi ## Overview -NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration contains configuration for NGINX that are not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, changing the IP family, or setting the NGINX error log level. +NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration contains configuration for NGINX that is not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, changing the IP family, or setting the NGINX error log level. The data plane configuration is stored in the NginxProxy custom resource, which is a namespace-scoped resource that can be attached to a GatewayClass or Gateway. When attached to a GatewayClass, the fields in the NginxProxy affect all Gateways that belong to the GatewayClass. When attached to a Gateway, the fields in the NginxProxy only affect the Gateway. If a GatewayClass and its Gateway both specify an NginxProxy, the GatewayClass NginxProxy provides defaults that can be overridden by the Gateway NginxProxy. See the [Merging Semantics](#merging-semantics) section for more detail. From fbc2aceb774146f8e966f937c24ac4b57435cd44 Mon Sep 17 00:00:00 2001 From: Kate Osborn Date: Wed, 29 Jan 2025 09:32:50 -0700 Subject: [PATCH 3/3] Use default gatewayclass name --- content/ngf/how-to/data-plane-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 4578cbdcd..7270947e7 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -209,7 +209,7 @@ EOF To attach the `ngf-proxy-config` NginxProxy to the GatewayClass: ```shell -kubectl edit gatewayclass +kubectl edit gatewayclass nginx ``` This will open your default editor, allowing you to add the following to the `spec`: @@ -225,7 +225,7 @@ parametersRef: After updating, you can check the status of the GatewayClass to see if the configuration is valid: ```shell -kubectl describe gatewayclasses +kubectl describe gatewayclass nginx ``` ```text