Skip to content

Commit b44b1a8

Browse files
sjbermansjberman
authored
Add high level doc for data plane config (#2378)
Problem: As a user, I want to know how I can configure global settings for nginx. Solution: Add a doc that talks about how global data plane config can be set.
1 parent 2ac3239 commit b44b1a8

File tree

4 files changed

+151
-28
lines changed

4 files changed

+151
-28
lines changed

‎.github/workflows/docs-build-push.yml

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,29 @@ on:
1818
paths:
1919
- "site/**"
2020

21+
concurrency:
22+
group: ${{ github.ref_name }}-docs-push
23+
cancel-in-progress: true
24+
2125
permissions:
2226
contents: read
2327

2428
jobs:
29+
vars:
30+
runs-on: ubuntu-22.04
31+
outputs:
32+
azure_creds: ${{ steps.vars.outputs.defined }}
33+
steps:
34+
- name: Check if variable is set
35+
id: vars
36+
env:
37+
AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS_DOCS }}
38+
if: "${{ env.AZURE_CREDENTIALS != '' }}"
39+
run: echo "defined=true" >> $GITHUB_OUTPUT
40+
2541
call-docs-build-push:
26-
if: ${{ github.event.repository.fork == false }}
42+
needs: [vars]
43+
if: ${{ github.event.repository.fork == false && needs.vars.outputs.azure_creds == 'true' }}
2744
uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@03a9a3808fcb77cd0c19d7fa5d59b25565dd1d6d # v1.0.2
2845
permissions:
2946
pull-requests: write # needed to write preview url comment to PR

‎site/content/how-to/control-plane-configuration.md

Lines changed: 18 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ toc: true
55
docs: "DOCS-1416"
66
---
77

8-
Learn how to dynamically update the Gateway Fabric control plane configuration.
8+
Learn how to dynamically update the NGINX Gateway Fabric control plane configuration.
99

1010
## Overview
1111

@@ -22,42 +22,34 @@ If the resource is invalid to the OpenAPI schema, the Kubernetes API server will
2222

2323
Additionally, the control plane updates the status of the resource (if it exists) to reflect whether it is valid or not.
2424

25-
### Spec
26-
27-
{{< bootstrap-table "table table-striped table-bordered" >}}
28-
| name | description | type | required |
29-
|---------|-----------------------------------------------------------------|--------------------------|----------|
30-
| logging | Logging defines logging related settings for the control plane. | [logging](#speclogging) | no |
31-
{{< /bootstrap-table >}}
32-
33-
### Spec.Logging
34-
35-
{{< bootstrap-table "table table-striped table-bordered" >}}
36-
| name | description | type | required |
37-
|-------|------------------------------------------------------------------------|--------|----------|
38-
| level | Level defines the logging level. Supported values: info, debug, error. | string | no |
39-
{{< /bootstrap-table >}}
25+
**For a full list of configuration options that can be set, see the `NginxGateway spec` in the [API reference]({{< relref "reference/api.md" >}}).**
4026

4127
## Viewing and Updating the Configuration
4228

43-
{{< note >}} For the following examples, the name `nginx-gateway-config` should be updated to the name of the resource created for your installation. {{< /note >}}
29+
{{< note >}} For the following examples, the name `ngf-config` should be updated to the name of the resource created for your installation.{{< /note >}}
4430

45-
To view the current configuration:
31+
To view the current configuration and its status:
4632

4733
```shell
48-
kubectl -n nginx-gateway get nginxgateways nginx-gateway-config -o yaml
34+
kubectl -n nginx-gateway describe nginxgateways ngf-config
35+
```
36+
37+
```text
38+
...
39+
Status:
40+
Conditions:
41+
Last Transition Time: 2024-08-13T19:22:14Z
42+
Message: NginxGateway is valid
43+
Observed Generation: 1
44+
Reason: Valid
45+
Status: True
46+
Type: Valid
4947
```
5048

5149
To update the configuration:
5250

5351
```shell
54-
kubectl -n nginx-gateway edit nginxgateways nginx-gateway-config
52+
kubectl -n nginx-gateway edit nginxgateways ngf-config
5553
```
5654

5755
This will open the configuration in your default editor. You can then update and save the configuration, which is applied automatically to the control plane.
58-
59-
To view the status of the configuration:
60-
61-
```shell
62-
kubectl -n nginx-gateway describe nginxgateways nginx-gateway-config
63-
```

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: "Data plane configuration"
3+
weight: 400
4+
toc: true
5+
docs: "DOCS-000"
6+
---
7+
8+
Learn how to dynamically update the NGINX Gateway Fabric global data plane configuration.
9+
10+
## Overview
11+
12+
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, or changing the IP family.
13+
14+
The data plane configuration is stored in the NginxProxy custom resource, which is a cluster-scoped resource that is attached to the `nginx` GatewayClass.
15+
16+
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.
17+
18+
When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config`.
19+
20+
**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< relref "reference/api.md" >}}).**
21+
22+
{{<note>}}Some global configuration also requires an [associated policy]({{< relref "overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< relref "/how-to/monitoring/tracing.md" >}}), for example).{{</note>}}
23+
24+
## Viewing and Updating the Configuration
25+
26+
If the `NginxProxy` resource already exists, you can view and edit it.
27+
28+
{{< note >}} For the following examples, the name `ngf-proxy-config` should be updated to the name of the resource created for your installation.{{< /note >}}
29+
30+
To view the current configuration:
31+
32+
```shell
33+
kubectl describe nginxproxies ngf-proxy-config
34+
```
35+
36+
To update the configuration:
37+
38+
```shell
39+
kubectl edit nginxproxies ngf-proxy-config
40+
```
41+
42+
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.
43+
44+
To view the status of the configuration, check the GatewayClass that it is attached to:
45+
46+
```shell
47+
kubectl describe gatewayclasses nginx
48+
```
49+
50+
```text
51+
...
52+
Status:
53+
Conditions:
54+
...
55+
Message: parametersRef resource is resolved
56+
Observed Generation: 1
57+
Reason: ResolvedRefs
58+
Status: True
59+
Type: ResolvedRefs
60+
```
61+
62+
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.
63+
64+
## Manually Creating the Configuration
65+
66+
If the `NginxProxy` resource doesn't exist, you can create it and attach it to the GatewayClass.
67+
68+
The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`:
69+
70+
```yaml
71+
kubectl apply -f - <<EOF
72+
apiVersion: gateway.nginx.org/v1alpha1
73+
kind: NginxProxy
74+
metadata:
75+
name: ngf-proxy-config
76+
spec:
77+
ipFamily: ipv4
78+
EOF
79+
```
80+
81+
Now we need to attach it to the GatewayClass:
82+
83+
```shell
84+
kubectl edit gatewayclass nginx
85+
```
86+
87+
This will open your default editor, allowing you to add the following to the `spec`:
88+
89+
```yaml
90+
parametersRef:
91+
group: gateway.nginx.org
92+
kind: NginxProxy
93+
name: ngf-proxy-config
94+
```
95+
96+
After updating, you can check the status of the GatewayClass to see if the configuration is valid:
97+
98+
```shell
99+
kubectl describe gatewayclasses nginx
100+
```
101+
102+
```text
103+
...
104+
Status:
105+
Conditions:
106+
...
107+
Message: parametersRef resource is resolved
108+
Observed Generation: 1
109+
Reason: ResolvedRefs
110+
Status: True
111+
Type: ResolvedRefs
112+
```
113+
114+
If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status.

‎site/content/how-to/upgrade-apps-without-downtime.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Upgrade applications without downtime"
3-
weight: 400
3+
weight: 500
44
toc: true
55
docs: "DOCS-1420"
66
---

0 commit comments

Comments
 (0)