From 70350764bfe60409da149d475d1580f5af6e4569 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 15 Jul 2025 17:26:11 +0100 Subject: [PATCH 01/23] feat: Clarify NIC install & upgrade steps This commit makes a number of changes to clarify what the precise steps are to install, upgrade and uninstall NGINX Ingress Controller - The Install document clarifies necessary steps - Uninstall steps have been moved to the bottom of the document - Upgrade instructions have been moved into their own document The changes made focused on clarifying the critical path for one single user story, as lots of unnecessary contextual information was being provided, which was causing confusion. With this commit, the general reading and execution flow for these deployment steps become more coherent. Similar changes may be made for Manifests documentation, if common steps are identified. --- content/nic/installation/ingress-nginx.md | 10 +- .../installing-nic/installation-with-helm.md | 296 +++++------------ .../installation-with-manifests.md | 4 +- .../installing-nic/upgrade-to-v4.md | 137 -------- .../nic/installation/integrations/_index.md | 2 +- .../run-multiple-ingress-controllers.md | 14 +- content/nic/installation/upgrade-version.md | 311 ++++++++++++++++++ content/nic/releases.md | 6 +- 8 files changed, 399 insertions(+), 381 deletions(-) delete mode 100644 content/nic/installation/installing-nic/upgrade-to-v4.md create mode 100644 content/nic/installation/upgrade-version.md diff --git a/content/nic/installation/ingress-nginx.md b/content/nic/installation/ingress-nginx.md index faa3d3b04..33b3ec409 100644 --- a/content/nic/installation/ingress-nginx.md +++ b/content/nic/installation/ingress-nginx.md @@ -1,12 +1,10 @@ --- -nd-docs: DOCS-1469 -doctypes: -- tutorial -tags: -- docs title: Migrate from Ingress-NGINX Controller to NGINX Ingress Controller toc: true -weight: 500 +weight: 700 +nd-content-type: how-to +nd-product: NIC +nd-docs: DOCS-1469 --- This document describes how to migrate from the community-maintained Ingress-NGINX Controller to F5 NGINX Ingress Controller. diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 4ad8e1377..5f35c63a2 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -15,97 +15,43 @@ This document explains how to install F5 NGINX Ingress Controller using [Helm](h - A [Kubernetes Version Supported by NGINX Ingress Controller]({{< ref "/nic/technical-specifications.md#supported-kubernetes-versions" >}}) - Helm 3.0+. -- If you’d like to use NGINX Plus: - - Get the NGINX Ingress Controller JWT and [create a license secret]({{< ref "/nic/installation/create-license-secret.md" >}}). - - Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. - - The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. - - The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. - - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. -## Custom Resource Definitions - -NGINX Ingress Controller requires custom resource definitions (CRDs) installed in the cluster, which Helm will install. If the CRDs are not installed, NGINX Ingress Controller pods will not become `Ready`. +There are additional requirements if you'd like to use NGINX Plus: +- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}). +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. +- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. +- Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. -If you do not use the custom resources that require those CRDs (which corresponds to `controller.enableCustomResources` set to `false` and `controller.appprotect.enable` set to `false` and `controller.appprotectdos.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` for the helm install command. +## Install the Helm chart using the OCI Registry -### Upgrade the CRDs +Run the following commands to install the chart with the release name _my-release_ (Which you can customize): -{{< 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 >}} +{{< tabs name="registry-chart-versions" >}} -To upgrade the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: +{{% tab name="NGINX Open Source" %}} ```shell -kubectl apply -f crds/ +helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -Alternatively, CRDs can be upgraded without pulling the chart by running: +{{% /tab %}} -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml -``` +{{% tab name="NGINX Plus" %}} -In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version. - -{{< 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. -{{< /call-out >}} - -### Uninstall the CRDs - -To remove the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: +This assumes you have pushed NGINX Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`: ```shell -kubectl delete -f crds/ +helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` -{{< 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 - -### Install the chart - -Run the following commands to install the chart with the release name my-release (my-release is the name that you choose): +{{% /tab %}} -- For NGINX: +{{< /tabs >}} - ```shell - helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} - ``` -- For NGINX Plus: (This assumes you have pushed NGINX Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) +If you'd like to test the latest changes in NGINX Ingress Controller before a new release, you can install the `edge` version, which is built from the `main` branch of the [NGINX Ingress Controller repository](https://github.com/nginx/kubernetes-ingress). - ```shell - helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true - ``` - -These commands install the latest `edge` version of NGINX Ingress Controller from GitHub Container Registry. If you prefer using Docker Hub, you can replace `ghcr.io/nginx/charts/nginx-ingress` with `registry-1.docker.io/nginxcharts/nginx-ingress`. - -### Upgrade the chart - -Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrade the CRDs](#upgrade-the-crds). - -To upgrade the release `my-release`: - -```shell -helm upgrade my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} -``` - -### Uninstall the chart - -To uninstall/delete the release `my-release`: - -```shell -helm uninstall my-release -``` - -The command removes all the Kubernetes components associated with the release and deletes the release. - -Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstall the CRDs](#uninstall-the-crds). - -### Edge version - -To test the latest changes in NGINX Ingress Controller before a new release, you can install the `edge` version. This version is built from the `main` branch of the NGINX Ingress Controller repository. You can install the `edge` version by specifying the `--version` flag with the value `0.0.0-edge`: ```shell @@ -114,187 +60,67 @@ helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.0.0 {{< 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 - -### Pull the chart - -This step is required if you're installing the chart using its sources. It also manages the custom resource definitions (CRDs) which NGINX Ingress Controller requires, and for upgrading or deleting the CRDs. - -1. Pull the chart sources: - - ```shell - helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version {{< nic-helm-version >}} - ``` - -2. Change your working directory to nginx-ingress: - - ```shell - cd nginx-ingress - ``` +## Install the Helm chart from source -### Install the chart +This section covers the steps involved with installing the Helm chart from the source, instead of using the registry. -To install the chart with the release name my-release (my-release is the name that you choose): +It also manages required the custom resource definitions (CRDs) for NGINX Ingress Controller. -- For NGINX: - - ```shell - helm install my-release . - ``` - -- For NGINX Plus: - - ```shell - helm install my-release -f values-plus.yaml . - ``` - -The command deploys the Ingress Controller in your Kubernetes cluster in the default configuration. The configuration section lists the parameters that can be configured during installation. - -### Upgrade the chart - -Helm does not upgrade the CRDs during a release upgrade. Before you upgrade a release, see [Upgrade the CRDs](#upgrade-the-crds). - -To upgrade the release `my-release`: +Pull the chart sources, which are also required for upgrading or deleting the CRDs: ```shell -helm upgrade my-release . +helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version {{< nic-helm-version >}} ``` -### Uninstall the chart - -To uninstall/delete the release `my-release`: +Change your working directory to nginx-ingress: ```shell -helm uninstall my-release +cd nginx-ingress ``` -The command removes all the Kubernetes components associated with the release and deletes the release. - -Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstall the CRDs](#uninstall-the-crds). - -## Upgrade without downtime +Install the chart with the release name _my-release_ (Which you can customize): -### Background +{{< tabs name="source-chart-versions" >}} -In NGINX Ingress Controller version 3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. -When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated due to the aforementioned changes, which will result in downtime. +{{% tab name="NGINX Open Source" %}} -Although the advisory is to update all resources in accordance with new naming convention, to avoid downtime follow the steps listed below. - -### Upgrade steps - -{{< 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: - -{{}} - -{{%tab name="Helm release name is `nginx-ingress`"%}} - -1. Use `kubectl describe` on deployment/daemonset to get the `Selector` value: - - ```shell - kubectl describe deployments -n - ``` - - Copy the key=value under `Selector`, such as: - - ```shell - Selector: app=nginx-ingress-nginx-ingress - ``` - -2. Checkout the latest available tag using `git checkout v{{< nic-version >}}` - -3. Navigate to `/kubernetes-ingress/charts/nginx-ingress` - -4. Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. - ```shell - selectorLabels: {app: nginx-ingress-nginx-ingress} - ``` - -5. Run `helm upgrade` with following arguments set: - ```shell - --set serviceNameOverride="nginx-ingress-nginx-ingress" - --set controller.name="" - --set fullnameOverride="nginx-ingress-nginx-ingress" - ``` - It could look as follows: - - ```shell - helm upgrade nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml - ``` - -6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: - ```shell - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 - Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 - Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set nginx-ingress-nginx-ingress- to 0 from 1 - ``` -{{%/tab%}} - -{{%tab name="Helm release name is not `nginx-ingress`"%}} - -1. Use `kubectl describe` on deployment/daemonset to get the `Selector` value: - - ```shell - kubectl describe deployment/daemonset -n - ``` - - Copy the key=value under ```Selector```, such as: - - ```shell - Selector: app=-nginx-ingress - ``` - -2. Checkout the latest available tag using `git checkout v{{< nic-version >}}` - -3. Navigate to `/kubernetes-ingress/charts/nginx-ingress` - -4. Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. +```shell +helm install my-release . +``` - ```shell - selectorLabels: {app: -nginx-ingress} - ``` +{{% /tab %}} -5. Run `helm upgrade` with following arguments set: +{{% tab name="NGINX Plus" %}} - ```shell - --set serviceNameOverride="-nginx-ingress" - --set controller.name="" - ``` +```shell +helm install my-release -f values-plus.yaml . +``` - It could look as follows: +{{% /tab %}} - ```shell - helm upgrade test-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml - ``` +{{< /tabs >}} -6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: +The command deploys NGINX Ingress Controller in your Kubernetes cluster in the default configuration. The [Helm chart parameters](#helm-chart-parameters) lists the parameters that can be configured during installation. - ```shell - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 - Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 - Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 - ``` +## Custom Resource Definitions -{{%/tab%}} +When installing the NGINX Ingress Controller chart, Helm will also install the required custom resource definitions (CRDs). -{{}} +If the CRDs are not installed, NGINX Ingress Controller pods will not become _Ready_. +If you do not use the custom resources that require those CRDs (With `controller.enableCustomResources`,`controller.appprotect.enable` and `controller.appprotectdos.enable` set to `false`), the installation of the CRDs can be skipped by specifying `--skip-crds` in your _helm install_ command. -## Run multiple NGINX Ingress Controllers +{{< call-out "caution" "Running multiple NGINX Ingress Controller instances">}} -If you are running NGINX Ingress Controller releases in your cluster with custom resources enabled, the releases will share a single version of the CRDs. +If you are running multiple NGINX Ingress Controller releases in your cluster with custom resources enabled, the releases will share a single version of the CRDs. Ensure the NGINX Ingress Controller versions match the version of the CRDs. When uninstalling a release, ensure that you don’t remove the CRDs until there are no other NGINX Ingress Controller releases running in the cluster. The [Run multiple NGINX Ingress Controllers]({{< ref "/nic/installation/run-multiple-ingress-controllers.md" >}}) topic has more details. -## Configuration +{{< /call-out >}} + +## Helm chart parameters The following tables lists the configurable parameters of the NGINX Ingress Controller chart and their default values. @@ -488,3 +314,29 @@ 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. | "" | {{}} + +## Uninstall NGINX Ingress Controller + +To uninstall NGINX Ingress Controller, you must first remove the chart. + +To remove a release named _my-release_, use the following command: + +```shell +helm uninstall my-release +``` + +The command removes all the Kubernetes components associated with the release and deletes the release. + +Uninstalling the release does not remove the CRDs. To do so, first pull the chart sources: + +```shell +helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version {{< nic-helm-version >}} +``` + +Then use _kubectl_ to delete the CRDs: + +```shell +kubectl delete -f crds/ +``` + +{{< 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 >}} \ No newline at end of file diff --git a/content/nic/installation/installing-nic/installation-with-manifests.md b/content/nic/installation/installing-nic/installation-with-manifests.md index 2f44611f6..5e04293f8 100644 --- a/content/nic/installation/installing-nic/installation-with-manifests.md +++ b/content/nic/installation/installing-nic/installation-with-manifests.md @@ -2,8 +2,8 @@ title: Installation with Manifests toc: true weight: 200 -type: how-to -product: NIC +nd-content-type: how-to +nd-product: NIC nd-docs: DOCS-603 --- diff --git a/content/nic/installation/installing-nic/upgrade-to-v4.md b/content/nic/installation/installing-nic/upgrade-to-v4.md deleted file mode 100644 index f63d33fb2..000000000 --- a/content/nic/installation/installing-nic/upgrade-to-v4.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Upgrade from NGINX Ingress Controller v3.x to v4.0.0 -toc: true -weight: 400 -nd-content-type: how-to -nd-product: NIC -nd-docs: DOCS-1862 ---- - -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 - -If the Helm chart you have been using is `v2.x`, before upgrading to NGINX Ingress Controller 4.0.0 you must update your GlobalConfiguration, Policy and TransportServer resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1`. - -If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources. - -The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources. - -{{}} - -{{% comment %}} Keep this left aligned. {{% /comment %}} -{{%tab name="Before"%}} - -```yaml -apiVersion: k8s.nginx.org/v1alpha1 -kind: Policy -metadata: - name: rate-limit-policy -spec: - rateLimit: - rate: 1r/s - key: ${binary_remote_addr} - zoneSize: 10M -``` -{{% /tab %}} - -{{%tab name="After"%}} -```yaml -apiVersion: k8s.nginx.org/v1 -kind: Policy -metadata: - name: rate-limit-policy -spec: - rateLimit: - rate: 1r/s - key: ${binary_remote_addr} - zoneSize: 10M -``` -{{% /tab %}} - -{{}} - -{{< warning >}} -If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process. -{{}} - -Once above specified custom resources are moved to `v1` ,please run below `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid [this issue](https://github.com/nginx/kubernetes-ingress/issues/7010). - -```shell -kubectl patch customresourcedefinitions transportservers.k8s.nginx.org --subresource='status' --type='merge' -p '{"status":{"storedVersions": ["v1"]}}' -``` - -```shell -kubectl patch customresourcedefinitions globalconfigurations.k8s.nginx.org --subresource='status' --type='merge' -p '{"status":{"storedVersions": ["v1"]}}' -``` - ---- - -## Configure structured logging - -To configure structured logging, you must update your log deployment arguments from an integer to a string. The logs themselves can also be rendered in different formats. - -{{< note >}} These options apply to NGINX Ingress Controller logs, and do not affect NGINX logs. {{< /note >}} - -| **Level arguments** | **Format arguments** | -|---------------------|----------------------| -| `trace` | `json` | -| `debug` | `text` | -| `info` | `glog` | -| `warning` | | -| `error` | | -| `fatal` | | - -{{}} - -{{%tab name="Helm"%}} - -The Helm value of `controller.logLevel` has been changed from an integer to a string. - -To change the rendering of the log format, use the `controller.logFormat` key. - -```yaml -controller: - logLevel: info - logFormat: json -``` -{{% /tab %}} - -{{%tab name="Manifests"%}} - -The command line argument `-v` has been replaced with `-log-level`, and takes a string instead of an integer. The argument `-logtostderr` has also been deprecated. - -To change the rendering of the log format, use the `-log-format` argument. - -```yaml -args: - - -log-level=info - - -log-format=json -``` -{{% /tab %}} - -{{}} - ---- - -## Create License secret - -If you're using [NGINX Plus]({{< ref "/nic/overview/nginx-plus.md" >}}) with NGINX Ingress Controller, you should read the [Create License Secret]({{< ref "/nic/installation/create-license-secret.md" >}}) topic to set up your NGINX Plus license. - -The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/nic/installation/create-license-secret.md#nim">}}), which is necessary for air-gapped environments. - -In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus. diff --git a/content/nic/installation/integrations/_index.md b/content/nic/installation/integrations/_index.md index 83943f248..1690f4888 100644 --- a/content/nic/installation/integrations/_index.md +++ b/content/nic/installation/integrations/_index.md @@ -1,6 +1,6 @@ --- title: Integrations description: -weight: 600 +weight: 800 url: /nginx-ingress-controller/installation/integrations --- diff --git a/content/nic/installation/run-multiple-ingress-controllers.md b/content/nic/installation/run-multiple-ingress-controllers.md index 98f3417b8..e0d6a6f47 100644 --- a/content/nic/installation/run-multiple-ingress-controllers.md +++ b/content/nic/installation/run-multiple-ingress-controllers.md @@ -1,10 +1,10 @@ --- -nd-docs: DOCS-606 -doctypes: -- '' title: Run multiple NGINX Ingress Controllers toc: true -weight: 400 +weight: 600 +nd-content-type: how-to +nd-product: NIC +nd-docs: DOCS-606 --- This document describes how to run multiple F5 NGINX Ingress Controller instances. @@ -17,8 +17,6 @@ It explains the following topics: {{< note >}} This document refers to [Ingress]({{< ref "/nic/configuration/ingress-resources/basic-configuration.md" >}}), [VirtualServer]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserver-specification" >}}), [VirtualServerRoute]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#virtualserverroute-specification" >}}), and [TransportServer]({{< ref "/nic/configuration/transportserver-resource.md" >}}) resources as "configuration resources".{{< /note >}} ---- - ## Ingress class The [IngressClass](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class) resource allows for multiple Ingress Controller to operate in the same cluster. It also allow developers to select which Ingress Controller implementation to use for their Ingress resource. @@ -35,16 +33,12 @@ The default Ingress class of NGINX Ingress Controller is `nginx`, which means th {{< note >}}- If the class of an Ingress resource is not set, Kubernetes will set it to the class of the default Ingress Controller. To make the Ingress Controller the default one, the `ingressclass.kubernetes.io/is-default-class` property must be set on the IngressClass resource. To learn more, see Step 3 *Create an IngressClass resource* of the [Create Common Resources]({{< ref "/nic/installation/installing-nic/installation-with-manifests.md#create-common-resources" >}}) section. - For VirtualServer, VirtualServerRoute, Policy and TransportServer resources, NGINX Ingress Controller will always handle resources with an empty class.{{< /note >}} ---- - ## Run NGINX Ingress Controller and another Ingress Controller It is possible to run NGINX Ingress Controller and an Ingress Controller for another load balancer in the same cluster. This is often the case if you create your cluster through a cloud provider's managed Kubernetes service that by default might include the Ingress Controller for the HTTP load balancer of the cloud provider, and you want to use NGINX Ingress Controller. To make sure that NGINX Ingress Controller handles specific configuration resources, update those resources with the class set to the value that is configured in NGINX Ingress Controller. By default, this is `nginx`. ---- - ## Run multiple NGINX Ingress Controllers When running NGINX Ingress Controller, you have the following options with regards to which configuration resources it handles: diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md new file mode 100644 index 000000000..b74570f1b --- /dev/null +++ b/content/nic/installation/upgrade-version.md @@ -0,0 +1,311 @@ +--- +# We use sentence case and present imperative tone +title: "Upgrade NGINX Ingress Controller" +# Weights are assigned in increments of 100: determines sorting order +weight: 500 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: how-to +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: NIC +--- + +This document describes how to upgrade F5 NGINX Ingress Controller when a new version releases. + +It covers the necessary steps for minor versions as well as major versions (Such as 3.x to 4.x). + +Many of the nuances in upgrade paths relate to how custom resource definitions (CRDs) are managed. + +## Minor NGINX Ingress Controller upgrades + +### Upgrade NGINX Ingress Controller 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/upgrade-version.md#upgrade-from-3x-to-4x" >}}) before continuing. {{< /call-out >}} + +To upgrade the CRDs, pull the Helm chart source, then use _kubectl apply_: + +```shell +helm pull oci://ghcr.io/nginx/charts/nginx-ingress --untar --version {{< nic-helm-version >}} +kubectl apply -f crds/ +``` + +Alternatively, CRDs can be upgraded without pulling the chart by running: + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml +``` + +In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version. + +{{< 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. +{{< /call-out >}} + +#### Helm upgrades prior to 3.1.0 + +For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. + +When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime. + +Although the advisory is to update all resources in accordance with new naming convention, to avoid downtime follow the steps listed below. + +{{< call-out "note" >}} The following steps apply to both 2.x and 3.0.x releases. {{}} + +The steps you should follow depend on your Helm release name: + +{{}} + +{{%tab name="nginx-ingress"%}} + +Use `kubectl describe` on deployment/daemonset to get the `Selector` value: + +```shell +kubectl describe deployments -n +``` + +Copy the key=value under `Selector`, such as: + +```shell +Selector: app=nginx-ingress-nginx-ingress +``` + +Checkout the latest available tag using `git checkout v{{< nic-version >}}` + +Navigate to `/kubernetes-ingress/charts/nginx-ingress` + +Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. + +```shell +selectorLabels: {app: nginx-ingress-nginx-ingress} +``` + +Run `helm upgrade` with following arguments set: + +```shell +--set serviceNameOverride="nginx-ingress-nginx-ingress" +--set controller.name="" +--set fullnameOverride="nginx-ingress-nginx-ingress" +``` + +It could look as follows: + +```shell +helm upgrade nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml +``` + +Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: + +```text + Type Reason Age From Message +---- ------ ---- ---- ------- +Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 +Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 +Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set nginx-ingress-nginx-ingress- to 0 from 1 +``` + +{{%/tab%}} + +{{%tab name="Other release names"%}} + +Use `kubectl describe` on deployment/daemonset to get the `Selector` value: + +```shell +kubectl describe deployment/daemonset -n +``` + +Copy the key=value under ```Selector```, such as: + +```shell +Selector: app=-nginx-ingress +``` + +Checkout the latest available tag using `git checkout v{{< nic-version >}}` + +Navigate to `/kubernetes-ingress/charts/nginx-ingress`. + +Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. + +```shell +selectorLabels: {app: -nginx-ingress} +``` + +Run `helm upgrade` with following arguments set: + +```shell +--set serviceNameOverride="-nginx-ingress" +--set controller.name="" +``` + +It could look as follows: + +```shell +helm upgrade test-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml +``` + +Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: + +```shell +Type Reason Age From Message +---- ------ ---- ---- ------- +Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 +Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 +Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 +``` + +{{%/tab%}} + +{{}} + +### Upgrade NGINX Ingress Controller charts + +Once the CRDs have been upgraded, you can then upgrade the release chart. + +The command depends on if you installed the chart using the registry or from source. + +To upgrade a release named _my-release_, use the following command: + +{{< tabs name="upgrade-chart" >}} + +{{% tab name="OCI registry" %}} + +```shell +helm upgrade my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} +``` + +{{% /tab %}} + +{{% tab name="Source" %}} + +```shell +helm upgrade my-release . +``` + +{{% /tab %}} + +{{< /tabs >}} + +## Upgrade from 3.x to 4.x + +{{< call-out "warning" "This upgrade path is intended for 3.x to 4.0.0 only" >}} + +The instructions in this section 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. + +{{< /call-out >}} + +This section provides step-by-step instructions for upgrading 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. + +### Update custom resource apiVersion + +If the Helm chart you have been using is `v2.x`, before upgrading to NGINX Ingress Controller 4.0.0 you must update your GlobalConfiguration, Policy and TransportServer resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1`. + +If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources. + +The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources. + +{{}} + +{{% comment %}} Keep this left aligned. {{% /comment %}} +{{%tab name="Before"%}} + +```yaml +apiVersion: k8s.nginx.org/v1alpha1 +kind: Policy +metadata: + name: rate-limit-policy +spec: + rateLimit: + rate: 1r/s + key: ${binary_remote_addr} + zoneSize: 10M +``` +{{% /tab %}} + +{{%tab name="After"%}} +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: rate-limit-policy +spec: + rateLimit: + rate: 1r/s + key: ${binary_remote_addr} + zoneSize: 10M +``` +{{% /tab %}} + +{{}} + +{{< warning >}} +If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process. +{{}} + +Once above specified custom resources are moved to `v1` ,please run below `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid [this issue](https://github.com/nginx/kubernetes-ingress/issues/7010). + +```shell +kubectl patch customresourcedefinitions transportservers.k8s.nginx.org --subresource='status' --type='merge' -p '{"status":{"storedVersions": ["v1"]}}' +``` + +```shell +kubectl patch customresourcedefinitions globalconfigurations.k8s.nginx.org --subresource='status' --type='merge' -p '{"status":{"storedVersions": ["v1"]}}' +``` + +### Configure structured logging + +To configure structured logging, you must update your log deployment arguments from an integer to a string. The logs themselves can also be rendered in different formats. + +{{< note >}} These options apply to NGINX Ingress Controller logs, and do not affect NGINX logs. {{< /note >}} + +| **Level arguments** | **Format arguments** | +|---------------------|----------------------| +| `trace` | `json` | +| `debug` | `text` | +| `info` | `glog` | +| `warning` | | +| `error` | | +| `fatal` | | + +{{}} + +{{%tab name="Helm"%}} + +The Helm value of `controller.logLevel` has been changed from an integer to a string. + +To change the rendering of the log format, use the `controller.logFormat` key. + +```yaml +controller: + logLevel: info + logFormat: json +``` +{{% /tab %}} + +{{%tab name="Manifests"%}} + +The command line argument `-v` has been replaced with `-log-level`, and takes a string instead of an integer. The argument `-logtostderr` has also been deprecated. + +To change the rendering of the log format, use the `-log-format` argument. + +```yaml +args: + - -log-level=info + - -log-format=json +``` +{{% /tab %}} + +{{}} + +### Create License secret + +If you're using [NGINX Plus]({{< ref "/nic/overview/nginx-plus.md" >}}) with NGINX Ingress Controller, you should read the [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}) topic to set up your NGINX Plus license. + +The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/nic/installation/create-license-secret.md#nim">}}), which is necessary for air-gapped environments. + +In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus. \ No newline at end of file diff --git a/content/nic/releases.md b/content/nic/releases.md index f3480f11a..ee9a9bd8b 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -152,10 +152,10 @@ versions: 1.25-1.32. 16 Dec 2024 With added support for [NGINX R33]({{< ref "/nginx/releases.md#nginxplusrelease-33-r33" >}}), deployments of F5 NGINX Ingress Controller using NGINX Plus now require a valid JSON Web Token to run. -Please see the [Upgrading to v4]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md#create-license-secret" >}}) for full details on setting up your license `Secret`. +Please see the [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on setting up your license `Secret`. API Version `v1alpha1` of `GlobalConfiguration`, `Policy` and `TransportServer` resources are now deprecated. -Please see [Update custom resource apiVersion]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md#update-custom-resource-apiversion" >}}) for full details on updating your resources. +Please see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on updating your resources. Updates have been made to our logging library. For a while, F5 NGINX Ingress Controller has been using the [golang/glog](https://github.com/golang/glog). For this release, we have moved to the native golang library [log/slog](https://pkg.go.dev/log/slog). This change was made for these reasons: @@ -199,7 +199,7 @@ For more details on what this feature does, and how to configure it yourself, pl [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress). - For NGINX Plus, use the 4.0.0 images from the F5 Container registry or build your own image using the 4.0.0 source code - For Helm, use version 2.0.0 of the chart. -- [Upgrading to v4]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md" >}}) +- [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) ### Supported Platforms From 00b5ba8bdbf855d1bc44e83aaa5c30752c105634 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 18 Jul 2025 15:04:01 +0100 Subject: [PATCH 02/23] feat: Move and rename old upgrade instructions --- content/nic/installation/upgrade-version.md | 232 ++++++++++---------- 1 file changed, 116 insertions(+), 116 deletions(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index b74570f1b..7d0b7acfc 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -44,121 +44,6 @@ In the above command, `v{{< nic-version >}}` represents the version of NGINX Ing Check the [release notes](https://www.github.com/nginx/kubernetes-ingress/releases) for a new release for any special upgrade procedures. {{< /call-out >}} -#### Helm upgrades prior to 3.1.0 - -For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. - -When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime. - -Although the advisory is to update all resources in accordance with new naming convention, to avoid downtime follow the steps listed below. - -{{< call-out "note" >}} The following steps apply to both 2.x and 3.0.x releases. {{}} - -The steps you should follow depend on your Helm release name: - -{{}} - -{{%tab name="nginx-ingress"%}} - -Use `kubectl describe` on deployment/daemonset to get the `Selector` value: - -```shell -kubectl describe deployments -n -``` - -Copy the key=value under `Selector`, such as: - -```shell -Selector: app=nginx-ingress-nginx-ingress -``` - -Checkout the latest available tag using `git checkout v{{< nic-version >}}` - -Navigate to `/kubernetes-ingress/charts/nginx-ingress` - -Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. - -```shell -selectorLabels: {app: nginx-ingress-nginx-ingress} -``` - -Run `helm upgrade` with following arguments set: - -```shell ---set serviceNameOverride="nginx-ingress-nginx-ingress" ---set controller.name="" ---set fullnameOverride="nginx-ingress-nginx-ingress" -``` - -It could look as follows: - -```shell -helm upgrade nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml -``` - -Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: - -```text - Type Reason Age From Message ----- ------ ---- ---- ------- -Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 -Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 -Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set nginx-ingress-nginx-ingress- to 0 from 1 -``` - -{{%/tab%}} - -{{%tab name="Other release names"%}} - -Use `kubectl describe` on deployment/daemonset to get the `Selector` value: - -```shell -kubectl describe deployment/daemonset -n -``` - -Copy the key=value under ```Selector```, such as: - -```shell -Selector: app=-nginx-ingress -``` - -Checkout the latest available tag using `git checkout v{{< nic-version >}}` - -Navigate to `/kubernetes-ingress/charts/nginx-ingress`. - -Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. - -```shell -selectorLabels: {app: -nginx-ingress} -``` - -Run `helm upgrade` with following arguments set: - -```shell ---set serviceNameOverride="-nginx-ingress" ---set controller.name="" -``` - -It could look as follows: - -```shell -helm upgrade test-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml -``` - -Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: - -```shell -Type Reason Age From Message ----- ------ ---- ---- ------- -Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 -Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 -Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 -``` - -{{%/tab%}} - -{{}} - ### Upgrade NGINX Ingress Controller charts Once the CRDs have been upgraded, you can then upgrade the release chart. @@ -308,4 +193,119 @@ If you're using [NGINX Plus]({{< ref "/nic/overview/nginx-plus.md" >}}) with NGI The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/nic/installation/create-license-secret.md#nim">}}), which is necessary for air-gapped environments. -In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus. \ No newline at end of file +In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus. + +## Upgrade a version older than v3.1.0 + +For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. + +When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime. + +We advise updating all resources to match the new naming convention: the following steps will minimize the aforementioned downtime. + +{{< call-out "note" >}} The following steps apply to both 2.x and 3.0.x releases. {{}} + +The steps you should follow depend on your Helm release name: + +{{}} + +{{%tab name="nginx-ingress"%}} + +Use `kubectl describe` on deployment/daemonset to get the `Selector` value: + +```shell +kubectl describe deployments -n +``` + +Copy the key=value under `Selector`, such as: + +```shell +Selector: app=nginx-ingress-nginx-ingress +``` + +Checkout the latest available tag using `git checkout v{{< nic-version >}}` + +Navigate to `/kubernetes-ingress/charts/nginx-ingress` + +Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. + +```shell +selectorLabels: {app: nginx-ingress-nginx-ingress} +``` + +Run `helm upgrade` with following arguments set: + +```shell +--set serviceNameOverride="nginx-ingress-nginx-ingress" +--set controller.name="" +--set fullnameOverride="nginx-ingress-nginx-ingress" +``` + +It could look as follows: + +```shell +helm upgrade nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml +``` + +Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: + +```text + Type Reason Age From Message +---- ------ ---- ---- ------- +Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 +Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set nginx-ingress-nginx-ingress- to 1 +Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set nginx-ingress-nginx-ingress- to 0 from 1 +``` + +{{%/tab%}} + +{{%tab name="Other release names"%}} + +Use `kubectl describe` on deployment/daemonset to get the `Selector` value: + +```shell +kubectl describe deployment/daemonset -n +``` + +Copy the key=value under ```Selector```, such as: + +```shell +Selector: app=-nginx-ingress +``` + +Checkout the latest available tag using `git checkout v{{< nic-version >}}` + +Navigate to `/kubernetes-ingress/charts/nginx-ingress`. + +Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. + +```shell +selectorLabels: {app: -nginx-ingress} +``` + +Run `helm upgrade` with following arguments set: + +```shell +--set serviceNameOverride="-nginx-ingress" +--set controller.name="" +``` + +It could look as follows: + +```shell +helm upgrade test-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml +``` + +Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: + +```shell +Type Reason Age From Message +---- ------ ---- ---- ------- +Normal ScalingReplicaSet 9m11s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 +Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set test-release-nginx-ingress- to 1 +Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 +``` + +{{%/tab%}} + +{{}} From 78489596346a53fb29ec0b63545df240871e243e Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:13:10 +0100 Subject: [PATCH 03/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 7d0b7acfc..dca6340b7 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -37,7 +37,7 @@ Alternatively, CRDs can be upgraded without pulling the chart by running: kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml ``` -In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version. +In the above command, `v{{< nic-version >}}` represents the version of the NGINX Ingress Controller release rather than the Helm chart version. {{< 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`. From 6b14dfce3306e87e042368791a7ecf49526fed38 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:13:43 +0100 Subject: [PATCH 04/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index dca6340b7..61d135a24 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -88,7 +88,7 @@ For NGINX Plus users, there is a third step to create a Secret for your license. ### Update custom resource apiVersion -If the Helm chart you have been using is `v2.x`, before upgrading to NGINX Ingress Controller 4.0.0 you must update your GlobalConfiguration, Policy and TransportServer resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1`. +If you're using Helm chart version `v2.x`, update your `GlobalConfiguration`, `Policy`, and `TransportServer` resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1` before upgrading to NGINX Ingress Controller 4.0.0. If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources. From 2f6db7c9dbb4452b3c603e163305bc10f6165a19 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:14:03 +0100 Subject: [PATCH 05/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 61d135a24..9069aec04 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -90,7 +90,7 @@ For NGINX Plus users, there is a third step to create a Secret for your license. If you're using Helm chart version `v2.x`, update your `GlobalConfiguration`, `Policy`, and `TransportServer` resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1` before upgrading to NGINX Ingress Controller 4.0.0. -If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources. +If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy, and TransportServer resources. The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources. From a87e651743b1378e4a73db0a32c5043e1a782900 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:14:25 +0100 Subject: [PATCH 06/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 9069aec04..4e6b660d3 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -132,7 +132,7 @@ spec: If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process. {{}} -Once above specified custom resources are moved to `v1` ,please run below `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid [this issue](https://github.com/nginx/kubernetes-ingress/issues/7010). +After you move the custom resources to `v1`, run the following `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid webhook errors caused by leftover `v1alpha1` resources. For details, see [GitHub issue #7010](https://github.com/nginx/kubernetes-ingress/issues/7010). ```shell kubectl patch customresourcedefinitions transportservers.k8s.nginx.org --subresource='status' --type='merge' -p '{"status":{"storedVersions": ["v1"]}}' From 027caccb85bf580dc69e199e79d48ffc2d926f7d Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:15:03 +0100 Subject: [PATCH 07/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 4e6b660d3..92e331078 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -144,7 +144,7 @@ kubectl patch customresourcedefinitions globalconfigurations.k8s.nginx.org --sub ### Configure structured logging -To configure structured logging, you must update your log deployment arguments from an integer to a string. The logs themselves can also be rendered in different formats. +To configure structured logging, you must update your log deployment arguments from an integer to a string. You can also choose different formats for the log output. {{< note >}} These options apply to NGINX Ingress Controller logs, and do not affect NGINX logs. {{< /note >}} From de6344e8d66f94c758a5f0134d4c34e4076cd639 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:15:29 +0100 Subject: [PATCH 08/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 92e331078..b86aeb708 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -161,7 +161,7 @@ To configure structured logging, you must update your log deployment arguments f {{%tab name="Helm"%}} -The Helm value of `controller.logLevel` has been changed from an integer to a string. +The Helm value `controller.logLevel` is now a string instead of an integer. To change the rendering of the log format, use the `controller.logFormat` key. From c094fc297bcc3ccc51bdf41d989de0c06e7b50a7 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:16:08 +0100 Subject: [PATCH 09/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index b86aeb708..a1d92e9e9 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -193,7 +193,7 @@ If you're using [NGINX Plus]({{< ref "/nic/overview/nginx-plus.md" >}}) with NGI The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/nic/installation/create-license-secret.md#nim">}}), which is necessary for air-gapped environments. -In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus. +Earlier versions required usage reporting through the cluster connector. This is no longer needed because it's now built into NGINX Plus. ## Upgrade a version older than v3.1.0 From a5b72f7668d19fd25d529805ccd51c4e54f3aebd Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:16:24 +0100 Subject: [PATCH 10/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index a1d92e9e9..6c381af19 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -197,7 +197,7 @@ Earlier versions required usage reporting through the cluster connector. This is ## Upgrade a version older than v3.1.0 -For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices. +Starting in version 3.1.0, NGINX Ingress Controller uses updated Helm resource names, labels, and annotations to follow Helm best practices. [See the changes.](https://github.com/nginx/kubernetes-ingress/pull/3606) When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime. From 3dc1027701d46fbb6e7354f5d088612d34741dd2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:17:04 +0100 Subject: [PATCH 11/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 6c381af19..e8e962123 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -199,9 +199,9 @@ Earlier versions required usage reporting through the cluster connector. This is Starting in version 3.1.0, NGINX Ingress Controller uses updated Helm resource names, labels, and annotations to follow Helm best practices. [See the changes.](https://github.com/nginx/kubernetes-ingress/pull/3606) -When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime. +When you upgrade with Helm from a version earlier than 3.1.0, some resources such as `Deployment`, `DaemonSet`, and `Service` are recreated. This causes downtime. -We advise updating all resources to match the new naming convention: the following steps will minimize the aforementioned downtime. +To reduce downtime, update all resources to use the new naming convention. The following steps help you do that. {{< call-out "note" >}} The following steps apply to both 2.x and 3.0.x releases. {{}} From a0f591b05e7431295769c0ba5b7706b06307a0d2 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:17:55 +0100 Subject: [PATCH 12/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index e8e962123..917699468 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -223,7 +223,7 @@ Copy the key=value under `Selector`, such as: Selector: app=nginx-ingress-nginx-ingress ``` -Checkout the latest available tag using `git checkout v{{< nic-version >}}` +Check out the latest available tag using `git checkout v{{< nic-version >}}` Navigate to `/kubernetes-ingress/charts/nginx-ingress` From 92759bdf123066b7d9c53c082d9ed4ba1488d9f9 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:20:12 +0100 Subject: [PATCH 13/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 917699468..4fd62a2ea 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -225,7 +225,7 @@ Selector: app=nginx-ingress-nginx-ingress Check out the latest available tag using `git checkout v{{< nic-version >}}` -Navigate to `/kubernetes-ingress/charts/nginx-ingress` +Go to `/kubernetes-ingress/charts/nginx-ingress` Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. From 4c72e558b6a28fdbd2c1f78e7a8c587602817549 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:20:26 +0100 Subject: [PATCH 14/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 4fd62a2ea..ada207dce 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -241,7 +241,7 @@ Run `helm upgrade` with following arguments set: --set fullnameOverride="nginx-ingress-nginx-ingress" ``` -It could look as follows: +It might look like this: ```shell helm upgrade nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="nginx-ingress-nginx-ingress" --set controller.name="" --set fullnameOverride="nginx-ingress-nginx-ingress" -f values.yaml From c8ba07937e58e03957954d0828cb91a516481bfb Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:20:41 +0100 Subject: [PATCH 15/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index ada207dce..b1e96d991 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -273,7 +273,7 @@ Copy the key=value under ```Selector```, such as: Selector: app=-nginx-ingress ``` -Checkout the latest available tag using `git checkout v{{< nic-version >}}` +Check out the latest available tag using `git checkout v{{< nic-version >}}` Navigate to `/kubernetes-ingress/charts/nginx-ingress`. From 40bd22490dfc1cb4ad9241a234b01f36cbfed347 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:20:52 +0100 Subject: [PATCH 16/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index b1e96d991..42e8c3b9f 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -275,7 +275,7 @@ Selector: app=-nginx-ingress Check out the latest available tag using `git checkout v{{< nic-version >}}` -Navigate to `/kubernetes-ingress/charts/nginx-ingress`. +Go to `/kubernetes-ingress/charts/nginx-ingress`. Update the `selectorLabels: {}` field in the `values.yaml` file located at `/kubernetes-ingress/charts/nginx-ingress` with the copied `Selector` value. From ce3b5dba9a731af4ec016a1e3971c8e49a847a16 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:21:05 +0100 Subject: [PATCH 17/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/installation/upgrade-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 42e8c3b9f..812a9490d 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -290,7 +290,7 @@ Run `helm upgrade` with following arguments set: --set controller.name="" ``` -It could look as follows: +It might look like this: ```shell helm upgrade test-release oci://ghcr.io/nginx/charts/nginx-ingress --version 0.19.0 --set controller.kind=deployment/daemonset --set controller.nginxplus=false/true --set controller.image.pullPolicy=Always --set serviceNameOverride="test-release-nginx-ingress" --set controller.name="" -f values.yaml From 6cc93b539a2fe11b226171332ed8ada2695a8ccc Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:21:24 +0100 Subject: [PATCH 18/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/releases.md b/content/nic/releases.md index 00802f96c..87c353201 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -158,7 +158,7 @@ versions: 1.25-1.32. 16 Dec 2024 With added support for [NGINX R33]({{< ref "/nginx/releases.md#nginxplusrelease-33-r33" >}}), deployments of F5 NGINX Ingress Controller using NGINX Plus now require a valid JSON Web Token to run. -Please see the [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on setting up your license `Secret`. +For full details on setting up your license `Secret`, see [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}). API Version `v1alpha1` of `GlobalConfiguration`, `Policy` and `TransportServer` resources are now deprecated. Please see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on updating your resources. From 7c098efec38027f50a1fd42a79c6a8b0d6b34240 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 11:21:38 +0100 Subject: [PATCH 19/23] Apply suggestion from @travisamartin Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com> --- content/nic/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/releases.md b/content/nic/releases.md index 87c353201..08269332a 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -161,7 +161,7 @@ With added support for [NGINX R33]({{< ref "/nginx/releases.md#nginxplusrelease- For full details on setting up your license `Secret`, see [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}). API Version `v1alpha1` of `GlobalConfiguration`, `Policy` and `TransportServer` resources are now deprecated. -Please see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on updating your resources. +For full details on updating your resources, see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}). Updates have been made to our logging library. For a while, F5 NGINX Ingress Controller has been using the [golang/glog](https://github.com/golang/glog). For this release, we have moved to the native golang library [log/slog](https://pkg.go.dev/log/slog). This change was made for these reasons: From 26bfffcf31fa468727bcf4e377c47366b5b1b9b9 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 16:38:43 +0100 Subject: [PATCH 20/23] feat: Incorporate suggestions, rename image pages --- .../installing-nic/installation-with-helm.md | 16 ++--- ...e-using-jwt.md => add-image-to-cluster.md} | 61 +++++++++---------- ...registry-image.md => registry-download.md} | 27 ++++---- content/nic/installation/upgrade-version.md | 7 ++- 4 files changed, 53 insertions(+), 58 deletions(-) rename content/nic/installation/nic-images/{get-image-using-jwt.md => add-image-to-cluster.md} (90%) rename content/nic/installation/nic-images/{get-registry-image.md => registry-download.md} (85%) diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index f102a2198..3f9bc653f 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -9,6 +9,10 @@ nd-docs: DOCS-602 This document explains how to install F5 NGINX Ingress Controller using [Helm](https://helm.sh/). +Following these steps will deploy NGINX Ingress Controller in your Kubernetes cluster with the default configuration. + +The [Helm chart parameters](#helm-chart-parameters) lists the parameters that can be configured during installation. + ## Before you begin {{< 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 >}} @@ -16,12 +20,10 @@ This document explains how to install F5 NGINX Ingress Controller using [Helm](h - A [Kubernetes Version Supported by NGINX Ingress Controller]({{< ref "/nic/technical-specifications.md#supported-kubernetes-versions" >}}) - Helm 3.0+. -There are additional requirements if you'd like to use NGINX Plus: -- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}). -- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. -- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. -- The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. -- Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. +If you would like to use NGINX Plus, there are few options: you will need to update the `controller.image.repository` field of `values-plus.yaml` accordingly. + +- [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) +- [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) ## Install the Helm chart using the OCI Registry @@ -100,8 +102,6 @@ helm install my-release -f values-plus.yaml . {{< /tabs >}} -The command deploys NGINX Ingress Controller in your Kubernetes cluster in the default configuration. The [Helm chart parameters](#helm-chart-parameters) lists the parameters that can be configured during installation. - ## Custom Resource Definitions When installing the NGINX Ingress Controller chart, Helm will also install the required custom resource definitions (CRDs). diff --git a/content/nic/installation/nic-images/get-image-using-jwt.md b/content/nic/installation/nic-images/add-image-to-cluster.md similarity index 90% rename from content/nic/installation/nic-images/get-image-using-jwt.md rename to content/nic/installation/nic-images/add-image-to-cluster.md index 1dff0c74b..09d611d26 100644 --- a/content/nic/installation/nic-images/get-image-using-jwt.md +++ b/content/nic/installation/nic-images/add-image-to-cluster.md @@ -1,5 +1,5 @@ --- -title: Get the NGINX Ingress Controller image with JWT +title: Add an NGINX Ingress Controller image to your cluster toc: true weight: 150 nd-content-type: how-to @@ -7,7 +7,7 @@ nd-product: NIC nd-docs: DOCS-1454 --- -This document describes how to pull the F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using your JWT token. +This document describes how to add an F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using a JWT token. ## Overview @@ -23,18 +23,18 @@ To list the available image tags using the Docker registry API, you will also ne {{< note >}} -You can also get the image using alternative methods: +You can also get an image using these methods: -* You can use Docker to pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. -* You can follow the [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic. +- [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. +- [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic. If you would like to use an NGINX Ingress Controller image with NGINX open source, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). {{< /note >}} -## Before You Begin +## Before you begin -You will need the following information from [MyF5](https://my.f5.com) for these steps: +To follow these steps, you will need the following pre-requisites: - A JWT Access Token (per instance) for NGINX Ingress Controller from an active NGINX Ingress Controller subscription. - The certificate (`nginx-repo.crt`) and key (`nginx-repo.key`) for each NGINX Ingress Controller instance, used to list the available image tags from the Docker registry API. @@ -70,28 +70,6 @@ You will need the following information from [MyF5](https://my.f5.com) for these --- -## Manifest Deployment - -The page ["Installation with Manifests"]({{< ref "/nic/installation/installing-nic/installation-with-manifests.md" >}}) explains how to install NGINX Ingress Controller using manifests. The following snippet is an example of a deployment: - -```yaml -spec: - serviceAccountName: nginx-ingress - imagePullSecrets: - - name: regcred - automountServiceAccountToken: true - securityContext: - seccompProfile: - type: RuntimeDefault - containers: - - image: private-registry.nginx.com/nginx-ic/nginx-plus-ingress:{{< nic-version >}} - imagePullPolicy: IfNotPresent - name: nginx-plus-ingress -``` - -The `imagePullSecrets` and `containers.image` lines represent the Kubernetes secret, as well as the registry and version of NGINX Ingress Controller we are going to deploy. - ---- ## Helm Deployment @@ -193,11 +171,30 @@ You can also use the certificate and key from the MyF5 portal and the Docker reg } ``` ---- +## Manifest Deployment + +The page ["Installation with Manifests"]({{< ref "/nic/installation/installing-nic/installation-with-manifests.md" >}}) explains how to install NGINX Ingress Controller using manifests. The following snippet is an example of a deployment: + +```yaml +spec: + serviceAccountName: nginx-ingress + imagePullSecrets: + - name: regcred + automountServiceAccountToken: true + securityContext: + seccompProfile: + type: RuntimeDefault + containers: + - image: private-registry.nginx.com/nginx-ic/nginx-plus-ingress:{{< nic-version >}} + imagePullPolicy: IfNotPresent + name: nginx-plus-ingress +``` + +The `imagePullSecrets` and `containers.image` lines represent the Kubernetes secret, as well as the registry and version of NGINX Ingress Controller we are going to deploy. -## Pulling an Image for Local Use +## Download an image for local use -If you need to pull the image for local use to then push to a different container registry, use this command: +If you need to download an image for local use (Such as to push to a different container registry), use this command: ```shell docker login private-registry.nginx.com --username= --password=none diff --git a/content/nic/installation/nic-images/get-registry-image.md b/content/nic/installation/nic-images/registry-download.md similarity index 85% rename from content/nic/installation/nic-images/get-registry-image.md rename to content/nic/installation/nic-images/registry-download.md index 9cf8dd08a..2196a106a 100644 --- a/content/nic/installation/nic-images/get-registry-image.md +++ b/content/nic/installation/nic-images/registry-download.md @@ -1,5 +1,5 @@ --- -title: Get NGINX Ingress Controller from the F5 Registry +title: Download NGINX Ingress Controller from the F5 Registry toc: true weight: 100 nd-content-type: how-to @@ -7,20 +7,24 @@ nd-product: NIC nd-docs: DOCS-605 --- -Learn how to pull an F5 NGINX Plus Ingress Controller image from the official F5 Docker registry and upload it to your private registry. +This page describes how to download an F5 NGINX Plus Ingress Controller image from the official F5 Docker registr. The F5 Registry images include versions with NGINX App Protect WAF and NGINX App Protect DoS. -This guide covers the prerequisites, image tagging, and troubleshooting steps. +This guide covers the prerequisites, how to images, upload images to your private registry, and troubleshooting steps. ## Before you begin -Before you start, you'll need these installed on your machine: +To follow these steps, you will need the following pre-requisites: +- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}). - [Docker v18.09 or higher](https://docs.docker.com/engine/release-notes/18.09/). -- An NGINX Ingress Controller subscription. Download both the certificate (*nginx-repo.crt*) and key (*nginx-repo.key*) from the [MyF5 Customer Portal](https://my.f5.com). Keep in mind that an NGINX Plus certificate and key won't work for for the steps in this guide. ---- +You can also get the NGINX Ingress Controller image using the following alternate methods: + +- [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}). +- [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) +- For NGINX Open Source, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub. ## Set up Docker for F5 Container Registry @@ -36,7 +40,7 @@ The steps provided are for Linux. For Mac or Windows, consult the [Docker for Ma ## Pull the image -Next, pull the image you need from `private-registry.nginx.com`. To find the correct image, consult the [Tech Specs guide]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}). +Next, pull the image you need from `private-registry.nginx.com`. To find the correct image, consult the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}). To pull an image, follow these steps. Replace `` with the specific version you need, for example, `{{< nic-version >}}`. @@ -182,12 +186,3 @@ If you encounter issues while following this guide, here are solutions to common - **Failed to push to private registry** - **Likely Cause**: Not logged into your private registry or incorrect image tagging. - **Solution**: Verify login status and correct image tagging before pushing. Consult the [Docker documentation](https://docs.docker.com/docker-hub/repos/) for more details. - - -## Alternative installation options - -You can also get the NGINX Ingress Controller image using the following alternate methods: - -- [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}). -- [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) using the source code from the GitHub repository and your NGINX Plus subscription certificate and key. -- For NGINX Ingress Controller using NGINX OSS, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub. diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 812a9490d..a2d2dd87b 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -82,9 +82,12 @@ The instructions in this section are intended only for users upgrading from NGIN This section provides step-by-step instructions for upgrading 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. +There are two necessary steps required -For NGINX Plus users, there is a third step to create a Secret for your license. +- Update the `apiVersion` value of custom resources +- Configure structured logging. + +If you want to use NGINX Plus, you will also need to follow the [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}) topic. ### Update custom resource apiVersion From a062bc430b76f1973b4376fc2853bda5d1a45f0a Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 21 Jul 2025 17:09:58 +0100 Subject: [PATCH 21/23] fix: Update tech specs with new links --- content/nic/technical-specifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nic/technical-specifications.md b/content/nic/technical-specifications.md index 794d5d818..d71e9852a 100644 --- a/content/nic/technical-specifications.md +++ b/content/nic/technical-specifications.md @@ -62,7 +62,7 @@ _NGINX Plus images include NGINX Plus R34._ #### **F5 Container registry** -NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Get the NGINX Ingress Controller image with JWT]({{}}) and [Get the F5 Registry NGINX Ingress Controller image]({{}}) topics. +NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) and [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topics. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Additional modules
| F5 Container Registry Image | Architectures | From 7063cf5057037cecf1c312c1e1ef146d7b3f04d3 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 22 Jul 2025 15:54:19 +0100 Subject: [PATCH 22/23] feat: Rename image docs, update references --- .../build-nginx-ingress-controller.md | 4 +- .../nic/installation/create-license-secret.md | 20 +++--- .../installation-with-manifests.md | 8 +-- .../installation-with-operator.md | 10 +-- .../app-protect-dos/installation.md | 4 +- .../app-protect-waf-v5/installation.md | 4 +- .../app-protect-waf/installation.md | 4 +- .../nic-images/add-image-to-cluster.md | 62 ++----------------- .../nic-images/registry-download.md | 18 +++--- content/nic/releases.md | 2 +- 10 files changed, 42 insertions(+), 94 deletions(-) diff --git a/content/nic/installation/build-nginx-ingress-controller.md b/content/nic/installation/build-nginx-ingress-controller.md index 560a46ca4..e89a1ec03 100644 --- a/content/nic/installation/build-nginx-ingress-controller.md +++ b/content/nic/installation/build-nginx-ingress-controller.md @@ -199,5 +199,5 @@ If you prefer not to build your own NGINX Ingress Controller image, you can use **NGINX Plus Ingress Controller**: You have two options for this: -- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image" >}}) topic. -- Use your NGINX Ingress Controller subscription JWT token to get the image. View the [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic. +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. +- Use your NGINX Ingress Controller subscription JWT token to get the image. View the [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic. diff --git a/content/nic/installation/create-license-secret.md b/content/nic/installation/create-license-secret.md index 3b13bc543..4efb08d7a 100644 --- a/content/nic/installation/create-license-secret.md +++ b/content/nic/installation/create-license-secret.md @@ -27,20 +27,21 @@ The JWT is required for validating your subscription and reporting telemetry dat ### Create the Secret -The JWT needs to be configured before deploying NGINX Ingress Controller. The JWT will be stored in a Kubernetes Secret of type `nginx.com/license`, and can be created with the following command. +The JWT needs to be configured before deploying NGINX Ingress Controller. + +It must be stored in a Kubernetes Secret of type `nginx.com/license` in the same namespace as your NGINX Ingress Controller pod(s). + +Create the Secret with the following command: ```shell -kubectl create secret generic license-token --from-file=license.jwt= --type=nginx.com/license -n +kubectl create secret generic license-token --from-file=license.jwt= --type=nginx.com/license -n ``` -You can now delete the downloaded `.jwt` file. -{{< note >}} -The Secret needs to be in the same Namespace as the NGINX Ingress Controller Pod(s). -{{}} +Once created, you can download the `.jwt` file. {{< include "/nic/installation/jwt-password-note.md" >}} -### Use the NGINX Plus license Secret +### Add the license Secret to your deployment If using a name other than the default `license-token`, provide the name of this Secret when installing NGINX Ingress Controller: @@ -50,7 +51,7 @@ If using a name other than the default `license-token`, provide the name of this Specify the Secret name using the `controller.mgmt.licenseTokenSecretName` Helm value. -For detailed guidance on creating the Management block via Helm, refer to the [Helm configuration documentation]({{< ref "/nic/installation/installing-nic/installation-with-helm/#configuration" >}}). +For detailed guidance on creating the Management block with Helm, refer to the [Helm configuration documentation]({{< ref "/nic/installation/installing-nic/installation-with-helm/#configuration" >}}). {{% /tab %}} @@ -129,11 +130,8 @@ Specify the SSL trusted certificate Secret name in the `ssl-trusted-certificate- {{}} -
- Once these Secrets are created and configured, you can now [install NGINX Ingress Controller ]({{< ref "/nic/installation/installing-nic/" >}}). - ## What’s reported and how it’s protected {#telemetry} NGINX Plus reports the following data every hour by default: diff --git a/content/nic/installation/installing-nic/installation-with-manifests.md b/content/nic/installation/installing-nic/installation-with-manifests.md index 5e04293f8..7cc5e8372 100644 --- a/content/nic/installation/installing-nic/installation-with-manifests.md +++ b/content/nic/installation/installing-nic/installation-with-manifests.md @@ -9,20 +9,20 @@ nd-docs: DOCS-603 This guide explains how to use Manifests to install F5 NGINX Ingress Controller, then create both common and custom resources and set up role-based access control. -## Before you start +## Before you begin If you are using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< ref "/nic/installation/create-license-secret.md" >}}). ### Get the NGINX Controller Image -{{< note >}} Always use the latest stable release listed on the [releases page]({{< ref "/nic/releases.md" >}}). {{< /note >}} +{{< call-out "note" >}} Always use the latest stable release listed on the [releases page]({{< ref "/nic/releases.md" >}}). {{< /call-out >}} Choose one of the following methods to get the NGINX Ingress Controller image: - **NGINX Ingress Controller**: Download the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). - **NGINX Plus Ingress Controller**: You have two options for this, both requiring an NGINX Ingress Controller subscription. - - Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. - - The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- - [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. +- - [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) - **Build your own image**: To build your own image, follow the [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic. ### Clone the repository diff --git a/content/nic/installation/installing-nic/installation-with-operator.md b/content/nic/installation/installing-nic/installation-with-operator.md index 459d7cfd1..fc659244a 100644 --- a/content/nic/installation/installing-nic/installation-with-operator.md +++ b/content/nic/installation/installing-nic/installation-with-operator.md @@ -9,17 +9,17 @@ nd-docs: DOCS-604 This document explains how to install F5 NGINX Ingress Controller using NGINX Ingress Operator. -## Before you start +## Before you begin If you're using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< ref "/nic/installation/create-license-secret.md" >}}). {{< note >}} We recommend the most recent stable version of NGINX Ingress Controller, available on the GitHub repository's [releases page]({{< ref "/nic/releases.md" >}}). {{< /note >}} 1. Make sure you have access to the NGINX Ingress Controller image: - - For NGINX Ingress Controller, use the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). - - For NGINX Plus Ingress Controller, view the [Get the F5 Registry NGINX Ingress Controller image]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic for details on how to pull the image from the F5 Docker registry. - - The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. - - The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. +- - For NGINX Ingress Controller, use the image `nginx/nginx-ingress` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress). +- - For NGINX Plus Ingress Controller, view the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download" >}}) topic for details on how to pull the image from the F5 Docker registry. +- - The [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic describes how to use your subscription JWT token to get the image. +- - The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry. 1. Install the NGINX Ingress Operator following the [instructions](https://github.com/nginx/nginx-ingress-helm-operator/blob/main/docs/installation.md). 1. Create the SecurityContextConstraint as outlined in the ["Getting Started" instructions](https://github.com/nginx/nginx-ingress-helm-operator/blob/main/README.md#getting-started). diff --git a/content/nic/installation/integrations/app-protect-dos/installation.md b/content/nic/installation/integrations/app-protect-dos/installation.md index 75a4439ae..0a50deb65 100644 --- a/content/nic/installation/integrations/app-protect-dos/installation.md +++ b/content/nic/installation/integrations/app-protect-dos/installation.md @@ -226,5 +226,5 @@ For more information, see the [Configuration guide]({{< ref "/nic/installation/i If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. - - The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. + - The [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic describes how to use your subscription JWT token to get the image. diff --git a/content/nic/installation/integrations/app-protect-waf-v5/installation.md b/content/nic/installation/integrations/app-protect-waf-v5/installation.md index 2cdc5964c..680f767fa 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/installation.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/installation.md @@ -501,5 +501,5 @@ For more information, see the [Configuration guide]({{< ref "/nic/installation/i If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. -- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. +- The [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic describes how to use your subscription JWT token to get the image. diff --git a/content/nic/installation/integrations/app-protect-waf/installation.md b/content/nic/installation/integrations/app-protect-waf/installation.md index ed7732450..b4170499d 100644 --- a/content/nic/installation/integrations/app-protect-waf/installation.md +++ b/content/nic/installation/integrations/app-protect-waf/installation.md @@ -217,5 +217,5 @@ For more information, see the [Configuration guide]({{< ref "/nic/installation/i If you prefer not to build your own NGINX Ingress Controller image, you can use pre-built images. Here are your options: -- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic. -- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image. +- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. +- The [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic describes how to use your subscription JWT token to get the image. diff --git a/content/nic/installation/nic-images/add-image-to-cluster.md b/content/nic/installation/nic-images/add-image-to-cluster.md index 09d611d26..e1285f995 100644 --- a/content/nic/installation/nic-images/add-image-to-cluster.md +++ b/content/nic/installation/nic-images/add-image-to-cluster.md @@ -9,67 +9,17 @@ nd-docs: DOCS-1454 This document describes how to add an F5 NGINX Plus Ingress Controller image from the F5 Docker registry into your Kubernetes cluster using a JWT token. -## Overview - -{{< important >}} - -An NGINX Plus subscription certificate and key will not work with the F5 Docker registry. - -For NGINX Ingress Controller, you must have an NGINX Ingress Controller subscription -- download the NGINX Plus Ingress Controller (per instance) JWT access token from [MyF5](https://my.f5.com). - -To list the available image tags using the Docker registry API, you will also need to download the NGINX Plus Ingress Controller (per instance) certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) from [MyF5](https://my.f5.com). - -{{< /important >}} - -{{< note >}} - -You can also get an image using these methods: - -- [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic. -- [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic. - -If you would like to use an NGINX Ingress Controller image with NGINX open source, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). - -{{< /note >}} - ## Before you begin -To follow these steps, you will need the following pre-requisites: - -- A JWT Access Token (per instance) for NGINX Ingress Controller from an active NGINX Ingress Controller subscription. -- The certificate (`nginx-repo.crt`) and key (`nginx-repo.key`) for each NGINX Ingress Controller instance, used to list the available image tags from the Docker registry API. - -## Prepare NGINX Ingress Controller +To follow these steps, you will need the following pre-requisite: -1. Choose your desired [NGINX Ingress Controller Image]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}). -1. Log into the [MyF5 Portal](https://my.f5.com/), navigate to your subscription details, and download the relevant .cert, .key and .JWT files. -1. Create a Kubernetes secret using the JWT token. You should use `cat` to view the contents of the JWT token and store the output for use in later steps. -1. Ensure there are no additional characters or extra whitespace that might have been accidentally added. This will break authorization and prevent the NGINX Ingress Controller image from being downloaded. -1. Modify your deployment (manifest or Helm) to use the Kubernetes secret created in step 3. -1. Deploy NGINX Ingress Controller into your Kubernetes cluster and verify that the installation has been successful. +- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}) -## Using the JWT token in a Docker Config Secret - -1. Create a Kubernetes `docker-registry` secret type on the cluster, using the JWT token as the username and `none` for password (as the password is not used). The name of the docker server is `private-registry.nginx.com`. - - ```shell - kubectl create secret docker-registry regcred --docker-server=private-registry.nginx.com --docker-username= --docker-password=none [-n nginx-ingress] - ``` - - It is important that the `--docker-username=` contains the contents of the token and is not pointing to the token itself. Ensure that when you copy the contents of the JWT token, there are no additional characters or extra whitespaces. This can invalidate the token and cause 401 errors when trying to authenticate to the registry. - -1. Confirm the details of the created secret by running: - - ```shell - kubectl get secret regcred --output=yaml - ``` - -1. You can now use the newly created Kubernetes secret in Helm and manifest deployments. - -{{< include "/nic/installation/jwt-password-note.md" >}} - ---- +You can also get the NGINX Ingress Controller image using the following alternate methods: +- [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) +- [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) +- For NGINX Open Source, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub ## Helm Deployment diff --git a/content/nic/installation/nic-images/registry-download.md b/content/nic/installation/nic-images/registry-download.md index 2196a106a..2d4a62c98 100644 --- a/content/nic/installation/nic-images/registry-download.md +++ b/content/nic/installation/nic-images/registry-download.md @@ -7,24 +7,22 @@ nd-product: NIC nd-docs: DOCS-605 --- -This page describes how to download an F5 NGINX Plus Ingress Controller image from the official F5 Docker registr. +This page describes how to download an F5 NGINX Plus Ingress Controller image from the official F5 Docker registry. The F5 Registry images include versions with NGINX App Protect WAF and NGINX App Protect DoS. -This guide covers the prerequisites, how to images, upload images to your private registry, and troubleshooting steps. - ## Before you begin To follow these steps, you will need the following pre-requisites: -- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}). -- [Docker v18.09 or higher](https://docs.docker.com/engine/release-notes/18.09/). +- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}}) +- [Docker v18.09 or higher](https://docs.docker.com/engine/release-notes/18.09/) You can also get the NGINX Ingress Controller image using the following alternate methods: -- [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}). +- [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) - [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) -- For NGINX Open Source, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub. +- For NGINX Open Source, you can pull [an image from DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) ## Set up Docker for F5 Container Registry @@ -40,9 +38,11 @@ The steps provided are for Linux. For Mac or Windows, consult the [Docker for Ma ## Pull the image -Next, pull the image you need from `private-registry.nginx.com`. To find the correct image, consult the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}). +Identify which image you need using the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) topic. + +Next, pull the image from `private-registry.nginx.com`. -To pull an image, follow these steps. Replace `` with the specific version you need, for example, `{{< nic-version >}}`. +Replace `` with the specific version you need, for example, `{{< nic-version >}}`. - For NGINX Plus Ingress Controller, run: diff --git a/content/nic/releases.md b/content/nic/releases.md index 08269332a..15111013a 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -1689,7 +1689,7 @@ We will provide technical support for NGINX Ingress Controller on any Kubernetes ### Upgrade - For NGINX, use the 1.12.1 image from our DockerHub: `nginx/nginx-ingress:1.12.1`, `nginx/nginx-ingress:1.12.1-alpine` or `nginx/nginx-ingress:1.12.1-ubi` -- For NGINX Plus, use the 1.12.1 image from the F5 Container Registry - see [the documentation here]({{< ref "/nic/installation/nic-images/get-registry-image.md">}}) +- For NGINX Plus, use the 1.12.1 image from the F5 Container Registry - see [the documentation here]({{< ref "/nic/installation/nic-images/registry-download.md">}}) - Alternatively, you can also build your own image using the 1.12.1 source code. - For Helm, use version 0.10.1 of the chart. From cbbef0e626457db6eaedad4b49c68cbd68a03e15 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 22 Jul 2025 16:55:57 +0100 Subject: [PATCH 23/23] feat: Update Helm IA for add image to cluster --- .../nic-images/add-image-to-cluster.md | 161 +++++++++--------- 1 file changed, 85 insertions(+), 76 deletions(-) diff --git a/content/nic/installation/nic-images/add-image-to-cluster.md b/content/nic/installation/nic-images/add-image-to-cluster.md index e1285f995..492a1eb86 100644 --- a/content/nic/installation/nic-images/add-image-to-cluster.md +++ b/content/nic/installation/nic-images/add-image-to-cluster.md @@ -21,13 +21,65 @@ You can also get the NGINX Ingress Controller image using the following alternat - [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) - For NGINX Open Source, you can pull the [nginx/nginx-ingress image](https://hub.docker.com/r/nginx/nginx-ingress/) from DockerHub -## Helm Deployment +## Helm deployments -If you are using Helm for deployment, there are two main methods: using *sources* or *charts*. +If you are using Helm for deployment, there are two main methods: using a _chart_ or _source_. -### Helm Source +### Add the image from chart -The [Installation with Helm ]({{< ref "/nic/installation/installing-nic/installation-with-helm.md#managing-the-chart-via-sources" >}}) documentation has a section describing how to use sources: these are the unique steps for Docker secrets using JWT tokens. +The following command installs NGINX Ingress Controller with a Helm chart, passing required arguments using the `set` parameter. + +```shell +helm install my-release -n nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} --set controller.image.repository=private-registry.nginx.com/nginx-ic/nginx-plus-ingress --set controller.image.tag={{< nic-version >}} --set controller.nginxplus=true --set controller.serviceAccount.imagePullSecretName=regcred +``` + +You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, for example: + +```shell +curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq +``` +```text +{ +"name": "nginx-ic/nginx-plus-ingress", +"tags": [ + "{{< nic-version >}}-alpine", + "{{< nic-version >}}-alpine-fips", + "{{< nic-version >}}-ubi", + "{{< nic-version >}}" +] +} +``` + +```shell +curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq +``` +```text +{ +"name": "nginx-ic-nap/nginx-plus-ingress", +"tags": [ + "{{< nic-version >}}-alpine-fips", + "{{< nic-version >}}-ubi", + "{{< nic-version >}}" +] +} +``` + +```shell +$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key --cert | jq +``` +```text +{ +"name": "nginx-ic-dos/nginx-plus-ingress", +"tags": [ + "{{< nic-version >}}-ubi", + "{{< nic-version >}}" +] +} +``` + +### Add the image from source + +The [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md#install-the-helm-chart-from-source" >}}) documentation has a section describing how to use sources: these are the unique steps for Docker secrets using JWT tokens. 1. Clone the NGINX [`kubernetes-ingress` repository](https://github.com/nginx/kubernetes-ingress). 1. Navigate to the `charts/nginx-ingress` folder of your local clone. @@ -37,36 +89,36 @@ The [Installation with Helm ]({{< ref "/nic/installation/installing-nic/installa 1. Change the `nginxplus` argument to `true`. 1. Change the `repository` argument to the NGINX Ingress Controller image you intend to use. - 2. Add an argument to `imagePullSecretName` or `imagePullSecretsNames` to allow Docker to pull the image from the private registry. - - The following code block shows snippets of the parameters you will need to change, and an example of their contents: - - ```yaml - ## Deploys the Ingress Controller for NGINX Plus - nginxplus: true - ## Truncated fields - ## ... - ## ... - image: - ## The image repository for the desired NGINX Ingress Controller image - repository: private-registry.nginx.com/nginx-ic/nginx-plus-ingress - - ## The version tag - tag: {{< nic-version >}} - - serviceAccount: - ## The annotations of the service account of the Ingress Controller pods. - annotations: {} + 1. Add an argument to `imagePullSecretName` or `imagePullSecretsNames` to allow Docker to pull the image from the private registry. - ## Truncated fields - ## ... - ## ... +The following code block shows snippets of the parameters you will need to change, and an example of their contents: - ## The name of the secret containing docker registry credentials. - ## Secret must exist in the same namespace as the helm release. - ## Note that also imagePullSecretsNames can be used here if multiple secrets need to be set. - imagePullSecretName: regcred - ``` +```yaml +## Deploys the Ingress Controller for NGINX Plus +nginxplus: true +## Truncated fields +## ... +## ... +image: +## The image repository for the desired NGINX Ingress Controller image +repository: private-registry.nginx.com/nginx-ic/nginx-plus-ingress + +## The version tag +tag: {{< nic-version >}} + +serviceAccount: + ## The annotations of the service account of the Ingress Controller pods. + annotations: {} + +## Truncated fields +## ... +## ... + + ## The name of the secret containing docker registry credentials. + ## Secret must exist in the same namespace as the helm release. + ## Note that also imagePullSecretsNames can be used here if multiple secrets need to be set. + imagePullSecretName: regcred +``` With the modified `values.yaml` file, you can now use Helm to install NGINX Ingress Controller, for example: @@ -78,50 +130,7 @@ The above command will install NGINX Ingress Controller in the `nginx-ingress` n If the namespace does not exist, `--create-namespace` will create it. Using `-f values.yaml` tells Helm to use the `values.yaml` file that you modified earlier with the settings you want to apply for your NGINX Ingress Controller deployment. - -### Helm Chart - -If you want to install NGINX Ingress Controller using the charts method, the following is an example of using the command line to pass the required arguments using the `set` parameter. - -```shell -helm install my-release -n nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} --set controller.image.repository=private-registry.nginx.com/nginx-ic/nginx-plus-ingress --set controller.image.tag={{< nic-version >}} --set controller.nginxplus=true --set controller.serviceAccount.imagePullSecretName=regcred -``` -You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, for example: - -```shell - $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq - - { - "name": "nginx-ic/nginx-plus-ingress", - "tags": [ - "{{< nic-version >}}-alpine", - "{{< nic-version >}}-alpine-fips", - "{{< nic-version >}}-ubi", - "{{< nic-version >}}" - ] - } - - $ curl --key --cert | jq - { - "name": "nginx-ic-nap/nginx-plus-ingress", - "tags": [ - "{{< nic-version >}}-alpine-fips", - "{{< nic-version >}}-ubi", - "{{< nic-version >}}" - ] - } - - $ curl --key --cert | jq - { - "name": "nginx-ic-dos/nginx-plus-ingress", - "tags": [ - "{{< nic-version >}}-ubi", - "{{< nic-version >}}" - ] - } -``` - -## Manifest Deployment +## Manifest deployment The page ["Installation with Manifests"]({{< ref "/nic/installation/installing-nic/installation-with-manifests.md" >}}) explains how to install NGINX Ingress Controller using manifests. The following snippet is an example of a deployment: