Skip to content

Commit 872844c

Browse files
ADubhlaoichADubhlaoich
committed
feat: Make upgrade a standalone topic, consolidate existing information
1 parent b16d532 commit 872844c

File tree

6 files changed

+308
-395
lines changed

6 files changed

+308
-395
lines changed

‎_banners/ngf-2.0-release.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{{< banner "notice" "NGINX Gateway Fabric 2.0 is now available" >}}
22

3-
NGINX Gateway Fabric 2.0 has released! Follow [this guide]({{< ref "/ngf/install/upgrade-2.0" >}}) to upgrade from 1.x to 2.0.
3+
NGINX Gateway Fabric 2.0 has released! Follow [these instructions]({{< ref "/ngf/install/upgrade-version.md#upgrade-from-v1x-to-v2x" >}}) to upgrade from 1.x to 2.0.
44

5-
For 1.x, checkout [an older version](https://github.com/nginx/nginx-gateway-fabric/tree/release-1.6) of documentation.
5+
For 1.x, checkout [an older version]({{< ref "/ngf/install/upgrade-version.md#access-nginx-gateway-fabric-1x-documentation" >}}) of documentation.
66

77
{{< /banner >}}

‎content/includes/ngf/installation/helm/pulling-the-chart.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,9 @@
22
docs: "DOCS-1439"
33
---
44

5-
Pull the latest stable release of the NGINX Gateway Fabric chart:
5+
```shell
6+
helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar
7+
cd nginx-gateway-fabric
8+
```
69

7-
```shell
8-
helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar
9-
cd nginx-gateway-fabric
10-
```
11-
12-
If you want the latest version from the **main** branch, add `--version 0.0.0-edge` to your pull command.
10+
For the latest version from the **main** branch, add _--version 0.0.0-edge_ to your pull command.

‎content/ngf/install/helm.md‎

Lines changed: 0 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +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-
---
1514

1615
## Before you begin
1716

@@ -44,15 +43,12 @@ To complete this guide, you will need:
4443

4544
</details>
4645

47-
---
48-
4946
## Deploy NGINX Gateway Fabric
5047

5148
### Installing the Gateway API resources
5249

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

55-
---
5652

5753
### Install from the OCI registry
5854

@@ -94,8 +90,6 @@ To wait for the Deployment to be ready, you can either add the `--wait` flag to
9490
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
9591
```
9692

97-
---
98-
9993
### Install from sources {#install-from-sources}
10094

10195
If you prefer to install directly from sources, instead of through the OCI helm registry, use the following steps.
@@ -136,8 +130,6 @@ To wait for the Deployment to be ready, you can either add the `--wait` flag to
136130
kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available
137131
```
138132

139-
---
140-
141133
### Custom installation options
142134

143135
#### Service type
@@ -150,8 +142,6 @@ To use a NodePort Service instead:
150142
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginx.service.type=NodePort
151143
```
152144

153-
---
154-
155145
#### Experimental features
156146

157147
We support a subset of the additional features provided by the Gateway API experimental channel. To enable the
@@ -163,159 +153,15 @@ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namesp
163153

164154
{{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}}
165155

166-
---
167156

168157
#### Examples
169158

170159
You can find several examples of configuration options of the `values.yaml` file in the [helm examples](https://github.com/nginx/nginx-gateway-fabric/tree/v{{< version-ngf >}}/examples/helm) directory.
171160

172-
---
173-
174161
### Access NGINX Gateway Fabric
175162

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

178-
---
179-
180-
## Upgrade NGINX Gateway Fabric
181-
182-
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
183-
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 >}}
184-
185-
{{< tip >}} For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below. {{< /tip >}}
186-
187-
{{< note >}} To upgrade from version 1.x to 2.x, please refer to this [guide]({{< ref "/ngf/install/upgrade-2.0.md" >}}). {{< /note >}}
188-
189-
To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps:
190-
191-
---
192-
193-
### Upgrade Gateway resources
194-
195-
{{< include "/ngf/installation/upgrade-api-resources.md" >}}
196-
197-
---
198-
199-
### Upgrade NGINX Gateway Fabric CRDs
200-
201-
Helm's upgrade process does not automatically upgrade the NGINX Gateway Fabric CRDs (Custom Resource Definitions).
202-
203-
To upgrade the CRDs, take the following steps:
204-
205-
1. {{< include "/ngf/installation/helm/pulling-the-chart.md" >}}
206-
207-
2. Upgrade the CRDs:
208-
209-
```shell
210-
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
211-
```
212-
213-
{{<note>}}Ignore the following warning, as it is expected.{{</note>}}
214-
215-
```text
216-
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply.
217-
```
218-
219-
---
220-
221-
### Upgrade NGINX Gateway Fabric release
222-
223-
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
224-
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 >}}
225-
226-
There are two possible ways to upgrade NGINX Gateway Fabric. You can either upgrade from the OCI registry, or download the chart and upgrade from the source.
227-
228-
---
229-
230-
#### Upgrade from the OCI registry
231-
232-
To upgrade to the latest stable release of NGINX Gateway Fabric, run:
233-
234-
```shell
235-
helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric -n nginx-gateway
236-
```
237-
238-
If needed, replace `ngf` with your chosen release name.
239-
240-
---
241-
242-
#### Upgrade from sources
243-
244-
{{< include "/ngf/installation/helm/pulling-the-chart.md" >}}
245-
246-
To upgrade, run: the following command:
247-
248-
```shell
249-
helm upgrade ngf . -n nginx-gateway
250-
```
251-
252-
If needed, replace `ngf` with your chosen release name.
253-
254-
---
255-
256-
## How to upgrade from NGINX OSS to NGINX Plus
257-
258-
To upgrade from NGINX OSS to NGINX Plus, update the Helm command to include the necessary values for Plus:
259-
260-
{{< note >}} If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry for your NGINX Plus image, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials.{{< /note >}}
261-
262-
{{< important >}} Ensure that you [Create the required JWT Secrets]({{< ref "/ngf/install/nginx-plus.md" >}}) before installing.{{< /important >}}
263-
264-
```shell
265-
helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set nginx.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway
266-
```
267-
268-
If needed, replace `ngf` with your chosen release name.
269-
270-
---
271-
272-
## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades}
273-
274-
{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}}
275-
276-
Follow these steps to configure delayed pod termination:
277-
278-
1. Open the `values.yaml` for editing.
279-
280-
1. **Add delayed shutdown hooks**:
281-
282-
- In the `values.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment.
283-
284-
```yaml
285-
nginxGateway:
286-
<...>
287-
lifecycle:
288-
preStop:
289-
exec:
290-
command:
291-
- /usr/bin/gateway
292-
- sleep
293-
- --duration=40s # This flag is optional, the default is 30s
294-
295-
nginx:
296-
<...>
297-
lifecycle:
298-
preStop:
299-
exec:
300-
command:
301-
- /bin/sleep
302-
- "40"
303-
```
304-
305-
1. **Set the termination grace period**:
306-
307-
- {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md">}}
308-
309-
1. Save the changes.
310-
311-
{{<see-also>}}
312-
For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation:
313-
314-
- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks)
315-
- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination)
316-
317-
{{</see-also>}}
318-
319165
## Uninstall NGINX Gateway Fabric
320166

