Skip to content

Commit b15d47e

Browse files
sjbermansjberman
authored
NGF: update Get started guide (#479)
The getting started guide needs to change with the new NGF architecture, specifically regarding the NodePorts. The user no longer needs to create the Service, and instead specifies configuration at installation time.
1 parent 2c9d188 commit b15d47e

File tree

1 file changed

+61
-102
lines changed

1 file changed

+61
-102
lines changed

‎content/ngf/get-started.md

+61-102
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
---

0 commit comments

Comments
 (0)