Skip to content

Commit b9a03d2

Browse files
committed
docs: update data plane config file
1 parent 707e7df commit b9a03d2

File tree

1 file changed

+41
-13
lines changed

1 file changed

+41
-13
lines changed

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

+41-13
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ Learn how to dynamically update the NGINX Gateway Fabric global data plane confi
1111

1212
## Overview
1313

14-
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.
14+
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 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.
1515

16-
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.
16+
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.
1717
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.
1818

1919
---
@@ -172,21 +172,19 @@ telemetry:
172172
173173
---
174174
175-
## Configuring the GatewayClass NginxProxy on Install
175+
## Configuring the GatewayClass NginxProxy on install
176176
177-
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.
177+
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).
178178

179179
When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config` and is created in the release Namespace.
180180

181-
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
182-
183181
{{< 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 >}}
184182

185183
---
186184

187185
## Manually Creating NginxProxies
188186

189-
The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`:
187+
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`:
190188

191189
```yaml
192190
kubectl apply -f - <<EOF
@@ -200,8 +198,6 @@ spec:
200198
EOF
201199
```
202200

203-
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
204-
205201
---
206202

207203
### Attaching NginxProxy to GatewayClass
@@ -282,11 +278,13 @@ Status:
282278

283279
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.
284280

281+
{{< note >}} The `NginxProxy` resource must reside in the same namespace as the Gateway it is attached to. {{< /note >}}
282+
285283
---
286284

287285
## Configure the data plane log level
288286

289-
You can use the `NginxProxy` resource to dynamically configure the Data Plane Log Level.
287+
You can use the `NginxProxy` resource at the GatewayClass level to dynamically configure the log level for all data plane instances.
290288

291289
The following command creates a basic `NginxProxy` configuration that sets the log level to `warn` instead of the default value of `info`:
292290

@@ -302,7 +300,7 @@ spec:
302300
EOF
303301
```
304302

305-
To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
303+
Other log levels supported are debug, notice, error, crit, alert, emerg.
306304

307305
{{< note >}}For `debug` logging to work, NGINX needs to be built with `--with-debug` or "in debug mode". NGINX Gateway Fabric can easily
308306
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:
375373
EOF
376374
```
377375

378-
For the full configuration API, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
379-
380376
{{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--haproxy-protocol` to avoid broken header errors. {{< /note >}}
377+
378+
---
379+
380+
## Configure infrastructure-related settings
381+
382+
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.
383+
384+
Users can specify these settings for NGINX data plane deployments:
385+
386+
- _replicas_ specifies the number of data plane pod replicas..
387+
- 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_.
388+
- 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.
389+
390+
Users can specify these settings for NGINX data plane service in the `service` config:
391+
392+
- _type_ specifies the service type for the NGINX data plane. Allowed values are ClusterIP, NodePort, or LoadBalancer.
393+
- _externalTrafficPolicy_ sets how external traffic is handled. `Local` preserves the client’s source IP.
394+
- _annotations_ adds custom annotations to the NGINX data plane service.
395+
- 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).
396+
397+
The below fields can only be specified when the `service.type` is `LoadBalancer`:
398+
- _loadBalancerIP_ specifies the static IP address of the load balancer.
399+
- _loadBalancerClass_ specifies the class of the load balancer implementation this service belongs to.
400+
- _loadBalancerSourceRanges_ specifies IP ranges (CIDR) that are allowed to access the load balancer.
401+
402+
---
403+
404+
## See also
405+
406+
For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
407+
408+
---

0 commit comments

Comments
 (0)