321167
Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster:

‎content/ngf/install/manifests.md‎

Lines changed: 0 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,6 @@ docs: DOCS-1429
1111

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

14-
---
15-
1614
## Before you begin
1715

1816
To complete this guide, you'll need to install:
@@ -43,20 +41,14 @@ To complete this guide, you'll need to install:
4341

4442
</details>
4543

46-
---
47-
4844
## Deploy NGINX Gateway Fabric
4945

5046
Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps. With manifests, you can configure your deployment exactly how you want. Manifests also make it easy to replicate deployments across environments or clusters, ensuring consistency.
5147

52-
---
53-
5448
### Install the Gateway API resources
5549

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

58-
---
59-
6052
### Deploy the NGINX Gateway Fabric CRDs
6153

6254
#### Stable release
@@ -71,8 +63,6 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{
7163
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml
7264
```
7365

74-
---
75-
7666
### Deploy NGINX Gateway Fabric
7767

7868
{{< 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 >}}
@@ -179,8 +169,6 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{
179169

180170
{{</tabs>}}
181171

182-
---
183-
184172
### Verify the Deployment
185173

186174
To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace:
@@ -196,94 +184,10 @@ NAME READY STATUS RESTARTS AGE
196184
nginx-gateway-5d4f4c7db7-xk2kq 1/1 Running 0 112s
197185
```
198186

199-
---
200-
201187
### Access NGINX Gateway Fabric
202188

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

205-
---
206-
207-
## Upgrade NGINX Gateway Fabric
208-
209-
{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT
210-
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 >}}
211-
212-
{{< tip >}} For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section. {{</ tip >}}
213-
214-
{{< note >}} To upgrade from version 1.x to 2.x, please refer to this [guide]({{< ref "/ngf/install/upgrade-2.0.md" >}}). {{< /note >}}
215-
216-
To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps:
217-
218-
### Upgrade Gateway API resources
219-
220-
{{< include "/ngf/installation/upgrade-api-resources.md" >}}
221-
222-
### Upgrade NGINX Gateway Fabric CRDs
223-
224-
To upgrade the Custom Resource Definitions (CRDs), run:
225-
226-
```shell
227-
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
228-
```
229-
230-
### Upgrade NGINX Gateway Fabric deployment
231-
232-
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.
233-
234-
---
235-
236-
## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades}
237-
238-
{{< include "/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md" >}}
239-
240-
Follow these steps to configure delayed pod termination:
241-
242-
1. Open the `deploy.yaml` for editing.
243-
244-
1. **Add delayed shutdown hooks**:
245-
246-
- In the `deploy.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment.
247-
248-
```yaml
249-
<...>
250-
name: nginx-gateway
251-
<...>
252-
lifecycle:
253-
preStop:
254-
exec:
255-
command:
256-
- /usr/bin/gateway
257-
- sleep
258-
- --duration=40s # This flag is optional, the default is 30s
259-
<...>
260-
name: nginx
261-
<...>
262-
lifecycle:
263-
preStop:
264-
exec:
265-
command:
266-
- /bin/sleep
267-
- "40"
268-
<...>
269-
```
270-
271-
1. **Set the termination grace period**:
272-
273-
- {{< include "/ngf/installation/delay-pod-termination/termination-grace-period.md" >}}
274-
275-
1. Save the changes.
276-
277-
{{< see-also >}}
278-
For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation:
279-
280-
- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks)
281-
- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination)
282-
283-
{{< /see-also >}}
284-
285-
---
286-
287191
## Uninstall NGINX Gateway Fabric
288192

289193
Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster:

0 commit comments

Comments
 (0)