Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 88df8b9

Browse files
sjbermanbjee19ciarams87salonichf5ADubhlaoich
authoredMay 27, 2025
NGF: control plane/data plane split docs (#590)
NGF: Update documentation for control plane/data plane separation feature for the 2.0 release. Includes upgrade docs, new configurations, and new architecture. --------- Co-authored-by: bjee19 <[email protected]> Co-authored-by: Ciara Stacke <[email protected]> Co-authored-by: salonichf5 <[email protected]> Co-authored-by: Alan Dooley <[email protected]>
1 parent c8ed6bd commit 88df8b9

38 files changed

+1630
-807
lines changed
 

‎content/ngf/get-started.md

Lines changed: 61 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,10 @@ nodes:
4747
- containerPort: 31437
4848
hostPort: 8080
4949
protocol: TCP
50-
- containerPort: 31438
51-
hostPort: 8443
52-
protocol: TCP
5350
```
5451
5552
{{< note >}}
56-
The two _containerPort_ values are used to later configure a _NodePort_.
53+
The _containerPort_ value is used to later configure a _NodePort_.
5754
{{< /note >}}
5855
5956
Run the following command:
@@ -111,17 +108,20 @@ customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking
111108

112109
### Install the Helm chart
113110

114-
Use `helm` to install NGINX Gateway Fabric with the following command:
111+
Use `helm` to install NGINX Gateway Fabric, specifying the NodePort configuration that will be set on the
112+
NGINX Service when it is provisioned:
115113

116114
```shell
117-
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false
115+
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginx.service.type=NodePort --set-json 'nginx.service.nodePorts=[{"port":31437,"listenerPort":80}]'
118116
```
119117

118+
{{< note >}}
119+
The port value should equal the _containerPort_ value from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster). The _listenerPort_ value will match the port that we expose in the Gateway listener.
120+
{{< /note >}}
121+
120122
```text
121-
Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:{{< version-ngf >}}
122-
Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee
123123
NAME: ngf
124-
LAST DEPLOYED: Mon Oct 21 14:45:14 2024
124+
LAST DEPLOYED: Tue Apr 29 14:45:14 2025
125125
NAMESPACE: nginx-gateway
126126
STATUS: deployed
127127
REVISION: 1
@@ -130,59 +130,6 @@ TEST SUITE: None
130130

131131
---
132132

133-
### Set up a NodePort
134-
135-
Create the file _nodeport-config.yaml_ with the following contents:
136-
137-
```yaml {linenos=true, hl_lines=[20, 25]}
138-
apiVersion: v1
139-
kind: Service
140-
metadata:
141-
name: nginx-gateway
142-
namespace: nginx-gateway
143-
labels:
144-
app.kubernetes.io/name: nginx-gateway-fabric
145-
app.kubernetes.io/instance: ngf
146-
app.kubernetes.io/version: "{{< version-ngf >}}"
147-
spec:
148-
type: NodePort
149-
selector:
150-
app.kubernetes.io/name: nginx-gateway-fabric
151-
app.kubernetes.io/instance: ngf
152-
ports:
153-
- name: http
154-
port: 80
155-
protocol: TCP
156-
targetPort: 80
157-
nodePort: 31437
158-
- name: https
159-
port: 443
160-
protocol: TCP
161-
targetPort: 443
162-
nodePort: 31438
163-
```
164-
165-
{{< note >}}
166-
The highlighted _nodePort_ values should equal the _containerPort_ values from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster).
167-
{{< /note >}}
168-
169-
Apply it using `kubectl`:
170-
171-
```shell
172-
kubectl apply -f nodeport-config.yaml
173-
```
174-
```text
175-
service/nginx-gateway created
176-
```
177-
178-
{{< warning >}}
179-
The NodePort resource must be deployed in the same namespace as NGINX Gateway Fabric.
180-
181-
If you are making customizations, ensure your `labels:` and `selectors:` also match the labels of the NGINX Gateway Fabric deployment.
182-
{{< /warning >}}
183-
184-
---
185-
186133
## Create an example application
187134

188135
In the previous section, you deployed NGINX Gateway Fabric to a local cluster. This section shows you how to deploy a simple web application to test that NGINX Gateway Fabric works.
@@ -220,8 +167,8 @@ kubectl -n default get pods
220167

221168
```text
222169
NAME READY STATUS RESTARTS AGE
223-
coffee-6db967495b-wk2mm 1/1 Running 0 10s
224-
tea-7b7d6c947d-d4qcf 1/1 Running 0 10s
170+
coffee-676c9f8944-k2bmd 1/1 Running 0 9s
171+
tea-6fbfdcb95d-9lhbj 1/1 Running 0 9s
225172
```
226173

