Skip to content

Commit 01c86c8

Browse files
authored
feat: Update NGF Get started guide and installation documents (#224)
This commit adds explicit guidance at the top of the Get started guide, directing the reader towards the Installation section for a production deployment. It also removes mention of the experimental channel, which is an unnecessary use case for trying NGF. It also creates uniformity in the Helm and Manifest deployment documentation, by matching how sections are formatted, and creating an include file for identical instructions on upgrading the API resources.
1 parent 396f608 commit 01c86c8

File tree

4 files changed

+60
-82
lines changed

4 files changed

+60
-82
lines changed
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
docs: DOCS-000
3+
---
4+
5+
To upgrade your Gateway API resources, take the following steps:
6+
7+
- Use [Technical specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) to verify your Gateway API resources are compatible with your NGINX Gateway Fabric version.
8+
- Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information.
9+
10+
To upgrade the Gateway API resources, run the following command:
11+
12+
```shell
13+
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v{{< version-ngf >}}" | kubectl apply -f -
14+
```
15+
16+
If you installed NGINX Gateway the from the experimental channel, use this instead:
17+
18+
```shell
19+
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v{{< version-ngf >}}" | kubectl apply -f -
20+
```

content/ngf/get-started.md

Lines changed: 14 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ product: NGF
77
docs: DOCS-000
88
---
99

10+
{{< important >}}
11+
This document is for trying out NGINX Gateway Fabric, and not intended for a production environment.
12+
13+
For standard deployments, you should read the [Install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}) section.
14+
{{< /important >}}
15+
1016
This is a guide for getting started with NGINX Gateway Fabric. It explains how to:
1117

1218
- Set up a [kind (Kubernetes in Docker)](https://kind.sigs.k8s.io/) cluster
@@ -46,9 +52,9 @@ nodes:
4652
protocol: TCP
4753
```
4854
49-
{{< warning >}}
50-
Take note of the two _containerPort_ values. They are necessary for later configuring a _NodePort_.
51-
{{< /warning >}}
55+
{{< note >}}
56+
The two _containerPort_ values are used to later configure a _NodePort_.
57+
{{< /note >}}
5258
5359
Run the following command:
5460
@@ -101,15 +107,6 @@ customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.
101107
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
102108
```
103109

104-
{{< note >}}
105-
To use experimental features, you'll need to install the API resources from the experimental channel instead.
106-
107-
```shell
108-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v{{< version-ngf >}}" | kubectl apply -f -
109-
```
110-
111-
{{< /note >}}
112-
113110
---
114111

115112
### Install the Helm chart
@@ -131,25 +128,12 @@ REVISION: 1
131128
TEST SUITE: None
132129
```
133130

134-
{{< note >}}
135-
If you installed the API resources from the experimental channel during the last step, you will need to enable the _nginxGateway.gwAPIExperimentalFeatures_ option:
136-
137-
```shell
138-
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false --set nginxGateway.gwAPIExperimentalFeatures.enable=true
139-
```
140-
141-
{{< /note >}}
142-
143131
---
144132

145133
### Set up a NodePort
146134

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

149-
{{< note >}}
150-
The highlighted _nodePort_ values should equal the _containerPort_ values from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster).
151-
{{< /note >}}
152-
153137
```yaml {linenos=true, hl_lines=[20, 25]}
154138
apiVersion: v1
155139
kind: Service
@@ -178,20 +162,23 @@ spec:
178162
nodePort: 31438
179163
```
180164
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+
181169
Apply it using `kubectl`:
182170

183171
```shell
184172
kubectl apply -f nodeport-config.yaml
185173
```
186-
187174
```text
188175
service/nginx-gateway created
189176
```
190177

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

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

197184
---

content/ngf/installation/installing-ngf/helm.md

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,6 @@ docs: DOCS-1430
1111

1212
Learn how to install, upgrade, and uninstall NGINX Gateway Fabric in a Kubernetes cluster using Helm.
1313

14-
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
15-
Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=<secret-name>` when running `helm upgrade`. {{< /important >}}
16-
1714
---
1815

1916
## Before you begin
@@ -30,15 +27,15 @@ To complete this guide, you'll need to install:
3027

3128
{{< include "/ngf/installation/jwt-password-note.md" >}}
3229

33-
### 1. Download the JWT from MyF5
30+
### Download the JWT from MyF5
3431

3532
{{< include "/ngf/installation/nginx-plus/download-jwt.md" >}}
3633

37-
### 2. Create the Docker Registry Secret
34+
### Create the Docker Registry Secret
3835

3936
{{< include "/ngf/installation/nginx-plus/docker-registry-secret.md" >}}
4037

41-
### 3. Create the NGINX Plus Secret
38+
### Create the NGINX Plus Secret
4239

4340
{{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}}
4441

@@ -187,29 +184,18 @@ You can find several examples of configuration options of the `values.yaml` file
187184

188185
## Upgrade NGINX Gateway Fabric
189186

190-
{{<tip>}}For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below.{{</tip>}}
187+
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
188+
Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=<secret-name>` when running `helm upgrade`. {{< /important >}}
189+
190+
{{< tip >}} For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below. {{< /tip >}}
191191

192192
To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps:
193193

194194
---
195195

196196
### Upgrade Gateway resources
197197

198-
To upgrade your Gateway API resources, take the following steps:
199-
200-
- Verify the Gateway API resources are compatible with your NGINX Gateway Fabric version. Refer to the [Technical Specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) for details.
201-
- Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information.
202-
- To upgrade the Gateway API resources, run:
203-
204-
```shell
205-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v{{< version-ngf >}}" | kubectl apply -f -
206-
```
207-
208-
or, if you installed the from the experimental channel:
209-
210-
```shell
211-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v{{< version-ngf >}}" | kubectl apply -f -
212-
```
198+
{{< include "/ngf/installation/upgrade-api-resources.md" >}}
213199

214200
---
215201

content/ngf/installation/installing-ngf/manifests.md

Lines changed: 18 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Installation with Kubernetes manifests
2+
title: Installation with Manifests
33
weight: 200
44
toc: true
55
type: how-to
@@ -11,9 +11,6 @@ docs: DOCS-1429
1111

1212
Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernetes manifests.
1313

14-
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
15-
Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret, which is referenced in the updated deployment manifest for the newest version. {{< /important >}}
16-
1714
---
1815

1916
## Before you begin
@@ -29,15 +26,15 @@ To complete this guide, you'll need to install:
2926

3027
{{< include "/ngf/installation/jwt-password-note.md" >}}
3128

32-
### 1. Download the JWT from MyF5
29+
### Download the JWT from MyF5
3330

3431
{{< include "/ngf/installation/nginx-plus/download-jwt.md" >}}
3532

36-
### 2. Create the Docker Registry Secret
33+
### Create the Docker Registry Secret
3734

3835
{{< include "/ngf/installation/nginx-plus/docker-registry-secret.md" >}}
3936

40-
### 3. Create the NGINX Plus Secret
37+
### Create the NGINX Plus Secret
4138

4239
{{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}}
4340

@@ -53,13 +50,13 @@ Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps.
5350

5451
---
5552

56-
### 1. Install the Gateway API resources
53+
### Install the Gateway API resources
5754

5855
{{< include "/ngf/installation/install-gateway-api-resources.md" >}}
5956

6057
---
6158

62-
### 2. Deploy the NGINX Gateway Fabric CRDs
59+
### Deploy the NGINX Gateway Fabric CRDs
6360

6461
#### Stable release
6562

@@ -75,7 +72,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/ma
7572

7673
---
7774

78-
### 3. Deploy NGINX Gateway Fabric
75+
### Deploy NGINX Gateway Fabric
7976

8077
{{< note >}} By default, NGINX Gateway Fabric is installed in the **nginx-gateway** namespace. You can deploy in another namespace by modifying the manifest files. {{< /note >}}
8178

@@ -173,7 +170,7 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{
173170

174171
---
175172

176-
### 4. Verify the Deployment
173+
### Verify the Deployment
177174

178175
To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace:
179176

@@ -190,7 +187,7 @@ nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s
190187

191188
---
192189

193-
### 5. Access NGINX Gateway Fabric
190+
### Access NGINX Gateway Fabric
194191

195192
{{< include "/ngf/installation/expose-nginx-gateway-fabric.md" >}}
196193

@@ -205,33 +202,21 @@ Secret before upgrading. Follow the steps in the [Before you begin](#before-you-
205202

206203
To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps:
207204

208-
1. **Upgrade Gateway API resources:**
209-
210-
- Verify that your NGINX Gateway Fabric version is compatible with the Gateway API resources. Refer to the [Technical Specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) for details.
211-
- Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information.
212-
- To upgrade the Gateway API resources, run:
205+
### Upgrade Gateway API resources
213206

214-
```shell
215-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v{{< version-ngf >}}" | kubectl apply -f -
216-
```
207+
{{< include "/ngf/installation/upgrade-api-resources.md" >}}
217208

218-
or, if you installed the from the experimental channel:
209+
### Upgrade NGINX Gateway Fabric CRDs
219210

220-
```shell
221-
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v{{< version-ngf >}}" | kubectl apply -f -
222-
```
211+
To upgrade the Custom Resource Definitions (CRDs), run:
223212

224-
1. **Upgrade NGINX Gateway Fabric CRDs:**
225-
226-
- To upgrade the Custom Resource Definitions (CRDs), run:
227-
228-
```shell
229-
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
230-
```
213+
```shell
214+
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
215+
```
231216

232-
1. **Upgrade NGINX Gateway Fabric deployment:**
217+
### Upgrade NGINX Gateway Fabric deployment
233218

234-
Select the deployment manifest that matches your current deployment from the table above in the [Deploy NGINX Gateway Fabric](#3-deploy-nginx-gateway-fabric) section and apply it.
219+
Select the deployment manifest that matches your current deployment from the table above in the [Deploy NGINX Gateway Fabric](#deploy-nginx-gateway-fabric) section and apply it.
235220

236221
---
237222

0 commit comments

Comments
 (0)