diff --git a/content/ngf/how-to/_index.md b/content/ngf/how-to/_index.md index b48bf630e..3d0b4588a 100644 --- a/content/ngf/how-to/_index.md +++ b/content/ngf/how-to/_index.md @@ -1,5 +1,5 @@ --- title: "How-to guides" url: /nginx-gateway-fabric/how-to/ -weight: 400 +weight: 500 --- diff --git a/content/ngf/installation/installing-ngf/control-plane-certs.md b/content/ngf/installation/installing-ngf/control-plane-certs.md index 4a34e24d9..763405e94 100644 --- a/content/ngf/installation/installing-ngf/control-plane-certs.md +++ b/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 diff --git a/content/ngf/reference/_index.md b/content/ngf/reference/_index.md index 7fad2be4f..075c35741 100644 --- a/content/ngf/reference/_index.md +++ b/content/ngf/reference/_index.md @@ -1,5 +1,5 @@ --- title: "Reference" -weight: 500 +weight: 600 url: /nginx-gateway-fabric/reference/ --- diff --git a/content/ngf/releases.md b/content/ngf/releases.md index f371d7a96..2dabcd11e 100644 --- a/content/ngf/releases.md +++ b/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 diff --git a/content/ngf/support.md b/content/ngf/support.md index c6f28eed2..198f88f3a 100644 --- a/content/ngf/support.md +++ b/content/ngf/support.md @@ -1,6 +1,6 @@ --- title: Support -weight: 600 +weight: 700 toc: true type: reference product: NGF diff --git a/content/ngf/upgrading-ngf.md b/content/ngf/upgrading-ngf.md new file mode 100644 index 000000000..d19aebed7 --- /dev/null +++ b/content/ngf/upgrading-ngf.md @@ -0,0 +1,95 @@ +--- +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. + +{{}} You do not need to uninstall the Gateway API CRDs during the upgrade. These resources are compatible with the new NGINX Gateway Fabric version. {{}} + +#### 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/v1.6.2/deploy/crds.yaml +``` + +{{}} + +{{%tab name="Helm"%}} + +Follow these steps to install NGINX Gateway Fabric v2.x using Helm: + +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: + +```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 %}} + +{{}} + + +### 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" >}}).