Skip to content

NGF: update Get started guide #479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 30, 2025
Merged

NGF: update Get started guide #479

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 61 additions & 102 deletions content/ngf/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,10 @@ nodes:
- containerPort: 31437
hostPort: 8080
protocol: TCP
- containerPort: 31438
hostPort: 8443
protocol: TCP
```

{{< note >}}
The two _containerPort_ values are used to later configure a _NodePort_.
The _containerPort_ value is used to later configure a _NodePort_.
{{< /note >}}

Run the following command:
Expand Down Expand Up @@ -111,17 +108,20 @@ customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking

### Install the Helm chart

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

```shell
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false
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}]'
```

{{< note >}}
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.
{{< /note >}}

```text
Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:{{< version-ngf >}}
Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee
NAME: ngf
LAST DEPLOYED: Mon Oct 21 14:45:14 2024
LAST DEPLOYED: Tue Apr 29 14:45:14 2025
NAMESPACE: nginx-gateway
STATUS: deployed
REVISION: 1
Expand All @@ -130,59 +130,6 @@ TEST SUITE: None

---

### Set up a NodePort

Create the file _nodeport-config.yaml_ with the following contents:

```yaml {linenos=true, hl_lines=[20, 25]}
apiVersion: v1
kind: Service
metadata:
name: nginx-gateway
namespace: nginx-gateway
labels:
app.kubernetes.io/name: nginx-gateway-fabric
app.kubernetes.io/instance: ngf
app.kubernetes.io/version: "{{< version-ngf >}}"
spec:
type: NodePort
selector:
app.kubernetes.io/name: nginx-gateway-fabric
app.kubernetes.io/instance: ngf
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
nodePort: 31437
- name: https
port: 443
protocol: TCP
targetPort: 443
nodePort: 31438
```

{{< note >}}
The highlighted _nodePort_ values should equal the _containerPort_ values from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster).
{{< /note >}}

Apply it using `kubectl`:

```shell
kubectl apply -f nodeport-config.yaml
```
```text
service/nginx-gateway created
```

{{< warning >}}
The NodePort resource must be deployed in the same namespace as NGINX Gateway Fabric.

If you are making customizations, ensure your `labels:` and `selectors:` also match the labels of the NGINX Gateway Fabric deployment.
{{< /warning >}}

---

## Create an example application

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.
Expand Down Expand Up @@ -220,8 +167,8 @@ kubectl -n default get pods

```text
NAME READY STATUS RESTARTS AGE
coffee-6db967495b-wk2mm 1/1 Running 0 10s
tea-7b7d6c947d-d4qcf 1/1 Running 0 10s
coffee-676c9f8944-k2bmd 1/1 Running 0 9s
tea-6fbfdcb95d-9lhbj 1/1 Running 0 9s
```

