Update NGF documentation on how to use NginxProxy

content/ngf/how-to/data-plane-configuration.md

@@ -11,80 +11,202 @@ 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 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 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 `<release-name>-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 `<release-name>-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 - <<EOF
-apiVersion: gateway.nginx.org/v1alpha1
+apiVersion: gateway.nginx.org/v1alpha2
 kind: NginxProxy
 metadata:
   name: ngf-proxy-config
+  namespace: default
 spec:
   ipFamily: ipv4
 EOF
 ```
 
-Now we need to 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" >}}).**
+
+---
+
+### Attaching NginxProxy to GatewayClass
+
+To attach the `ngf-proxy-config` NginxProxy to the GatewayClass:
 
 ```shell
 kubectl edit gatewayclass nginx
@@ -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 gatewayclass nginx
+```
+
+```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 <gateway-name>
+```
+
+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 <gateway-name>
 ```
 
 ```text
@@ -129,7 +293,7 @@ The following command creates a basic `NginxProxy` configuration that sets the l
 
 ```yaml
 kubectl apply -f - <<EOF
-apiVersion: gateway.nginx.org/v1alpha1
+apiVersion: gateway.nginx.org/v1alpha2
 kind: NginxProxy
 metadata:
   name: ngf-proxy-config
@@ -139,8 +303,6 @@ spec:
 EOF
 ```
 
-After attaching the NginxProxy to the GatewayClass, the log level of the data plane will be updated to `warn`.
-
 To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
 
 {{< 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 - <<EOF
-apiVersion: gateway.nginx.org/v1alpha1
+apiVersion: gateway.nginx.org/v1alpha2
 kind: NginxProxy
 metadata:
   name: ngf-proxy-config

content/ngf/overview/gateway-api-compatibility.md

@@ -98,6 +98,10 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma
 
 - `spec`
   - `gatewayClassName`: Supported.
+  - `infrastructure`: Partially Supported.
+    - `parametersRef`: NginxProxy resource supported.
+    - `labels`: Not supported.
+    - `annotations`: Not supported.
   - `listeners`
     - `name`: Supported.
     - `hostname`: Supported.