From d6a1d0d667c950ed6835f42a5508c554c47e74f4 Mon Sep 17 00:00:00 2001 From: salonichf5 <146118978+salonichf5@users.noreply.github.com> Date: Tue, 6 May 2025 13:01:10 -0600 Subject: [PATCH 1/4] docs: update data plane config file --- .../ngf/how-to/data-plane-configuration.md | 54 ++++++++++++++----- 1 file changed, 41 insertions(+), 13 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index 61a1bc57d..c6a1886b9 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -11,9 +11,9 @@ 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 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. +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 options such as configuring an OpenTelemetry collector, disabling HTTP/2, changing the IP family, modifying infrastructure-related fields, and 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. +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. --- @@ -172,21 +172,19 @@ telemetry: --- -## Configuring the GatewayClass NginxProxy on Install +## 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. +By default, the `NginxProxy` resource is created in the same namespace where NGINX Gateway Fabric is installed. You can set configuration options in the `nginx.` Helm values, and the resource will be created and attached using the set values, when NGINX Gateway Fabric is installed using Helm. You can also manually create and attach specific `NginxProxy` resources to target different data planes [manually creating NginxProxies](#manually-creating-nginxProxies). When installed using the Helm chart, the NginxProxy resource is named `-proxy-config` and is created in the release Namespace. -**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`: +The following command creates a basic `NginxProxy` configuration in the `default` namespace that sets the IP family to `ipv4` instead of the default value of `dual`: ```yaml kubectl apply -f - <}}).** - --- ### Attaching NginxProxy to GatewayClass @@ -282,11 +278,13 @@ Status: If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status. +{{< note >}} The `NginxProxy` resource must reside in the same namespace as the Gateway it is attached to. {{< /note >}} + --- ## Configure the data plane log level -You can use the `NginxProxy` resource to dynamically configure the Data Plane Log Level. +You can use the `NginxProxy` resource at the GatewayClass level to dynamically configure the log level for all data plane instances. The following command creates a basic `NginxProxy` configuration that sets the log level to `warn` instead of the default value of `info`: @@ -302,7 +300,7 @@ spec: EOF ``` -To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). +Other log levels supported are debug, notice, error, crit, alert, emerg. {{< note >}}For `debug` logging to work, NGINX needs to be built with `--with-debug` or "in debug mode". NGINX Gateway Fabric can easily be [run with NGINX in debug mode](#run-nginx-gateway-fabric-with-nginx-in-debug-mode) upon startup through the addition @@ -375,6 +373,36 @@ spec: EOF ``` -For the full configuration API, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). - {{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--haproxy-protocol` to avoid broken header errors. {{< /note >}} + +--- + +## Configure infrastructure-related settings + +You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the GatewayClass level. These settings can also be specified under `nginx.` in the Helm values file. + +Users can specify these settings for NGINX data plane deployments: + + - _replicas_ specifies the number of data plane pod replicas.. + - The `pod` section provides control over pod scheduling and lifecycle behavior. You can configure settings such as _terminationGracePeriodSeconds_, _tolerations_, _nodeSelector_, _affinity_, and _topologySpreadConstraints_. Use _extraVolumes_ to mount additional volumes, typically alongside container-level _extraVolumeMounts_. + - The `container` defines settings for the NGINX container itself., such as resource requests and limits using _resources_, and lifecycle hooks like preStop or postStart via _lifecycle_. You can also specify _extraVolumeMounts_ to mount additional volumes defined at the pod level. + +Users can specify these settings for NGINX data plane service in the `service` config: + + - _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer. + - _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP. + - _annotations_ adds custom annotations to the NGINX data plane service. + - Certain fields are only applicable when _service.type_ is set to `LoadBalancer`: _loadBalancerIP_ to assign a static IP, _loadBalancerClass_ to define the load balancer implementation, and _loadBalancerSourceRanges_ to restrict access to specific IP ranges (CIDRs). + + The below fields can only be specified when the `service.type` is `LoadBalancer`: + - _loadBalancerIP_ specifies the static IP address of the load balancer. + - _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to. + - _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer. + +--- + +## See also + +For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). + +--- From 4ab74052eea91b2045d5ff038249f75264054f02 Mon Sep 17 00:00:00 2001 From: salonichf5 <146118978+salonichf5@users.noreply.github.com> Date: Wed, 7 May 2025 21:35:24 +0530 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Saylor Berman Co-authored-by: Alan Dooley --- .../ngf/how-to/data-plane-configuration.md | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index c6a1886b9..dc063b20d 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -174,7 +174,7 @@ telemetry: ## Configuring the GatewayClass NginxProxy on install -By default, the `NginxProxy` resource is created in the same namespace where NGINX Gateway Fabric is installed. You can set configuration options in the `nginx.` Helm values, and the resource will be created and attached using the set values, when NGINX Gateway Fabric is installed using Helm. You can also manually create and attach specific `NginxProxy` resources to target different data planes [manually creating NginxProxies](#manually-creating-nginxProxies). +By default, an `NginxProxy` resource is created in the same namespace where NGINX Gateway Fabric is installed, attached to the GatewayClass. You can set configuration options in the `nginx` Helm value section, and the resource will be created and attached using the set values. You can also [manually create and attach](#manually-creating-nginxProxies) specific `NginxProxy` resources to target different Gateways. When installed using the Helm chart, the NginxProxy resource is named `-proxy-config` and is created in the release Namespace. @@ -383,26 +383,23 @@ You can configure deployment and service settings for all data plane instances b Users can specify these settings for NGINX data plane deployments: - - _replicas_ specifies the number of data plane pod replicas.. - - The `pod` section provides control over pod scheduling and lifecycle behavior. You can configure settings such as _terminationGracePeriodSeconds_, _tolerations_, _nodeSelector_, _affinity_, and _topologySpreadConstraints_. Use _extraVolumes_ to mount additional volumes, typically alongside container-level _extraVolumeMounts_. - - The `container` defines settings for the NGINX container itself., such as resource requests and limits using _resources_, and lifecycle hooks like preStop or postStart via _lifecycle_. You can also specify _extraVolumeMounts_ to mount additional volumes defined at the pod level. +- _replicas_ specifies the number of data plane pod replicas.. +- The `pod` section provides control over pod scheduling and lifecycle behavior. You can configure settings such as _terminationGracePeriodSeconds_, _tolerations_, _nodeSelector_, _affinity_, and _topologySpreadConstraints_. Use _extraVolumes_ to mount additional volumes, typically alongside container-level _extraVolumeMounts_. +- The `container` defines settings for the NGINX container itself., such as resource requests and limits using _resources_, and lifecycle hooks like preStop or postStart via _lifecycle_. You can also specify _extraVolumeMounts_ to mount additional volumes defined at the pod level. Users can specify these settings for NGINX data plane service in the `service` config: - - _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer. - - _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP. - - _annotations_ adds custom annotations to the NGINX data plane service. - - Certain fields are only applicable when _service.type_ is set to `LoadBalancer`: _loadBalancerIP_ to assign a static IP, _loadBalancerClass_ to define the load balancer implementation, and _loadBalancerSourceRanges_ to restrict access to specific IP ranges (CIDRs). +- _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer. +- _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP. +- _annotations_ adds custom annotations to the NGINX data plane service. - The below fields can only be specified when the `service.type` is `LoadBalancer`: - - _loadBalancerIP_ specifies the static IP address of the load balancer. - - _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to. - - _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer. +The below fields can only be specified when the `service.type` is `LoadBalancer`: +- _loadBalancerIP_ specifies the static IP address of the load balancer. +- _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to. +- _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer. ---- ## See also For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). ---- From 9738803d1bfaa6cdb968200387a150c37a80bca4 Mon Sep 17 00:00:00 2001 From: salonichf5 <146118978+salonichf5@users.noreply.github.com> Date: Wed, 7 May 2025 11:35:34 -0600 Subject: [PATCH 3/4] modify section about infrastructure related settings, api ref links --- .../ngf/how-to/data-plane-configuration.md | 95 +++++++------------ 1 file changed, 33 insertions(+), 62 deletions(-) diff --git a/content/ngf/how-to/data-plane-configuration.md b/content/ngf/how-to/data-plane-configuration.md index dc063b20d..f588ca8ea 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -198,45 +198,7 @@ spec: EOF ``` ---- - -### Attaching NginxProxy to GatewayClass - -To attach the `ngf-proxy-config` NginxProxy to the GatewayClass: - -```shell -kubectl edit gatewayclass nginx -``` - -This will open your default editor, allowing you to add the following to the `spec`: - -```yaml -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 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. +For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). --- @@ -258,6 +220,8 @@ infrastructure: name: ngf-proxy-config ``` +{{< note >}} The `NginxProxy` resource must reside in the same namespace as the Gateway it is attached to. {{< /note >}} + After updating, you can check the status of the Gateway to see if the configuration is valid: ```shell @@ -278,13 +242,11 @@ Status: If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status. -{{< note >}} The `NginxProxy` resource must reside in the same namespace as the Gateway it is attached to. {{< /note >}} - --- ## Configure the data plane log level -You can use the `NginxProxy` resource at the GatewayClass level to dynamically configure the log level for all data plane instances. +You can use the `NginxProxy` resource to dynamically configure the log level. The following command creates a basic `NginxProxy` configuration that sets the log level to `warn` instead of the default value of `info`: @@ -300,7 +262,7 @@ spec: EOF ``` -Other log levels supported are debug, notice, error, crit, alert, emerg. +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 be [run with NGINX in debug mode](#run-nginx-gateway-fabric-with-nginx-in-debug-mode) upon startup through the addition @@ -379,27 +341,36 @@ EOF ## Configure infrastructure-related settings -You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the GatewayClass level. These settings can also be specified under `nginx.` in the Helm values file. - -Users can specify these settings for NGINX data plane deployments: - -- _replicas_ specifies the number of data plane pod replicas.. -- The `pod` section provides control over pod scheduling and lifecycle behavior. You can configure settings such as _terminationGracePeriodSeconds_, _tolerations_, _nodeSelector_, _affinity_, and _topologySpreadConstraints_. Use _extraVolumes_ to mount additional volumes, typically alongside container-level _extraVolumeMounts_. -- The `container` defines settings for the NGINX container itself., such as resource requests and limits using _resources_, and lifecycle hooks like preStop or postStart via _lifecycle_. You can also specify _extraVolumeMounts_ to mount additional volumes defined at the pod level. +You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the Gateway or GatewayClass level. These settings can also be specified under `nginx.` in the Helm values file. You can edit things such as replicas, pod scheduling options, container resource limits, extra volume mounts, service types and load balancer settings. -Users can specify these settings for NGINX data plane service in the `service` config: - -- _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer. -- _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP. -- _annotations_ adds custom annotations to the NGINX data plane service. - -The below fields can only be specified when the `service.type` is `LoadBalancer`: -- _loadBalancerIP_ specifies the static IP address of the load balancer. -- _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to. -- _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer. +The following command creates an `NginxProxy` resource with 2 replicas, sets `container.resources.requests` to 100m CPU and 128Mi memory, configures a 90 second `pod.terminationGracePeriodSeconds`, and sets the service type to `LoadBalancer` with IP `192.87.9.1` and AWS NLB annotation. +```yaml +kubectl apply -f - <}}). -For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). +--- From feabd3ddc89b67a51ab1e1d26f0b6264c7626cf1 Mon Sep 17 00:00:00 2001 From: salonichf5 <146118978+salonichf5@users.noreply.github.com> Date: Wed, 7 May 2025 12:58:09 -0600 Subject: [PATCH 4/4] update based on review --- 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 f588ca8ea..c164f5318 100644 --- a/content/ngf/how-to/data-plane-configuration.md +++ b/content/ngf/how-to/data-plane-configuration.md @@ -341,7 +341,7 @@ EOF ## Configure infrastructure-related settings -You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the Gateway or GatewayClass level. These settings can also be specified under `nginx.` in the Helm values file. You can edit things such as replicas, pod scheduling options, container resource limits, extra volume mounts, service types and load balancer settings. +You can configure deployment and service settings for all data plane instances by editing the `NginxProxy` resource at the Gateway or GatewayClass level. These settings can also be specified under the `nginx` section in the Helm values file. You can edit things such as replicas, pod scheduling options, container resource limits, extra volume mounts, service types and load balancer settings. The following command creates an `NginxProxy` resource with 2 replicas, sets `container.resources.requests` to 100m CPU and 128Mi memory, configures a 90 second `pod.terminationGracePeriodSeconds`, and sets the service type to `LoadBalancer` with IP `192.87.9.1` and AWS NLB annotation. @@ -370,7 +370,7 @@ spec: EOF ``` -To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). +To view the full list of configuration options, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}). ---