---
Expand All @@ -242,6 +189,19 @@ kubectl apply -f gateway.yaml
gateway.gateway.networking.k8s.io/gateway created
```

Verify that the NGINX deployment has been provisioned:

```shell
kubectl -n default get pods
```

```text
NAME READY STATUS RESTARTS AGE
coffee-676c9f8944-k2bmd 1/1 Running 0 31s
gateway-nginx-66b5d78f8f-4fmtb 1/1 Running 0 13s
tea-6fbfdcb95d-9lhbj 1/1 Running 0 31s
```

Create the file _cafe-routes.yaml_ with the following contents:

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

```shell
kubectl get service --all-namespaces
kubectl -n default get services
```

```text
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
default coffee ClusterIP 10.96.18.163 <none> 80/TCP 2m51s
default kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4m41s
default tea ClusterIP 10.96.169.132 <none> 80/TCP 2m51s
kube-system kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 4m40s
nginx-gateway nginx-gateway NodePort 10.96.186.45 <none> 80:31437/TCP,443:31438/TCP 3m6s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
coffee ClusterIP 10.96.206.93 <none> 80/TCP 2m2s
gateway-nginx NodePort 10.96.157.168 <none> 80:31437/TCP 104s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 142m
tea ClusterIP 10.96.43.183 <none> 80/TCP 2m2s
```

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

```shell
kubectl describe httproutes
kubectl -n default describe httproutes
```

```text
Expand All @@ -290,10 +249,10 @@ Annotations: <none>
API Version: gateway.networking.k8s.io/v1
Kind: HTTPRoute
Metadata:
Creation Timestamp: 2024-10-21T13:46:51Z
Creation Timestamp: 2025-04-29T19:06:31Z
Generation: 1
Resource Version: 821
UID: cc591089-d3aa-44d3-a851-e2bbfa285029
Resource Version: 12285
UID: c8055a74-b4c6-442f-b3fb-350fb88b2a7c
Spec:
Hostnames:
cafe.example.com
Expand All @@ -316,13 +275,13 @@ Spec:
Status:
Parents:
Conditions:
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: The route is accepted
Observed Generation: 1
Reason: Accepted
Status: True
Type: Accepted
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: All references are resolved
Observed Generation: 1
Reason: ResolvedRefs
Expand All @@ -345,10 +304,10 @@ Annotations: <none>
API Version: gateway.networking.k8s.io/v1
Kind: HTTPRoute
Metadata:
Creation Timestamp: 2024-10-21T13:46:51Z
Creation Timestamp: 2025-04-29T19:06:31Z
Generation: 1
Resource Version: 823
UID: d72d2a19-1c4d-48c4-9808-5678cff6c331
Resource Version: 12284
UID: 55aa0ab5-9b1c-4028-9bb5-4903f05bb998
Spec:
Hostnames:
cafe.example.com
Expand All @@ -371,13 +330,13 @@ Spec:
Status:
Parents:
Conditions:
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: The route is accepted
Observed Generation: 1
Reason: Accepted
Status: True
Type: Accepted
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: All references are resolved
Observed Generation: 1
Reason: ResolvedRefs
Expand All @@ -394,7 +353,7 @@ Events: <none>
```

```shell
kubectl describe gateways
kubectl -n default describe gateways
```

```text
Expand All @@ -405,10 +364,10 @@ Annotations: <none>
API Version: gateway.networking.k8s.io/v1
Kind: Gateway
Metadata:
Creation Timestamp: 2024-10-21T13:46:36Z
Creation Timestamp: 2025-04-29T19:05:01Z
Generation: 1
Resource Version: 824
UID: 2ae8ec42-70eb-41a4-b249-3e47177aea48
Resource Version: 12286
UID: 0baa6e15-55e0-405a-9e7c-de22472fc3ad
Spec:
Gateway Class Name: nginx
Listeners:
Expand All @@ -422,15 +381,15 @@ Spec:
Status:
Addresses:
Type: IPAddress
Value: 10.244.0.5
Value: 10.96.157.168
Conditions:
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: Gateway is accepted
Observed Generation: 1
Reason: Accepted
Status: True
Type: Accepted
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: Gateway is programmed
Observed Generation: 1
Reason: Programmed
Expand All @@ -439,25 +398,25 @@ Status:
Listeners:
Attached Routes: 2
Conditions:
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: Listener is accepted
Observed Generation: 1
Reason: Accepted
Status: True
Type: Accepted
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: Listener is programmed
Observed Generation: 1
Reason: Programmed
Status: True
Type: Programmed
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: All references are resolved
Observed Generation: 1
Reason: ResolvedRefs
Status: True
Type: ResolvedRefs
Last Transition Time: 2024-10-21T13:46:51Z
Last Transition Time: 2025-04-29T19:06:31Z
Message: No conflicts
Observed Generation: 1
Reason: NoConflicts
Expand All @@ -476,7 +435,7 @@ Events: <none>

## Test NGINX Gateway Fabric

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.
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.

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

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

```text
Server address: 10.244.0.6:8080
Server name: coffee-6db967495b-wk2mm
Date: 21/Oct/2024:13:52:13 +0000
Server address: 10.244.0.16:8080
Server name: coffee-676c9f8944-k2bmd
Date: 29/Apr/2025:19:08:21 +0000
URI: /coffee
Request ID: fb226a54fd94f927b484dd31fb30e747
Request ID: f34e138922171977a79b1b0d0395b97e
```

```shell
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/tea
```

```text
Server address: 10.244.0.7:8080
Server name: tea-7b7d6c947d-d4qcf
Date: 21/Oct/2024:13:52:17 +0000
Server address: 10.244.0.17:8080
Server name: tea-6fbfdcb95d-9lhbj
Date: 29/Apr/2025:19:08:31 +0000
URI: /tea
Request ID: 43882f2f5794a1ee05d2ea017a035ce3
Request ID: 1b5c8f3a4532ea7d7510cf14ffeb27af
```

---
Expand Down
Loading