Skip to content

Commit 95f2d02

Browse files
salonichf5salonichf5
authored
NGF: Upgrade NGF from 1.x to 2.x (#564)
* docs: upgrade NGF from v1.x to v2.x
1 parent 1ffebbb commit 95f2d02

File tree

6 files changed

+104
-5
lines changed

6 files changed

+104
-5
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
22
title: "How-to guides"
33
url: /nginx-gateway-fabric/how-to/
4-
weight: 400
4+
weight: 500
55
---

‎content/ngf/installation/installing-ngf/control-plane-certs.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ By default, NGINX Gateway Fabric installs self-signed certificates to secure the
1313

1414
This guide will step through how to install and use `cert-manager` to secure this connection. **This should be done _before_ you install NGINX Gateway Fabric.**
1515

16+
---
17+
1618
## Before you begin
1719

1820
You need:
@@ -27,6 +29,7 @@ Add the Helm repository:
2729
```shell
2830
helm repo add jetstack https://charts.jetstack.io
2931
helm repo update
32+
```
3033

3134
Install cert-manager:
3235

@@ -39,8 +42,9 @@ helm install \
3942
--set config.kind="ControllerConfiguration" \
4043
--set config.enableGatewayAPI=true \
4144
--set crds.enabled=true
45+
```
4246

43-
This also enables Gateway API features for cert-manager, which can be useful for [securing your workload traffic]({{< ref "/ngf/how-to/traffic-security/integrating-cert-manager.md" >}}).
47+
This also enables Gateway API features for cert-manager, which can be useful for [securing your workload traffic]({{< ref "/ngf/how-to/traffic-security/integrating-cert-manager.md" >}}).
4448

4549
## Create the CA issuer
4650

‎content/ngf/reference/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
22
title: "Reference"
3-
weight: 500
3+
weight: 600
44
url: /nginx-gateway-fabric/reference/
55
---

‎content/ngf/releases.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Releases
33
description: "NGINX Gateway Fabric releases."
4-
weight: 700
4+
weight: 800
55
toc: true
66
type: reference
77
product: NGF

‎content/ngf/support.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Support
3-
weight: 600
3+
weight: 700
44
toc: true
55
type: reference
66
product: NGF

‎content/ngf/upgrading-ngf.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Upgrade NGINX Gateway Fabric to version 2.x
3+
weight: 400
4+
toc: true
5+
type: how-to
6+
product: NGF
7+
docs: DOCS-0000
8+
---
9+
10+
This guide provides step-by-step instructions for upgrading NGINX Gateway Fabric from version 1.x to 2.x, highlighting key architectural changes, expected downtime, and important considerations for custom resource definitions (CRDs).
11+
12+
13+
### Upgrade from v1.x to v2.x
14+
15+
To upgrade NGINX Gateway Fabric from version 1.x to the new architecture in version 2.x, you must uninstall the existing NGINX Gateway Fabric CRDs and deployment, and perform a fresh installation. This will cause brief downtime during the upgrade process.
16+
17+
{{<note>}} You do not need to uninstall the Gateway API CRDs during the upgrade. These resources are compatible with the new NGINX Gateway Fabric version. {{</note>}}
18+
19+
#### Uninstall NGINX Gateway Fabric v1.x
20+
21+
To remove the previous version 1.x of NGINX Gateway Fabric, follow these steps:
22+
23+
First, run the following command to uninstall NGINX Gateway Fabric from the `nginx-gateway` namespace, and update `ngf` to your release name if it is different:
24+
25+
```shell
26+
helm uninstall ngf -n nginx-gateway
27+
```
28+
29+
Afterwards, remove CRDs associated with NGINX Gateway Fabric version 1.x with the following command:
30+
31+
```shell
32+
kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.2/deploy/crds.yaml
33+
```
34+
35+
{{<tabs name="install-ngf-2.x">}}
36+
37+
{{%tab name="Helm"%}}
38+
39+
Follow these steps to install NGINX Gateway Fabric v2.x using Helm:
40+
41+
Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace. The following `helm install` command will install the NGINX Gateway Fabric release along with the necessary CRDs required for the deployment:
42+
43+
```shell
44+
helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
45+
```
46+
47+
For additional customization options during the helm installation process, take a look at [Installation with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md" >}}).
48+
49+
{{% /tab %}}
50+
51+
{{%tab name="Manifests"%}}
52+
53+
Follow these steps to install NGINX Gateway Fabric v2.x using Manifests:
54+
55+
Apply the new CRDs with the following command:
56+
57+
```shell
58+
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
59+
```
60+
61+
Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command:
62+
63+
```shell
64+
kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml
65+
```
66+
67+
For additional customization options during the installation process using manifests, take a look at [Installation with Manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md" >}}).
68+
69+
{{% /tab %}}
70+
71+
{{</tabs>}}
72+
73+
74+
### Architecture changes
75+
76+
With this release, NGINX Gateway Fabric adopts a new architecture that separates the control plane and data plane into independent deployments. This separation improves scalability, security, and operational clarity.
77+
78+
The control plane is a Kubernetes controller that watches Gateway API and Kubernetes resources (e.g., Services, Endpoints, Secrets) and dynamically provisions NGINX data plane deployments for each Gateway.
79+
80+
NGINX configurations are generated by the control plane and securely delivered to the data planes via gRPC, using the NGINX Agent. TLS is enabled by default, with optional integration with `cert-manager`.
81+
82+
Each data plane pod runs NGINX alongside the Agent, which applies config updates and handles reloads without shared volumes or signals. This design ensures dynamic, per-Gateway traffic management and operational isolation.
83+
84+
New fields have been added to the `NginxProxy` resource to configure infrastructure-related settings for data plane deployments. The `NginxProxy` resource is now a namespaced-scoped resource, instead of a cluster-scoped resource, and can be modified at either the Gateway or GatewayClass level. These new fields provide the flexibility to customize deployment and service configurations.
85+
86+
For detailed instructions on how to modify these settings, refer to the [Configure infrastructure-related settings]({{< ref "/ngf/how-to/data-plane-configuration.md#configure-infrastructure-related-settings" >}}) guide.
87+
88+
89+
### Key links for the version 2.x update
90+
91+
- To read more on [modifying data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}).
92+
- To learn more about [deploying a Gateway for data plane instances]({{< ref "/ngf/installation/installing-ngf/deploy-data-plane.md" >}}).
93+
- To adding secure [authentication to control plane and data planes]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}).
94+
- To read more about [architecture changes]({{< ref "/ngf/overview/gateway-architecture.md" >}}).
95+
- For detailed [API reference]({{< ref "/ngf/reference/api.md" >}}).

0 commit comments

Comments
 (0)