227174
---
@@ -242,6 +189,19 @@ kubectl apply -f gateway.yaml
242189
gateway.gateway.networking.k8s.io/gateway created
243190
```
244191

192+
Verify that the NGINX deployment has been provisioned:
193+
194+
```shell
195+
kubectl -n default get pods
196+
```
197+
198+
```text
199+
NAME READY STATUS RESTARTS AGE
200+
coffee-676c9f8944-k2bmd 1/1 Running 0 31s
201+
gateway-nginx-66b5d78f8f-4fmtb 1/1 Running 0 13s
202+
tea-6fbfdcb95d-9lhbj 1/1 Running 0 31s
203+
```
204+
245205
Create the file _cafe-routes.yaml_ with the following contents:
246206

247207
{{< ghcode `https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/cafe-routes.yaml`>}}
@@ -264,22 +224,21 @@ httproute.gateway.networking.k8s.io/tea created
264224
You can check that all of the expected services are available using `kubectl get`:
265225

266226
```shell
267-
kubectl get service --all-namespaces
227+
kubectl -n default get services
268228
```
269229

270230
```text
271-
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
272-
default coffee ClusterIP 10.96.18.163 <none> 80/TCP 2m51s
273-
default kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4m41s
274-
default tea ClusterIP 10.96.169.132 <none> 80/TCP 2m51s
275-
kube-system kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 4m40s
276-
nginx-gateway nginx-gateway NodePort 10.96.186.45 <none> 80:31437/TCP,443:31438/TCP 3m6s
231+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
232+
coffee ClusterIP 10.96.206.93 <none> 80/TCP 2m2s
233+
gateway-nginx NodePort 10.96.157.168 <none> 80:31437/TCP 104s
234+
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 142m
235+
tea ClusterIP 10.96.43.183 <none> 80/TCP 2m2s
277236
```
278237

279238
You can also use `kubectl describe` on the new resources to check their status:
280239

281240
```shell
282-
kubectl describe httproutes
241+
kubectl -n default describe httproutes
283242
```
284243

285244
```text
@@ -290,10 +249,10 @@ Annotations: <none>
290249
API Version: gateway.networking.k8s.io/v1
291250
Kind: HTTPRoute
292251
Metadata:
293-
Creation Timestamp: 2024-10-21T13:46:51Z
252+
Creation Timestamp: 2025-04-29T19:06:31Z
294253
Generation: 1
295-
Resource Version: 821
296-
UID: cc591089-d3aa-44d3-a851-e2bbfa285029
254+
Resource Version: 12285
255+
UID: c8055a74-b4c6-442f-b3fb-350fb88b2a7c
297256
Spec:
298257
Hostnames:
299258
cafe.example.com
@@ -316,13 +275,13 @@ Spec:
316275
Status:
317276
Parents:
318277
Conditions:
319-
Last Transition Time: 2024-10-21T13:46:51Z
278+
Last Transition Time: 2025-04-29T19:06:31Z
320279
Message: The route is accepted
321280
Observed Generation: 1
322281
Reason: Accepted
323282
Status: True
324283
Type: Accepted
325-
Last Transition Time: 2024-10-21T13:46:51Z
284+
Last Transition Time: 2025-04-29T19:06:31Z
326285
Message: All references are resolved
327286
Observed Generation: 1
328287
Reason: ResolvedRefs
@@ -345,10 +304,10 @@ Annotations: <none>
345304
API Version: gateway.networking.k8s.io/v1
346305
Kind: HTTPRoute
347306
Metadata:
348-
Creation Timestamp: 2024-10-21T13:46:51Z
307+
Creation Timestamp: 2025-04-29T19:06:31Z
349308
Generation: 1
350-
Resource Version: 823
351-
UID: d72d2a19-1c4d-48c4-9808-5678cff6c331
309+
Resource Version: 12284
310+
UID: 55aa0ab5-9b1c-4028-9bb5-4903f05bb998
352311
Spec:
353312
Hostnames:
354313
cafe.example.com
@@ -371,13 +330,13 @@ Spec:
371330
Status:
372331
Parents:
373332
Conditions:
374-
Last Transition Time: 2024-10-21T13:46:51Z
333+
Last Transition Time: 2025-04-29T19:06:31Z
375334
Message: The route is accepted
376335
Observed Generation: 1
377336
Reason: Accepted
378337
Status: True
379338
Type: Accepted
380-
Last Transition Time: 2024-10-21T13:46:51Z
339+
Last Transition Time: 2025-04-29T19:06:31Z
381340
Message: All references are resolved
382341
Observed Generation: 1
383342
Reason: ResolvedRefs
@@ -394,7 +353,7 @@ Events: <none>
394353
```
395354

396355
```shell
397-
kubectl describe gateways
356+
kubectl -n default describe gateways
398357
```
399358

400359
```text
@@ -405,10 +364,10 @@ Annotations: <none>
405364
API Version: gateway.networking.k8s.io/v1
406365
Kind: Gateway
407366
Metadata:
408-
Creation Timestamp: 2024-10-21T13:46:36Z
367+
Creation Timestamp: 2025-04-29T19:05:01Z
409368
Generation: 1
410-
Resource Version: 824
411-
UID: 2ae8ec42-70eb-41a4-b249-3e47177aea48
369+
Resource Version: 12286
370+
UID: 0baa6e15-55e0-405a-9e7c-de22472fc3ad
412371
Spec:
413372
Gateway Class Name: nginx
414373
Listeners:
@@ -422,15 +381,15 @@ Spec:
422381
Status:
423382
Addresses:
424383
Type: IPAddress
425-
Value: 10.244.0.5
384+
Value: 10.96.157.168
426385
Conditions:
427-
Last Transition Time: 2024-10-21T13:46:51Z
386+
Last Transition Time: 2025-04-29T19:06:31Z
428387
Message: Gateway is accepted
429388
Observed Generation: 1
430389
Reason: Accepted
431390
Status: True
432391
Type: Accepted
433-
Last Transition Time: 2024-10-21T13:46:51Z
392+
Last Transition Time: 2025-04-29T19:06:31Z
434393
Message: Gateway is programmed
435394
Observed Generation: 1
436395
Reason: Programmed
@@ -439,25 +398,25 @@ Status:
439398
Listeners:
440399
Attached Routes: 2
441400
Conditions:
442-
Last Transition Time: 2024-10-21T13:46:51Z
401+
Last Transition Time: 2025-04-29T19:06:31Z
443402
Message: Listener is accepted
444403
Observed Generation: 1
445404
Reason: Accepted
446405
Status: True
447406
Type: Accepted
448-
Last Transition Time: 2024-10-21T13:46:51Z
407+
Last Transition Time: 2025-04-29T19:06:31Z
449408
Message: Listener is programmed
450409
Observed Generation: 1
451410
Reason: Programmed
452411
Status: True
453412
Type: Programmed
454-
Last Transition Time: 2024-10-21T13:46:51Z
413+
Last Transition Time: 2025-04-29T19:06:31Z
455414
Message: All references are resolved
456415
Observed Generation: 1
457416
Reason: ResolvedRefs
458417
Status: True
459418
Type: ResolvedRefs
460-
Last Transition Time: 2024-10-21T13:46:51Z
419+
Last Transition Time: 2025-04-29T19:06:31Z
461420
Message: No conflicts
462421
Observed Generation: 1
463422
Reason: NoConflicts
@@ -476,7 +435,7 @@ Events: <none>
476435

477436
## Test NGINX Gateway Fabric
478437

479-
By configuring the cluster with the ports `31437` and `31438`, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service.
438+
By configuring the cluster with the port `31437`, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service.
480439

481440
You can use `curl` to test the new services by targeting the hostname (_cafe.example.com_) with the _/coffee_ and _/tea_ paths:
482441

@@ -485,23 +444,23 @@ curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coff
485444
```
486445

487446
```text
488-
Server address: 10.244.0.6:8080
489-
Server name: coffee-6db967495b-wk2mm
490-
Date: 21/Oct/2024:13:52:13 +0000
447+
Server address: 10.244.0.16:8080
448+
Server name: coffee-676c9f8944-k2bmd
449+
Date: 29/Apr/2025:19:08:21 +0000
491450
URI: /coffee
492-
Request ID: fb226a54fd94f927b484dd31fb30e747
451+
Request ID: f34e138922171977a79b1b0d0395b97e
493452
```
494453

495454
```shell
496455
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/tea
497456
```
498457

499458
```text
500-
Server address: 10.244.0.7:8080
501-
Server name: tea-7b7d6c947d-d4qcf
502-
Date: 21/Oct/2024:13:52:17 +0000
459+
Server address: 10.244.0.17:8080
460+
Server name: tea-6fbfdcb95d-9lhbj
461+
Date: 29/Apr/2025:19:08:31 +0000
503462
URI: /tea
504-
Request ID: 43882f2f5794a1ee05d2ea017a035ce3
463+
Request ID: 1b5c8f3a4532ea7d7510cf14ffeb27af
505464
```
506465

507466
---

‎content/ngf/how-to/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
22
title: "How-to guides"
33
url: /nginx-gateway-fabric/how-to/
4-
weight: 400
4+
weight: 500
55
---

0 commit comments

Comments
 (0)
Please sign in to comment.