Skip to content

Commit 4577687

Browse files
kate-osbornsjberman
kate-osborn
and
sjberman
authored
Update NGF documentation on how to use NginxProxy (#135)
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. Co-authored-by: Saylor Berman <[email protected]>
1 parent 17c7f2d commit 4577687

File tree

2 files changed

+206
-40
lines changed

2 files changed

+206
-40
lines changed

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

Lines changed: 202 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -11,80 +11,202 @@ 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 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.
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.
1515

16-
The data plane configuration is stored in the NginxProxy custom resource, which is a cluster-scoped resource that is attached to the `nginx` 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.
17+
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.
1718

18-
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.
19+
---
1920

20-
When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config`.
21+
## Merging Semantics
2122

22-
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
23+
NginxProxy resources are merged when a GatewayClass and a Gateway reference different NginxProxy resources.
2324

24-
{{< 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 >}}
25+
For fields that are bools, integers, and strings:
26+
- If a field on the Gateway's NginxProxy is unspecified (`nil`), the Gateway __inherits__ the value of the field in the GatewayClass's NginxProxy.
27+
- If a field on the Gateway's NginxProxy is specified, its value __overrides__ the value of the field in the GatewayClass's NginxProxy.
2528

26-
---
29+
For array fields:
30+
- If the array on the Gateway's NginxProxy is unspecified (`nil`), the Gateway __inherits__ the entire array in the GatewayClass's NginxProxy.
31+
- If the array on the Gateway's NginxProxy is empty, it __overrides__ the entire array in the GatewayClass's NginxProxy, effectively unsetting the field.
32+
- If the array on the Gateway's NginxProxy is specified and not empty, it __overrides__ the entire array in the GatewayClass's NginxProxy.
2733

28-
## Viewing and Updating the Configuration
2934

30-
If the `NginxProxy` resource already exists, you can view and edit it.
35+
### Merging Examples
3136

32-
{{< note >}} For the following examples, the name `ngf-proxy-config` should be updated to the name of the resource created for your installation. {{< /note >}}
37+
This section contains examples of how NginxProxy resources are merged when they are attached to both a Gateway and its GatewayClass.
3338

34-
To view the current configuration:
39+
#### Disable HTTP/2 for a Gateway
3540

36-
```shell
37-
kubectl describe nginxproxies ngf-proxy-config
41+
A GatewayClass references the following NginxProxy which explicitly allows HTTP/2 traffic and sets the IPFamily to ipv4:
42+
43+
```yaml
44+
apiVersion: gateway.nginx.org/v1alpha2
45+
kind: NginxProxy
46+
metadata:
47+
name: gateway-class-enable-http2
48+
namespace: default
49+
spec:
50+
ipFamily: "ipv4"
51+
disableHTTP: false
3852
```
3953
40-
To update the configuration:
54+
To disable HTTP/2 traffic for a particular Gateway, reference the following NginxProxy in the Gateway's spec:
4155
42-
```shell
43-
kubectl edit nginxproxies ngf-proxy-config
56+
```yaml
57+
apiVersion: gateway.nginx.org/v1alpha2
58+
kind: NginxProxy
59+
metadata:
60+
name: gateway-disable-http
61+
namespace: default
62+
spec:
63+
disableHTTP: true
4464
```
4565
46-
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.
66+
These NginxProxy resources are merged and the following settings are applied to the Gateway:
4767
48-
To view the status of the configuration, check the GatewayClass that it is attached to:
68+
```yaml
69+
ipFamily: "ipv4"
70+
disableHTTP: true
71+
```
4972
50-
```shell
51-
kubectl describe gatewayclasses nginx
73+
#### Change Telemetry configuration for a Gateway
74+
75+
A GatewayClass references the following NginxProxy which configures telemetry:
76+
77+
```yaml
78+
apiVersion: gateway.nginx.org/v1alpha2
79+
kind: NginxProxy
80+
metadata:
81+
name: gateway-class-telemetry
82+
namespace: default
83+
spec:
84+
telemetry:
85+
exporter:
86+
endpoint: "my.telemetry.collector:9000"
87+
interval: "60s"
88+
batchSize: 20
89+
serviceName: "my-company"
90+
spanAttributes:
91+
- key: "company-key"
92+
value: "company-value"
5293
```
5394
54-
```text
55-
...
56-
Status:
57-
Conditions:
58-
...
59-
Message: parametersRef resource is resolved
60-
Observed Generation: 1
61-
Reason: ResolvedRefs
62-
Status: True
63-
Type: ResolvedRefs
95+
To change the telemetry configuration for a particular Gateway, reference the following NginxProxy in the Gateway's spec:
96+
97+
```yaml
98+
apiVersion: gateway.nginx.org/v1alpha2
99+
kind: NginxProxy
100+
metadata:
101+
name: gateway-telemetry-service-name
102+
namespace: default
103+
spec:
104+
telemetry:
105+
exporter:
106+
batchSize: 50
107+
batchCount: 5
108+
serviceName: "my-app"
109+
spanAttributes:
110+
- key: "app-key"
111+
value: "app-value"
64112
```
65113
66-
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.
114+
These NginxProxy resources are merged and the following settings are applied to the Gateway:
115+
116+
```yaml
117+
telemetry:
118+
exporter:
119+
endpoint: "my.telemetry.collector:9000"
120+
interval: "60s"
121+
batchSize: 50
122+
batchCount: 5
123+
serviceName: "my-app"
124+
spanAttributes:
125+
- key: "app-key"
126+
value: "app-value"
127+
```
128+
129+
#### Disable Tracing for a Gateway
130+
131+
A GatewayClass references the following NginxProxy which configures telemetry:
132+
133+
```yaml
134+
apiVersion: gateway.nginx.org/v1alpha2
135+
kind: NginxProxy
136+
metadata:
137+
name: gateway-class-telemetry
138+
namespace: default
139+
spec:
140+
telemetry:
141+
exporter:
142+
endpoint: "my.telemetry.collector:9000"
143+
interval: "60s"
144+
serviceName: "my-company"
145+
```
146+
147+
To disable tracing for a particular Gateway, reference the following NginxProxy in the Gateway's spec:
148+
149+
```yaml
150+
apiVersion: gateway.nginx.org/v1alpha2
151+
kind: NginxProxy
152+
metadata:
153+
name: gateway-disable-tracing
154+
namespace: default
155+
spec:
156+
telemetry:
157+
disabledFeatures:
158+
- DisableTracing
159+
```
160+
161+
These NginxProxy resources are merged and the following settings are applied to the Gateway:
162+
163+
```yaml
164+
telemetry:
165+
exporter:
166+
endpoint: "my.telemetry.collector:9000"
167+
interval: "60s"
168+
serviceName: "my-app"
169+
disabledFeatures:
170+
- DisableTracing
171+
```
67172
68173
---
69174
70-
## Manually create the configuration
175+
## Configuring the GatewayClass NginxProxy on Install
176+
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.
178+
179+
When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config` and is created in the release Namespace.
71180

72-
If the `NginxProxy` resource doesn't exist, you can create it and attach it to the GatewayClass.
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+
183+
{{< 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 >}}
184+
185+
---
186+
187+
## Manually Creating NginxProxies
73188

74189
The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`:
75190

76191
```yaml
77192
kubectl apply -f - <<EOF
78-
apiVersion: gateway.nginx.org/v1alpha1
193+
apiVersion: gateway.nginx.org/v1alpha2
79194
kind: NginxProxy
80195
metadata:
81196
name: ngf-proxy-config
197+
namespace: default
82198
spec:
83199
ipFamily: ipv4
84200
EOF
85201
```
86202

87-
Now we need to attach it to the GatewayClass:
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+
205+
---
206+
207+
### Attaching NginxProxy to GatewayClass
208+
209+
To attach the `ngf-proxy-config` NginxProxy to the GatewayClass:
88210

89211
```shell
90212
kubectl edit gatewayclass nginx
@@ -97,12 +219,54 @@ parametersRef:
97219
group: gateway.nginx.org
98220
kind: NginxProxy
99221
name: ngf-proxy-config
222+
namespace: default
100223
```
101224

102225
After updating, you can check the status of the GatewayClass to see if the configuration is valid:
103226

104227
```shell
105-
kubectl describe gatewayclasses nginx
228+
kubectl describe gatewayclass nginx
229+
```
230+
231+
```text
232+
...
233+
Status:
234+
Conditions:
235+
...
236+
Message: parametersRef resource is resolved
237+
Observed Generation: 1
238+
Reason: ResolvedRefs
239+
Status: True
240+
Type: ResolvedRefs
241+
```
242+
243+
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.
244+
245+
---
246+
247+
### Attaching NginxProxy to Gateway
248+
249+
To attach the `ngf-proxy-config` NginxProxy to a Gateway:
250+
251+
```shell
252+
kubectl edit gateway <gateway-name>
253+
```
254+
255+
This will open your default editor, allowing you to add the following to the `spec`:
256+
257+
```yaml
258+
infrastructure:
259+
parametersRef:
260+
group: gateway.nginx.org
261+
kind: NginxProxy
262+
name: ngf-proxy-config
263+
namespace: default
264+
```
265+
266+
After updating, you can check the status of the Gateway to see if the configuration is valid:
267+
268+
```shell
269+
kubectl describe gateway <gateway-name>
106270
```
107271

108272
```text
@@ -129,7 +293,7 @@ The following command creates a basic `NginxProxy` configuration that sets the l
129293

130294
```yaml
131295
kubectl apply -f - <<EOF
132-
apiVersion: gateway.nginx.org/v1alpha1
296+
apiVersion: gateway.nginx.org/v1alpha2
133297
kind: NginxProxy
134298
metadata:
135299
name: ngf-proxy-config
@@ -139,8 +303,6 @@ spec:
139303
EOF
140304
```
141305

142-
After attaching the NginxProxy to the GatewayClass, the log level of the data plane will be updated to `warn`.
143-
144306
To view the full list of supported log levels, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).
145307

146308
{{< 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
189351

190352
```yaml
191353
kubectl apply -f - <<EOF
192-
apiVersion: gateway.nginx.org/v1alpha1
354+
apiVersion: gateway.nginx.org/v1alpha2
193355
kind: NginxProxy
194356
metadata:
195357
name: ngf-proxy-config

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,10 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma
9898

9999
- `spec`
100100
- `gatewayClassName`: Supported.
101+
- `infrastructure`: Partially Supported.
102+
- `parametersRef`: NginxProxy resource supported.
103+
- `labels`: Not supported.
104+
- `annotations`: Not supported.
101105
- `listeners`
102106
- `name`: Supported.
103107
- `hostname`: Supported.

0 commit comments

Comments
 (0)