NGF: Upgrade NGF from 1.x to 2.x

content/ngf/how-to/_index.md

@@ -1,5 +1,5 @@
 ---
 title: "How-to guides"
 url: /nginx-gateway-fabric/how-to/
-weight: 400
+weight: 500
 ---

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

@@ -13,6 +13,8 @@ By default, NGINX Gateway Fabric installs self-signed certificates to secure the
 
 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.**
 
+---
+
 ## Before you begin
 
 You need:
@@ -27,6 +29,7 @@ Add the Helm repository:
 ```shell
 helm repo add jetstack https://charts.jetstack.io
 helm repo update
+```
 
 Install cert-manager:
 
@@ -39,8 +42,9 @@ helm install \
   --set config.kind="ControllerConfiguration" \
   --set config.enableGatewayAPI=true \
   --set crds.enabled=true
+```
 
-  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" >}}).
+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" >}}).
 
 ## Create the CA issuer
 

content/ngf/reference/_index.md

@@ -1,5 +1,5 @@
 ---
 title: "Reference"
-weight: 500
+weight: 600
 url: /nginx-gateway-fabric/reference/
 ---

content/ngf/releases.md

@@ -1,7 +1,7 @@
 ---
 title: Releases
 description: "NGINX Gateway Fabric releases."
-weight: 700
+weight: 800
 toc: true
 type: reference
 product: NGF

content/ngf/support.md

@@ -1,6 +1,6 @@
 ---
 title: Support
-weight: 600
+weight: 700
 toc: true
 type: reference
 product: NGF

content/ngf/upgrading-ngf.md

@@ -0,0 +1,101 @@
+---
+title: Upgrade NGINX Gateway Fabric to version 2.x
+weight: 400
+toc: true
+type: how-to
+product: NGF
+docs: DOCS-0000
+---
+
+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).
+
+
+### Upgrade from v1.x to v2.x
+
+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.
+
+{{<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>}}
+
+#### Uninstall NGINX Gateway Fabric v1.x
+
+To remove the previous version 1.x of NGINX Gateway Fabric, follow these steps:
+
+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:
+
+```shell
+helm uninstall ngf -n nginx-gateway 
+```
+
+Afterwards, remove CRDs associated with NGINX Gateway Fabric version 1.x with the following command:
+
+```shell
+kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+```
+
+{{<tabs name="install-ngf-2.x">}}
+
+{{%tab name="Helm"%}}
+
+Follow these steps to install NGINX Gateway Fabric v2.x using Helm:
+
+Apply the new CRDs with the following command:
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+```
+
+Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command:
+
+```shell
+helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway
+```
+
+For additional customization options during the helm installation process, take a look at [Installation with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md" >}}).
+
+{{% /tab %}}
+
+{{%tab name="Manifests"%}}
+
+Follow these steps to install NGINX Gateway Fabric v2.x using Manifests:
+
+Apply the new CRDs with the following command:
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/crds.yaml
+```
+
+Next, install the latest stable release of NGINX Gateway Fabric in the `nginx-gateway` namespace with the following command:
+
+```shell
+kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v{{< version-ngf >}}/deploy/default/deploy.yaml
+```
+
+For additional customization options during the installation process using manifests, take a look at [Installation with Manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md" >}}).
+
+{{% /tab %}}
+
+{{</tabs>}}
+
+
+### Architecture changes
+
+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.
+
+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.
+
+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`.
+
+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.
+
+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.
+
+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.
+
+
+### Key links for the version 2.x update
+
+- To read more on [modifying data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}}).
+- To learn more about [deploying a Gateway for data plane instances]({{< ref "/ngf/installation/installing-ngf/deploy-data-plane.md" >}}).
+- To adding secure [authentication to control plane and data planes]({{< ref "/ngf/installation/installing-ngf/control-plane-certs.md" >}}).
+- To read more about [architecture changes]({{< ref "/ngf/overview/gateway-architecture.md" >}}).
+- For detailed [API reference]({{< ref "/ngf/reference/api.md" >}}).