Skip to content

Commit 418e0f4

Browse files
ADubhlaoichADubhlaoich
committed
Add new "Get started" document
This commit adds a new "Get started" document for NGINX Gateway Fabric. It re-orders the top level page so that it is second after "Overview" as a means to get a reader started as quickly as possible, and is a combination of the existing kind guide, a Helm installation path and the cafe-example on GitHub. As part of this work, the original kind guide has been deleted: the only context lost is regarding port forwarding, which this new document mentions not requiring. The README for the cafe-example could also be stripped down as a result: the step "skipped" regards how to use a different hostname. Both of these could instead be added to a general network configuration document.
1 parent 3a08fda commit 418e0f4

File tree

9 files changed

+320
-130
lines changed

9 files changed

+320
-130
lines changed

‎site/content/get-started.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
---
2+
title: Get started
3+
toc: true
4+
weight: 200
5+
docs: DOCS-000
6+
---
7+
8+
This is a guide for getting started with NGINX Gateway Fabric. It explains how to:
9+
10+
- Set up a [kind (Kubernetes in Docker)](https://kind.sigs.k8s.io/) cluster
11+
- Install [NGINX Gateway Fabric](https://blog.nginx.org/blog/5-things-to-know-about-nginx-gateway-fabric) with [NGINX](https://nginx.org/)
12+
- Test NGINX Gateway Fabric with an example application
13+
14+
By following the steps in order, you will finish with a functional NGINX Gateway Fabric cluster.
15+
16+
---
17+
18+
## Before you begin
19+
20+
To complete this guide, you need the following prerequisites installed:
21+
22+
- [Go 1.16](https://go.dev/dl/) or newer, which is used by kind
23+
- [Docker](https://docs.docker.com/get-started/get-docker/), for creating and managing containers
24+
- [kind](https://kind.sigs.k8s.io/#installation-and-usage), which allows for running a local Kubernetes cluster using Docker
25+
- [kubectl](https://kubernetes.io/docs/tasks/tools/), which provides a command line interface (CLI) for interacting with Kubernetes clusters
26+
- [Helm 3.0](https://helm.sh/docs/intro/install/) or newer to install NGINX Gateway Fabric
27+
- [curl](https://curl.se/), to test the example application
28+
29+
## Set up a kind cluster
30+
31+
Create the file _cluster-config.yaml_ with the following contents, noting the highlighted lines:
32+
33+
```yaml {linenos=true, hl_lines=[6, 9]}
34+
apiVersion: kind.x-k8s.io/v1alpha4
35+
kind: Cluster
36+
nodes:
37+
- role: control-plane
38+
extraPortMappings:
39+
- containerPort: 31437
40+
hostPort: 8080
41+
protocol: TCP
42+
- containerPort: 31438
43+
hostPort: 8443
44+
protocol: TCP
45+
```
46+
47+
{{< warning >}}
48+
Take note of the two _containerPort_ values. They are necessary for later configuring a _NodePort_.
49+
{{< /warning >}}
50+
51+
Run the following command:
52+
53+
```shell
54+
kind create cluster --config cluster-config.yaml
55+
```
56+
```text
57+
Creating cluster "kind" ...
58+
✓ Ensuring node image (kindest/node:v1.31.0) 🖼
59+
✓ Preparing nodes 📦
60+
✓ Writing configuration 📜
61+
✓ Starting control-plane 🕹️
62+
✓ Installing CNI 🔌
63+
✓ Installing StorageClass 💾
64+
Set kubectl context to "kind-kind"
65+
You can now use your cluster with:
66+
67+
kubectl cluster-info --context kind-kind
68+
69+
Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
70+
```
71+
72+
{{< note >}}
73+
If you have cloned [the NGINX Gateway Fabric repository](https://github.com/nginxinc/nginx-gateway-fabric/tree/main), you can also create a kind cluster from the root folder with the following *make* command:
74+
75+
```shell
76+
make create-kind-cluster
77+
```
78+
{{< /note >}}
79+
80+
---
81+
82+
## Install NGINX Gateway Fabric
83+
84+
### Add Gateway API resources
85+
86+
Use `kubectl` to add the API resources for NGINX Gateway Fabric with the following command:
87+
88+
```shell
89+
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.4.0" | kubectl apply -f -
90+
```
91+
```text
92+
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created
93+
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created
94+
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created
95+
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created
96+
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
97+
```
98+
99+
{{< note >}}
100+
To use experimental features, you'll need to install the API resources from the experimental channel instead.
101+
102+
```shell
103+
kubectl kustomize "https://github.com/nginxinc/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.4.0" | kubectl apply -f -
104+
```
105+
{{< /note >}}
106+
107+
---
108+
109+
### Install the Helm chart
110+
111+
Use `helm` to install NGINX Gateway Fabric with the following command:
112+
113+
```shell
114+
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false
115+
```
116+
```text
117+
Pulled: ghcr.io/nginxinc/charts/nginx-gateway-fabric:1.4.0
118+
Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee
119+
NAME: ngf
120+
LAST DEPLOYED: Fri Oct 11 16:57:20 2024
121+
NAMESPACE: nginx-gateway
122+
STATUS: deployed
123+
REVISION: 1
124+
TEST SUITE: None
125+
```
126+
127+
{{< note >}}
128+
If you installed the API resources from the experimental channel during the last step, you will need to enable the _nginxGateway.gwAPIExperimentalFeatures_ option:
129+
130+
```shell
131+
helm install ngf oci://ghcr.io/nginxinc/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false --set nginxGateway.gwAPIExperimentalFeatures.enable=true
132+
```
133+
{{< /note >}}
134+
135+
---
136+
137+
### Set up a NodePort
138+
139+
Create the file _nodeport-config.yaml_ with the following contents:
140+
141+
{{< note >}}
142+
The highlighted _nodePort_ values should equal the _containerPort_ values from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster).
143+
{{< /note >}}
144+
145+
```yaml {linenos=true, hl_lines=[20, 25]}
146+
apiVersion: v1
147+
kind: Service
148+
metadata:
149+
name: nginx-gateway
150+
namespace: nginx-gateway
151+
labels:
152+
app.kubernetes.io/name: nginx-gateway-fabric
153+
app.kubernetes.io/instance: ngf
154+
app.kubernetes.io/version: "1.4.0"
155+
spec:
156+
type: NodePort
157+
selector:
158+
app.kubernetes.io/name: nginx-gateway-fabric
159+
app.kubernetes.io/instance: ngf
160+
ports:
161+
- name: http
162+
port: 80
163+
protocol: TCP
164+
targetPort: 80
165+
nodePort: 31437
166+
- name: https
167+
port: 443
168+
protocol: TCP
169+
targetPort: 443
170+
nodePort: 31438
171+
```
172+
173+
Apply it using `kubectl`:
174+
175+
```shell
176+
kubectl apply -f nodeport-config.yaml
177+
```
178+
```text
179+
service/nginx-gateway created
180+
```
181+
182+
{{< warning >}}
183+
The NodePort resource must be deployed in the same namespace as NGINX Gateway Fabric.
184+
185+
If you are making customizations, ensure your `labels:` and `selectors:` also match.
186+
{{< /warning >}}
187+
188+
---
189+
190+
191+
## Create an example application
192+
193+
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.
194+
195+
{{< note >}}
196+
The YAML code in the following sections can be founded in the [cafe-example folder](https://github.com/nginxinc/nginx-gateway-fabric/tree/main/examples/cafe-example) of the GitHub repository.
197+
{{< /note >}}
198+
199+
---
200+
201+
### Create the application resources
202+
203+
Create the file _cafe.yaml_ with the following contents:
204+
205+
{{< ghcode "https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/cafe.yaml">}}
206+
207+
Apply it:
208+
209+
```shell
210+
kubectl apply -f cafe.yaml
211+
```
212+
```text
213+
deployment.apps/coffee created
214+
service/coffee created
215+
deployment.apps/tea created
216+
service/tea created
217+
```
218+
219+
Verify that the new pods are in the `default` namespace:
220+
221+
```shell
222+
kubectl -n default get pods
223+
```
224+
```text
225+
NAME READY STATUS RESTARTS AGE
226+
coffee-6db967495b-dvg5w 1/1 Running 0 80s
227+
tea-7b7d6c947d-8xmhm 1/1 Running 0 80s
228+
```
229+
230+
---
231+
232+
### Create Gateway and HTTPRoute resources
233+
234+
Create the file _gateway.yaml_ with the following contents:
235+
236+
{{< ghcode "https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/gateway.yaml">}}
237+
238+
Apply it using `kubectl`:
239+
240+
```shell
241+
kubectl apply -f gateway.yaml
242+
```
243+
```text
244+
gateway.gateway.networking.k8s.io/gateway created
245+
```
246+
247+
Create the file _cafe-routes.yaml_ with the following contents:
248+
249+
{{< ghcode "https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/cafe-routes.yaml">}}
250+
251+
Apply it using `kubectl`:
252+
253+
```shell
254+
kubectl apply -f cafe-routes.yaml
255+
```
256+
```text
257+
httproute.gateway.networking.k8s.io/coffee created
258+
httproute.gateway.networking.k8s.io/tea created
259+
```
260+
261+
You can check that all of the expected services are available using `kubectl get`:
262+
263+
```shell
264+
kubectl get service --all-namespaces
265+
```
266+
```text
267+
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
268+
default coffee ClusterIP 10.96.18.163 <none> 80/TCP 2m51s
269+
default kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4m41s
270+
default tea ClusterIP 10.96.169.132 <none> 80/TCP 2m51s
271+
kube-system kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 4m40s
272+
nginx-gateway nginx-gateway NodePort 10.96.186.45 <none> 80:31437/TCP,443:31438/TCP 3m6s
273+
```
274+
275+
---
276+
277+
## Test NGINX Gateway Fabric
278+
279+
The cluster was configured with port `8080` as the `containerPort` value, alongside the `nodePort` value of the NodePort service.
280+
281+
Since the NodePort `targetPort` values match the _tea_ and _coffee_ service `port` values, no port forwarding is required.
282+
283+
You can use `curl` to test the new services by targeting the hostname (_cafe.example.com_) with the _/coffee_ and _/tea_ paths:
284+
285+
```shell
286+
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee
287+
```
288+
```text
289+
Server address: 10.244.0.6:8080
290+
Server name: coffee-6db967495b-984mx
291+
Date: 17/Oct/2024:15:50:22 +0000
292+
URI: /coffee
293+
Request ID: 8ad83b06ea42b996ad6bd28032b38e28
294+
```
295+
296+
```shell
297+
curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee
298+
```
299+
```text
300+
Server address: 10.244.0.6:8080
301+
Server name: coffee-6db967495b-984mx
302+
Date: 17/Oct/2024:15:50:29 +0000
303+
URI: /coffee
304+
Request ID: 2dfc85564dd5b5dad7e62b980bb60ee1
305+
```
306+
307+
---
308+
309+
## Additional reading
310+
311+
- [Install NGINX Gateway Fabric](http://localhost:1313/nginx-gateway-fabric/installation/installing-ngf/), for additional ways to install NGINX Gateway Fabric
312+
- [How-to guides](http://localhost:1313/nginx-gateway-fabric/how-to/), for configuring your cluster

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
---
22
title: "How-to guides"
3-
weight: 300
3+
weight: 400
44
---

‎site/content/installation/_index.md‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
11
---
22
title: "Installation"
3-
description:
4-
weight: 200
5-
linkTitle: "Installation"
6-
menu:
7-
docs:
8-
parent: NGINX Gateway Fabric
3+
weight: 300
94
---

0 commit comments

Comments
 (0)