From 10594fa370fe0891dec578d5f51bd297bdb76845 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 10 Jul 2025 12:03:38 +0100 Subject: [PATCH 1/3] feat: Clarify 3.x to 4.x upgrade process for NIC This commit renames the Upgrade to 3.x document for NGINX Ingress Controller to clarify it is for 3.x to 4.00 only. It adds an explicit warning call-out at the top of the page to reinforce this, and the Helm installation document has also been updated with more generic phrasing. At a certain point of maturity the note on the Helm instructions page could likely be removed, unless we anticipate someone will be still be running a 3.x instance years after the versions have moved on. --- .../installing-nic/installation-with-helm.md | 18 ++++++++---------- .../installing-nic/upgrade-to-v4.md | 12 ++++++++++-- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 3580dce67..8cfa0819d 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -11,7 +11,7 @@ This document explains how to install F5 NGINX Ingress Controller using [Helm](h ## Before you begin -{{< note >}} All documentation should only be used with the latest stable release, indicated on [the releases page]({{< ref "/nic/releases.md" >}}) of the GitHub repository. {{< /note >}} +{{< call-out "note" >}} All documentation should only be used with the latest stable release, indicated on [the releases page]({{< ref "/nic/releases.md" >}}) of the GitHub repository. {{< /call-out >}} - A [Kubernetes Version Supported by NGINX Ingress Controller]({{< ref "/nic/technical-specifications.md#supported-kubernetes-versions" >}}) - Helm 3.0+. @@ -30,8 +30,8 @@ If you do not use the custom resources that require those CRDs (which correspond ### Upgrade the CRDs -{{< note >}} Please make sure to read the steps outlined in [Upgrade to V4]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md#update-custom-resource-apiversion" >}}) before running the CRD upgrade and perform the steps if applicable. -{{< /note >}} +{{< call-out "note" >}} If you are running NGINX Ingress Controller v3.x, you should read [Upgrade from NGINX Ingress Controller v3.x to v4.0.0]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md" >}}) before continuing. +{{< /call-out >}} To upgrade the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: @@ -47,10 +47,10 @@ kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version. -{{< note >}} The following warning is expected and can be ignored: `Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply`. +{{< call-out "note" >}} The following warning is expected and can be ignored: `Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply`. Check the [release notes](https://www.github.com/nginx/kubernetes-ingress/releases) for a new release for any special upgrade procedures. -{{< /note >}} +{{< /call-out >}} ### Uninstall the CRDs @@ -60,7 +60,7 @@ To remove the CRDs, pull the chart sources as described in [Pull the Chart](#pul kubectl delete -f crds/ ``` -{{< warning >}} This command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other NGINX Ingress Controller instances running in the cluster. {{< /warning >}} +{{< call-out "warning" >}} This command will delete all the corresponding custom resources in your cluster across all namespaces. Please ensure there are no custom resources that you want to keep and there are no other NGINX Ingress Controller instances running in the cluster. {{< /call-out >}} ## Manage the chart with OCI Registry @@ -113,7 +113,7 @@ You can install the `edge` version by specifying the `--version` flag with the v helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.0.0-edge ``` -{{< warning >}} The `edge` version is not intended for production use. It is intended for testing and development purposes only. {{< /warning >}} +{{< call-out "warning" >}} The `edge` version is not intended for production use. It is intended for testing and development purposes only. {{< /call-out >}} ## Manage the chart with Sources @@ -184,7 +184,7 @@ Although the advisory is to update all resources in accordance with new naming c ### Upgrade steps -{{< note >}} The following steps apply to both 2.x and 3.0.x releases. {{}} +{{< call-out "note" >}} The following steps apply to both 2.x and 3.0.x releases. {{}} The steps you should follow depend on the Helm release name: @@ -299,7 +299,6 @@ The [Run multiple NGINX Ingress Controllers]({{< ref "/nic/installation/run-mult The following tables lists the configurable parameters of the NGINX Ingress Controller chart and their default values. -{{< table >}} {{}} |Parameter | Description | Default | | --- | --- | --- | @@ -490,4 +489,3 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont |**nginxAgent.napMonitoring.processorBufferSize** | Buffer size for processor. Will contain log lines and parsed log lines. | 50000 | |**nginxAgent.customConfigMap** | The name of a custom ConfigMap to use instead of the one provided by default. | "" | {{}} -{{< /table >}} diff --git a/content/nic/installation/installing-nic/upgrade-to-v4.md b/content/nic/installation/installing-nic/upgrade-to-v4.md index 36b3e798d..29b275067 100644 --- a/content/nic/installation/installing-nic/upgrade-to-v4.md +++ b/content/nic/installation/installing-nic/upgrade-to-v4.md @@ -1,5 +1,5 @@ --- -title: Upgrade to NGINX Ingress Controller 4.0.0 +title: Upgrade from NGINX Ingress Controller v3.x to v4.0.0 toc: true weight: 400 type: how-to @@ -7,12 +7,20 @@ product: NIC nd-docs: DOCS-1862 --- -This document explains how to upgrade F5 NGINX Ingress Controller to 4.0.0. +This document explains how to upgrade F5 NGINX Ingress Controller from version v3.x to v4.0.0. There are two necessary steps required: updating the `apiVersion` value of custom resources and configuring structured logging. For NGINX Plus users, there is a third step to create a Secret for your license. +{{< call-out "warning" "This upgrade path is intended for 3.x to 4.0.0 only" >}} + +The instructions in this document are intended only for users upgrading from NGINX Ingress Controller 3.x to 4.0.0. Internal changes meant that backwards compability was not possible, requiring extra steps to upgrade. + +From NGINX Ingress Controller v4.0.0 onwards, you can upgrade as normal, based on your installation method: [Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md">}}) or [Manifests]({{< ref "/nic/installation/installing-nic/installation-with-manifests.md">}}). + +{{< /call-out >}} + --- ## Update custom resource apiVersion From 6f27a3c5a7254183a815bc3bb99aca7e0ccb947a Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 10 Jul 2025 12:09:45 +0100 Subject: [PATCH 2/3] chore: Update document metadata --- content/nic/installation/installing-nic/upgrade-to-v4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nic/installation/installing-nic/upgrade-to-v4.md b/content/nic/installation/installing-nic/upgrade-to-v4.md index 29b275067..f63d33fb2 100644 --- a/content/nic/installation/installing-nic/upgrade-to-v4.md +++ b/content/nic/installation/installing-nic/upgrade-to-v4.md @@ -2,8 +2,8 @@ title: Upgrade from NGINX Ingress Controller v3.x to v4.0.0 toc: true weight: 400 -type: how-to -product: NIC +nd-content-type: how-to +nd-product: NIC nd-docs: DOCS-1862 --- From 9fd368ac05fdfe82c796c2b02a4dec9eda9f58f5 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Thu, 10 Jul 2025 12:11:47 +0100 Subject: [PATCH 3/3] fix: Note formatting issue --- .../nic/installation/installing-nic/installation-with-helm.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 8cfa0819d..4ad8e1377 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -30,8 +30,7 @@ If you do not use the custom resources that require those CRDs (which correspond ### Upgrade the CRDs -{{< call-out "note" >}} If you are running NGINX Ingress Controller v3.x, you should read [Upgrade from NGINX Ingress Controller v3.x to v4.0.0]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md" >}}) before continuing. -{{< /call-out >}} +{{< call-out "note" >}} If you are running NGINX Ingress Controller v3.x, you should read [Upgrade from NGINX Ingress Controller v3.x to v4.0.0]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md" >}}) before continuing. {{< /call-out >}} To upgrade the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: