From 70350764bfe60409da149d475d1580f5af6e4569 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 15 Jul 2025 17:26:11 +0100 Subject: [PATCH 01/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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/31] 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: From 490def156f66d5eef9adecdf1235ed6ae6730f0b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 14:50:47 +0100 Subject: [PATCH 24/31] feat: Update NIC Docker docs, related files --- .../download-certificates-from-myf5.md | 9 +++ .../download-jwt-from-myf5.md | 13 ++++- .../credential-download-instructions.md | 26 +++++++++ .../use-cases/docker-registry-instructions.md | 49 ++++++++++++++++ .../installing-nginx-docker.md | 57 ++----------------- .../nic-images/add-image-to-cluster.md | 14 +++-- .../nic-images/registry-download.md | 38 +++++++------ documentation/README.md | 1 + documentation/include-files.md | 43 ++++++++++++++ documentation/style-guide.md | 21 ------- 10 files changed, 174 insertions(+), 97 deletions(-) create mode 100644 content/includes/licensing-and-reporting/download-certificates-from-myf5.md create mode 100644 content/includes/use-cases/credential-download-instructions.md create mode 100644 content/includes/use-cases/docker-registry-instructions.md create mode 100644 documentation/include-files.md diff --git a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md new file mode 100644 index 000000000..37d68957a --- /dev/null +++ b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md @@ -0,0 +1,9 @@ +--- +files: +- content/includes/use-cases/credential-download-instructions.md +--- + +1. Log in to [MyF5](https://my.f5.com/manage/s/). +1. Go to **My Products and Plans** > **Subscriptions**. +1. Select the product subscription. +1. Download the **SSL Certificate** and **Private Key** files. \ No newline at end of file diff --git a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md index af947d320..3b117934f 100644 --- a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md @@ -1,8 +1,19 @@ --- docs: +files: +- content/includes/nim/docker/docker-registry-login.md +- content/includes/use-cases/credential-download-instructions.md +- content/nap-waf/v5/admin-guide/install.md +- content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md +- content/nginx-one/connect-instances/connect-nginx-plus-container-images-to-nginx-one.md +- content/nim/admin-guide/add-license.md +- content/nim/deploy/docker/deploy-nginx-plus-and-agent-docker.md +- content/nim/disconnected/add-license-disconnected-deployment.md +- content/solutions/about-subscription-licenses.md +- content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md --- 1. Log in to [MyF5](https://my.f5.com/manage/s/). 2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. -3. Find your NGINX products or services subscription, and select the **Subscription ID** for details. +3. Find your NGINX subscription, and select the **Subscription ID** for details. 4. Download the **JSON Web Token** from the subscription page. diff --git a/content/includes/use-cases/credential-download-instructions.md b/content/includes/use-cases/credential-download-instructions.md new file mode 100644 index 000000000..a936057d8 --- /dev/null +++ b/content/includes/use-cases/credential-download-instructions.md @@ -0,0 +1,26 @@ +--- +files: +- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md +- content/nic/installation/nic-images/registry-download.md +--- + + +In order to obtain a container image, you will need the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. + +These files grant access to the package repository from which the script will download the NGINX Plus package: + +{{< tabs name="product_keys" >}} + +{{< tab name="JSON Web Token" >}} + +{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} + +{{< /tab >}} + +{{< tab name="SSL" >}} + +{{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}} + +{{< /tab >}} + +{{< /tabs >}} \ No newline at end of file diff --git a/content/includes/use-cases/docker-registry-instructions.md b/content/includes/use-cases/docker-registry-instructions.md new file mode 100644 index 000000000..ea0aeb019 --- /dev/null +++ b/content/includes/use-cases/docker-registry-instructions.md @@ -0,0 +1,49 @@ +--- +files: +- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md +- content/nic/installation/nic-images/registry-download.md +--- + +This step describes how to use Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`. + +{{< call-out "note" >}} + +The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. + +For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/). + +{{< /call-out >}} + +{{}} + +{{%tab name="JSON Web Token"%}} + +Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents. + +Log in to the Docker registry using the contents of the JSON Web Token file: + +```shell +docker login private-registry.nginx.com --username= --password=none +``` + +{{% /tab %}} + +{{%tab name="SSL"%}} + +Create a directory and copy your certificate and key to this directory: + +```shell +mkdir -p /etc/docker/certs.d/private-registry.nginx.com +cp /etc/docker/certs.d/private-registry.nginx.com/client.cert +cp /etc/docker/certs.d/private-registry.nginx.com/client.key +``` + +Log in to the Docker registry: + +```shell +docker login private-registry.nginx.com +``` + +{{% /tab %}} + +{{% /tabs %}} \ No newline at end of file diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md index b47f900e3..7988f8b8c 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md @@ -88,61 +88,13 @@ where: - the `jq` command is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed. +### Download your subscription credential files +{{< include "use-cases/credential-download-instructions.md" >}} -### Download the JSON Web Token or NGINX Plus certificate and key {#myf5-download} +### Set up Docker for the F5 Container Registry -Before you get a container image, you should provide the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. These files grant access to the package repository from which the script will download the NGINX Plus package: - -{{}} - -{{%tab name="JSON Web Token"%}} -{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} -{{% /tab %}} - -{{%tab name="SSL"%}} -1. Log in to the [MyF5](https://my.f5.com) customer portal. -2. Go to **My Products and Plans** > **Subscriptions**. -3. Select the product subscription. -4. Download the **SSL Certificate** and **Private Key** files. -{{% /tab %}} - -{{% /tabs %}} - -### Set up Docker for NGINX Plus container registry - -Set up Docker to communicate with the NGINX Container Registry located at `private-registry.nginx.com`. - -{{}} - -{{%tab name="JSON Web Token"%}} -Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents. - -Log in to the docker registry using the contents of the JSON Web Token file: - -```shell -docker login private-registry.nginx.com --username= --password=none -``` -{{% /tab %}} - -{{%tab name="SSL"%}} -Create a directory and copy your certificate and key to this directory: - -```shell -mkdir -p /etc/docker/certs.d/private-registry.nginx.com -cp /etc/docker/certs.d/private-registry.nginx.com/client.cert -cp /etc/docker/certs.d/private-registry.nginx.com/client.key -``` -The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/). - -Log in to the docker registry: - -```shell -docker login private-registry.nginx.com -``` -{{% /tab %}} - -{{% /tabs %}} +{{< include "use-cases/docker-registry-instructions.md" >}} ### Pull the image @@ -192,7 +144,6 @@ For NGINX modules, run: docker pull private-registry.nginx.com/nginx-plus/modules: ``` - {{< include "security/jwt-password-note.md" >}} ### Push the image to your private registry 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 492a1eb86..f07d77ff4 100644 --- a/content/nic/installation/nic-images/add-image-to-cluster.md +++ b/content/nic/installation/nic-images/add-image-to-cluster.md @@ -36,9 +36,9 @@ helm install my-release -n nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingres 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 +curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert ``` -```text +```json { "name": "nginx-ic/nginx-plus-ingress", "tags": [ @@ -51,9 +51,9 @@ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list ``` ```shell -curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq +curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert ``` -```text +```json { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ @@ -65,9 +65,9 @@ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/ ``` ```shell -$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key --cert | jq +curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key --cert ``` -```text +```json { "name": "nginx-ic-dos/nginx-plus-ingress", "tags": [ @@ -77,6 +77,8 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tag } ``` +The `jq` command was used in these examples to make the JSON output easier to read. + ### 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. diff --git a/content/nic/installation/nic-images/registry-download.md b/content/nic/installation/nic-images/registry-download.md index 2d4a62c98..c37c00e05 100644 --- a/content/nic/installation/nic-images/registry-download.md +++ b/content/nic/installation/nic-images/registry-download.md @@ -15,7 +15,6 @@ The F5 Registry images include versions with NGINX App Protect WAF and NGINX App 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/) You can also get the NGINX Ingress Controller image using the following alternate methods: @@ -24,17 +23,13 @@ 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 [an image from DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) -## Set up Docker for F5 Container Registry +### Download your subscription credential files -Start by setting up Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`. If you're using Linux, follow these steps to create a directory and add your certificate and key: +{{< include "use-cases/credential-download-instructions.md" >}} -```shell -mkdir -p /etc/docker/certs.d/private-registry.nginx.com -cp /etc/docker/certs.d/private-registry.nginx.com/client.cert -cp /etc/docker/certs.d/private-registry.nginx.com/client.key -``` +### Set up Docker for the F5 Container Registry -The steps provided are for Linux. For Mac or Windows, consult the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/). +{{< include "use-cases/docker-registry-instructions.md" >}} ## Pull the image @@ -70,7 +65,6 @@ Replace `` with the specific version you need, for example, `{{< ni docker pull private-registry.nginx.com/nap/waf-enforcer: ``` - - For NGINX Plus Ingress Controller with NGINX App Protect DoS, run: ```shell @@ -83,10 +77,14 @@ Replace `` with the specific version you need, for example, `{{< ni docker pull private-registry.nginx.com/nginx-ic-nap-dos/nginx-plus-ingress: ``` -You can use the Docker registry API to list the available image tags by running the following commands. Replace `` with the location of your client key and `` with the location of your client certificate. The `jq` command is used to format the JSON output for easier reading. +You can use the Docker registry API to list the available image tags by running the following commands. Replace `` with the location of your client key and `` with the location of your client certificate. + +The `jq` command was used in these examples to make the JSON output easier to read. +```shell +curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert +``` ```json -$ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key --cert | jq { "name": "nginx-ic/nginx-plus-ingress", "tags": [ @@ -96,8 +94,12 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/li "{{< nic-version >}}" ] } +``` -$ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert | jq +```shell +curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key --cert +``` +```json { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ @@ -106,8 +108,12 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tag "{{< nic-version >}}" ] } +``` -$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key --cert | jq +```shell +curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key --cert +``` +```json { "name": "nginx-ic-dos/nginx-plus-ingress", "tags": [ @@ -169,7 +175,7 @@ After pulling the image, tag it and upload it to your private registry. ## Troubleshooting -If you encounter issues while following this guide, here are solutions to common problems: +If you encounter issues while following this guide, here are some possible solutions: - **Certificate errors** - **Likely Cause**: Incorrect certificate or key location, or using an NGINX Plus certificate. @@ -181,7 +187,7 @@ If you encounter issues while following this guide, here are solutions to common - **Can't pull the image** - **Likely Cause**: Mismatched image name or tag. - - **Solution**: Double-check the image name and tag against the [Tech Specs guide]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}). + - **Solution**: Double-check the image name and tag matches the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) document. - **Failed to push to private registry** - **Likely Cause**: Not logged into your private registry or incorrect image tagging. diff --git a/documentation/README.md b/documentation/README.md index 6cae42e2e..169a891f5 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -19,4 +19,5 @@ If you're interested in contributing to the [NGINX documentation website](https: - [Managing content with Hugo](/documentation/writing-hugo.md) - [Proposals](/documentation/proposals/README.md) - [Set up pre-commit](/documentation/pre-commit.md) +- [Using include files](/documentation/include-files.md) - [Writing style guide](/documentation/style-guide.md) diff --git a/documentation/include-files.md b/documentation/include-files.md new file mode 100644 index 000000000..f52602164 --- /dev/null +++ b/documentation/include-files.md @@ -0,0 +1,43 @@ +# Using Include files + +_Include files_, often referred to as _includes_, are Markdown files with self-contained text fragments used by Hugo for content re-use. + +They enable contributors to maintain a single source of truth for information that is often repeated, such as how to download credential files. + +We use them to [avoid repeating ourselves](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and create consistency in similar instructional steps. + +Include files are designed to be context-agnostic and should not rely on or assume any prior content. + +The files are located in the [content/includes](https://github.com/nginxinc/docs/tree/main/content/includes) folder, and are implemented using the Hugo `include` shortcode: + +```text +{{< include "use-cases/docker-registry-instructions.md" >}} +``` + +Putting the previous example in any Markdown file would embed the contents of `content/includes/use-cases/docker-registry-instructions.md` wherever the shortcode was used. + +For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/writing-hugo.md) document. + +## Guidelines for include files + +To make sure includes are effective and easy to maintain, follow these guidelines: + +- **Only use includes for repeated content**: Create an include only if the content appears in at least **two locations**. Using an include for single-use content adds unnecessary complexity and makes maintenance harder. +- **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse. +- **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While possible, it complicates reviews and maintenance. A flat structure is simple. +- **Don't include heading**: Do not include headings in include files. These headings won't appear in a document's table of contents and may break the linear flow of the surrounding content. Add headings directly to the document instead. +- **Don't start documents with includes**: The opening of most document is the introduction which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. +- **Do not add the F5 prefix to product names in includes**: The brand name is required only on [the first mention in a document](/documentation/style-guide.md#f5-brand-trademarks-and-product-names). + +## Include file index + +To aid in discoverability of include files, this index is maintained to offer contributors a reference for existing entries. + +When viewing an include file, you may also see the `files`: parameter in the frontmatter, which shows where the file is currently in use. + +| **_File name_** | **_Description_** | +| ----------------| ------------------ | +| [_licensing-and-reporting/download-jwt-from-myf5.md_](/content/includes/licensing-and-reporting/download-jwt-from-myf5.md) | Instructions for downloading a JSON Web Token from MyF5 | +| [_licensing-and-reporting/download-certificates-from-myf5.md_](/content/includes/licensing-and-reporting/download-certificates-from-myf5.md) | Instructions for downloading certificate files from MyF5 | +| [_use-cases/credential-download-instructions.md_](/content/includes/use-cases/credential-download-instructions.md) | Parallel tabbed instructions for downloading credential files from MyF5 | +| [_use-cases/docker-registry-instructions.md_](/content/includes/use-cases/docker-registry-instructions.md) | Parallel tabbed instructions for listing Docker images from the F5 Registry | \ No newline at end of file diff --git a/documentation/style-guide.md b/documentation/style-guide.md index b1f7860c3..4b4a7e616 100644 --- a/documentation/style-guide.md +++ b/documentation/style-guide.md @@ -463,27 +463,6 @@ Ensure content and screenshots are anonymized and don't contain sensitive inform - Limit the use of links to external (non-F5) sources. When necessary, only link to reputable sources and foundational sites, such as GitHub.com, Google.com, and Microsoft.com. - This helps minimize the risk of prompt injection. -## Guidelines for `includes` - -In an ideal world, we'd "write once, publish everywhere." To support this goal, we follow the principle of [Don't repeat yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) in our documentation. This principle shapes how we create and use `includes`, which pull reusable content from files in the [content/includes](https://github.com/nginxinc/docs/tree/main/content/includes) directory. - -For example: - -```text -{{< include "controller/helper-script-prereqs.md" >}} -``` - -This entry automatically incorporates content from the `helper-script-prereqs.md` file in the `content/includes/controller` subdirectory. - -To make sure includes are effective and easy to maintain, follow these practices: - -- **Use includes only for reusable content**: Create an include only if the content appears in at least **two locations**. Using an include for single-use content adds unnecessary complexity and makes maintenance harder. -- **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse. -- **Avoid branded product names in includes**: Use the full product name (e.g., "NGINX Instance Manager"), but avoid including the branded version (e.g., "F5 NGINX Instance Manager"). The branded name is required only on the first mention in a document; this is a context-specific rule. Includes, however, are designed to be context-agnostic—they should not rely on or assume any prior content—so including the branded name could repeat information unnecessarily in locations where it has already been introduced. -- **Don't include headers**: Avoid adding H2 or other headers inside includes. These headers won't appear in the document's table of contents (TOC) and may not fit well with the surrounding content hierarchy. Add headers directly in the document instead. -- **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While technically possible, it complicates reviews and maintenance. Use a flat structure for simplicity. -- **Don't start documents with includes**: The opening of a document is usually the introduction, which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. - ## Guidelines for command-line operations ### Restarting vs. reloading NGINX From 084fc48f29527abcaac316f787ac400303e23dbe Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 14:58:09 +0100 Subject: [PATCH 25/31] fix: Remove unnecessary linebreak from include --- content/includes/use-cases/credential-download-instructions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/includes/use-cases/credential-download-instructions.md b/content/includes/use-cases/credential-download-instructions.md index a936057d8..416fa9e0d 100644 --- a/content/includes/use-cases/credential-download-instructions.md +++ b/content/includes/use-cases/credential-download-instructions.md @@ -4,7 +4,6 @@ files: - content/nic/installation/nic-images/registry-download.md --- - In order to obtain a container image, you will need the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. These files grant access to the package repository from which the script will download the NGINX Plus package: From f970a40be1eabc961ccfbdda33d5bd998436e925 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 15:00:31 +0100 Subject: [PATCH 26/31] fix: Further formatting issues --- .../download-jwt-from-myf5.md | 6 ++-- content/nic/installation/upgrade-version.md | 34 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md index 3b117934f..f7e92a6fa 100644 --- a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md @@ -14,6 +14,6 @@ files: --- 1. Log in to [MyF5](https://my.f5.com/manage/s/). -2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. -3. Find your NGINX subscription, and select the **Subscription ID** for details. -4. Download the **JSON Web Token** from the subscription page. +1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. +1. Find your NGINX subscription, and select the **Subscription ID** for details. +1. Download the **JSON Web Token** from the subscription page. diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index a2d2dd87b..73e3f96f5 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -54,21 +54,21 @@ To upgrade a release named _my-release_, use the following command: {{< tabs name="upgrade-chart" >}} -{{% tab name="OCI registry" %}} +{{< tab name="OCI registry" >}} ```shell helm upgrade my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -{{% /tab %}} +{{< /tab >}} -{{% tab name="Source" %}} +{{< tab name="Source" >}} ```shell helm upgrade my-release . ``` -{{% /tab %}} +{{< /tab >}} {{< /tabs >}} @@ -99,8 +99,8 @@ The example below shows the change for a Policy resource: you must do the same f {{}} -{{% comment %}} Keep this left aligned. {{% /comment %}} -{{%tab name="Before"%}} +{{< comment >}} Keep this left aligned. {{< /comment >}} +{{}} ```yaml apiVersion: k8s.nginx.org/v1alpha1 @@ -113,9 +113,9 @@ spec: key: ${binary_remote_addr} zoneSize: 10M ``` -{{% /tab %}} +{{< /tab >}} -{{%tab name="After"%}} +{{}} ```yaml apiVersion: k8s.nginx.org/v1 kind: Policy @@ -127,7 +127,7 @@ spec: key: ${binary_remote_addr} zoneSize: 10M ``` -{{% /tab %}} +{{< /tab >}} {{}} @@ -162,7 +162,7 @@ To configure structured logging, you must update your log deployment arguments f {{}} -{{%tab name="Helm"%}} +{{}} The Helm value `controller.logLevel` is now a string instead of an integer. @@ -173,9 +173,9 @@ controller: logLevel: info logFormat: json ``` -{{% /tab %}} +{{< /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. @@ -186,7 +186,7 @@ args: - -log-level=info - -log-format=json ``` -{{% /tab %}} +{{< /tab >}} {{}} @@ -212,7 +212,7 @@ 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: @@ -260,9 +260,9 @@ Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set n 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: @@ -309,6 +309,6 @@ Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set t Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 ``` -{{%/tab%}} +{{}} {{}} From ba5baf890b40dc9e42ecc2568316180e0f8864c9 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 15:20:00 +0100 Subject: [PATCH 27/31] fix: Revert tab formatting to use % instead of <> --- .../download-certificates-from-myf5.md | 2 +- .../credential-download-instructions.md | 8 +-- .../use-cases/docker-registry-instructions.md | 8 +-- content/nic/installation/upgrade-version.md | 54 ++++++++++--------- 4 files changed, 38 insertions(+), 34 deletions(-) diff --git a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md index 37d68957a..b65710b5a 100644 --- a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md @@ -5,5 +5,5 @@ files: 1. Log in to [MyF5](https://my.f5.com/manage/s/). 1. Go to **My Products and Plans** > **Subscriptions**. -1. Select the product subscription. +1. Find your NGINX subscription, and select the **Subscription ID** for details. 1. Download the **SSL Certificate** and **Private Key** files. \ No newline at end of file diff --git a/content/includes/use-cases/credential-download-instructions.md b/content/includes/use-cases/credential-download-instructions.md index 416fa9e0d..672bdfb0f 100644 --- a/content/includes/use-cases/credential-download-instructions.md +++ b/content/includes/use-cases/credential-download-instructions.md @@ -10,16 +10,16 @@ These files grant access to the package repository from which the script will do {{< tabs name="product_keys" >}} -{{< tab name="JSON Web Token" >}} +{{% tab name="JSON Web Token" %}} {{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} -{{< /tab >}} +{{% /tab %}} -{{< tab name="SSL" >}} +{{% tab name="SSL" %}} {{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}} -{{< /tab >}} +{{% /tab %}} {{< /tabs >}} \ No newline at end of file diff --git a/content/includes/use-cases/docker-registry-instructions.md b/content/includes/use-cases/docker-registry-instructions.md index ea0aeb019..5f7e6af73 100644 --- a/content/includes/use-cases/docker-registry-instructions.md +++ b/content/includes/use-cases/docker-registry-instructions.md @@ -14,9 +14,9 @@ For more details on Docker Engine security, you can refer to the [Docker Engine {{< /call-out >}} -{{}} +{{< tabs name="docker_login" >}} -{{%tab name="JSON Web Token"%}} +{{% tab name="JSON Web Token"%}} Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents. @@ -28,7 +28,7 @@ docker login private-registry.nginx.com --username= --passw {{% /tab %}} -{{%tab name="SSL"%}} +{{% tab name="SSL" %}} Create a directory and copy your certificate and key to this directory: @@ -46,4 +46,4 @@ docker login private-registry.nginx.com {{% /tab %}} -{{% /tabs %}} \ No newline at end of file +{{< /tabs >}} \ No newline at end of file diff --git a/content/nic/installation/upgrade-version.md b/content/nic/installation/upgrade-version.md index 73e3f96f5..ae5f3982a 100644 --- a/content/nic/installation/upgrade-version.md +++ b/content/nic/installation/upgrade-version.md @@ -54,21 +54,21 @@ To upgrade a release named _my-release_, use the following command: {{< tabs name="upgrade-chart" >}} -{{< tab name="OCI registry" >}} +{{% tab name="OCI registry" %}} ```shell helm upgrade my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -{{< /tab >}} +{{% /tab %}} -{{< tab name="Source" >}} +{{% tab name="Source" %}} ```shell helm upgrade my-release . ``` -{{< /tab >}} +{{% /tab %}} {{< /tabs >}} @@ -97,10 +97,9 @@ If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Cont The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources. -{{}} +{{< tabs name="resource-version-update" >}} -{{< comment >}} Keep this left aligned. {{< /comment >}} -{{}} +{{% tab name="Before" %}} ```yaml apiVersion: k8s.nginx.org/v1alpha1 @@ -113,9 +112,11 @@ spec: key: ${binary_remote_addr} zoneSize: 10M ``` -{{< /tab >}} -{{}} +{{% /tab %}} + +{{% tab name="After" %}} + ```yaml apiVersion: k8s.nginx.org/v1 kind: Policy @@ -127,13 +128,16 @@ spec: key: ${binary_remote_addr} zoneSize: 10M ``` -{{< /tab >}} -{{}} +{{% /tab %}} + +{{< /tabs >}} + +{{< call-out "warning" >}} -{{< warning >}} If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process. -{{}} + +{{}} 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). @@ -160,9 +164,9 @@ To configure structured logging, you must update your log deployment arguments f | `error` | | | `fatal` | | -{{}} +{{< tabs name="structured logging" >}} -{{}} +{{% tab name="Helm" %}} The Helm value `controller.logLevel` is now a string instead of an integer. @@ -173,9 +177,9 @@ controller: logLevel: info logFormat: json ``` -{{< /tab >}} +{{% /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. @@ -186,9 +190,9 @@ args: - -log-level=info - -log-format=json ``` -{{< /tab >}} +{{% /tab %}} -{{}} +{{< /tabs >}} ### Create License secret @@ -210,9 +214,9 @@ To reduce downtime, update all resources to use the new naming convention. The f The steps you should follow depend on your Helm release name: -{{}} +{{< tabs name="upgrade-helm" >}} -{{}} +{{% tab name="nginx-ingress" %}} Use `kubectl describe` on deployment/daemonset to get the `Selector` value: @@ -260,9 +264,9 @@ Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set n 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: @@ -309,6 +313,6 @@ Normal ScalingReplicaSet 101s deployment-controller Scaled up replica set t Normal ScalingReplicaSet 98s deployment-controller Scaled down replica set test-release-nginx-ingress- to 0 from 1 ``` -{{}} +{{% /tab %}} -{{}} +{{< /tabs >}} From fabdf2a6f5a9bca965f2800d4cbd7b06f8d504e1 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 16:06:48 +0100 Subject: [PATCH 28/31] feat: Make include text consistent --- .../licensing-and-reporting/download-certificates-from-myf5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md index b65710b5a..5ea333185 100644 --- a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md @@ -4,6 +4,6 @@ files: --- 1. Log in to [MyF5](https://my.f5.com/manage/s/). -1. Go to **My Products and Plans** > **Subscriptions**. +1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. 1. Find your NGINX subscription, and select the **Subscription ID** for details. 1. Download the **SSL Certificate** and **Private Key** files. \ No newline at end of file From f22d693b22f8714bfc63433a340712997a8c096c Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 16:34:41 +0100 Subject: [PATCH 29/31] fix: Include text consistency --- .../licensing-and-reporting/download-certificates-from-myf5.md | 2 +- .../includes/licensing-and-reporting/download-jwt-from-myf5.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md index 5ea333185..36597020c 100644 --- a/content/includes/licensing-and-reporting/download-certificates-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-certificates-from-myf5.md @@ -6,4 +6,4 @@ files: 1. Log in to [MyF5](https://my.f5.com/manage/s/). 1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. 1. Find your NGINX subscription, and select the **Subscription ID** for details. -1. Download the **SSL Certificate** and **Private Key** files. \ No newline at end of file +1. Download the **SSL Certificate** and **Private Key** files from the subscription page. \ No newline at end of file diff --git a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md index f7e92a6fa..1ede09099 100644 --- a/content/includes/licensing-and-reporting/download-jwt-from-myf5.md +++ b/content/includes/licensing-and-reporting/download-jwt-from-myf5.md @@ -16,4 +16,4 @@ files: 1. Log in to [MyF5](https://my.f5.com/manage/s/). 1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. 1. Find your NGINX subscription, and select the **Subscription ID** for details. -1. Download the **JSON Web Token** from the subscription page. +1. Download the **JSON Web Token** file from the subscription page. From bfbabee7e6c48a983dda2c71426ae98e057ce454 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 17:10:30 +0100 Subject: [PATCH 30/31] fix: Typos in include documentation --- documentation/include-files.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/include-files.md b/documentation/include-files.md index f52602164..096ba4661 100644 --- a/documentation/include-files.md +++ b/documentation/include-files.md @@ -25,8 +25,8 @@ To make sure includes are effective and easy to maintain, follow these guideline - **Only use includes for repeated content**: Create an include only if the content appears in at least **two locations**. Using an include for single-use content adds unnecessary complexity and makes maintenance harder. - **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse. - **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While possible, it complicates reviews and maintenance. A flat structure is simple. -- **Don't include heading**: Do not include headings in include files. These headings won't appear in a document's table of contents and may break the linear flow of the surrounding content. Add headings directly to the document instead. -- **Don't start documents with includes**: The opening of most document is the introduction which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. +- **Don't include headings**: Do not include headings in include files. These headings won't appear in a document's table of contents and may break the linear flow of the surrounding content. Add headings directly to the document instead. +- **Don't start documents with includes**: The opening of most documents is the introduction which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results. - **Do not add the F5 prefix to product names in includes**: The brand name is required only on [the first mention in a document](/documentation/style-guide.md#f5-brand-trademarks-and-product-names). ## Include file index From e630c58394fc097b1eb6347a147f9f65f0471b70 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Mon, 28 Jul 2025 17:13:50 +0100 Subject: [PATCH 31/31] feat: Update product name in Helm page --- .../installing-nic/installation-with-helm.md | 124 +++++++++--------- 1 file changed, 62 insertions(+), 62 deletions(-) diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 3f9bc653f..a6d99bfd0 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -127,10 +127,10 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont {{}} |Parameter | Description | Default | | --- | --- | --- | -| **controller.name** | The name of the Ingress Controller daemonset or deployment. | Autogenerated | -| **controller.kind** | The kind of the Ingress Controller installation - deployment or daemonset. | deployment | +| **controller.name** | The name of the NGINX Ingress Controller daemonset or deployment. | Autogenerated | +| **controller.kind** | The kind of the NGINX Ingress Controller installation - deployment or daemonset. | deployment | | **controller.annotations** | Allows for setting of `annotations` for deployment or daemonset. | {} | -| **controller.nginxplus** | Deploys the Ingress Controller for NGINX Plus. | false | +| **controller.nginxplus** | Deploys the NGINX Ingress Controller for NGINX Plus. | false | | **controller.mgmt.licenseTokenSecretName** | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | license-token | | **controller.mgmt.enforceInitialReport** | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | false | | **controller.mgmt.usageReport.endpoint** | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NIM. | product.connect.nginx.com | @@ -144,20 +144,20 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.mgmt.sslCertificateSecretName** | Configures the secret used to create the `ssl_certificate` and `ssl_certificate_key` directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `kubernetes.io/tls` | N/A | | **controller.mgmt.sslTrustedCertificateSecretName** | Configures the secret used to create the file(s) referenced the in [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.org/ca`, where the `ca.crt` key contains a base64 encoded trusted cert, and the optional `ca.crl` key can contain a base64 encoded CRL. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | | **controller.mgmt.configMapName** | Allows changing the name of the MGMT config map. The name should not include a namespace| Autogenerated | -| **controller.nginxReloadTimeout** | The timeout in milliseconds which the Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. | 60000 | -| **controller.hostNetwork** | Enables the Ingress Controller pods to use the host's network namespace. | false | -| **controller.dnsPolicy** | DNS policy for the Ingress Controller pods. | ClusterFirst | +| **controller.nginxReloadTimeout** | The timeout in milliseconds which the NGINX Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. | 60000 | +| **controller.hostNetwork** | Enables the NGINX Ingress Controller pods to use the host's network namespace. | false | +| **controller.dnsPolicy** | DNS policy for the NGINX Ingress Controller pods. | ClusterFirst | | **controller.nginxDebug** | Enables debugging for NGINX. Uses the `nginx-debug` binary. Requires `error-log-level: debug` in the ConfigMap via `controller.config.entries`. | false | -| **controller.logLevel** | The log level of the Ingress Controller. | info | -| **controller.logFormat** | The log format of the Ingress Controller. | glog | -| **controller.image.digest** | The image digest of the Ingress Controller. | None | -| **controller.image.repository** | The image repository of the Ingress Controller. | nginx/nginx-ingress | -| **controller.image.tag** | The tag of the Ingress Controller image. | {{< nic-version >}} | -| **controller.image.pullPolicy** | The pull policy for the Ingress Controller image. | IfNotPresent | -| **controller.lifecycle** | The lifecycle of the Ingress Controller pods. | {} | -| **controller.customConfigMap** | The name of the custom ConfigMap used by the Ingress Controller. If set, then the default config is ignored. | "" | -| **controller.config.name** | The name of the ConfigMap used by the Ingress Controller. | Autogenerated | -| **controller.config.annotations** | The annotations of the Ingress Controller configmap. | {} | +| **controller.logLevel** | The log level of the NGINX Ingress Controller. | info | +| **controller.logFormat** | The log format of the NGINX Ingress Controller. | glog | +| **controller.image.digest** | The image digest of the NGINX Ingress Controller. | None | +| **controller.image.repository** | The image repository of the NGINX Ingress Controller. | nginx/nginx-ingress | +| **controller.image.tag** | The tag of the NGINX Ingress Controller image. | {{< nic-version >}} | +| **controller.image.pullPolicy** | The pull policy for the NGINX Ingress Controller image. | IfNotPresent | +| **controller.lifecycle** | The lifecycle of the NGINX Ingress Controller pods. | {} | +| **controller.customConfigMap** | The name of the custom ConfigMap used by the NGINX Ingress Controller. If set, then the default config is ignored. | "" | +| **controller.config.name** | The name of the ConfigMap used by the NGINX Ingress Controller. | Autogenerated | +| **controller.config.annotations** | The annotations of the NGINX Ingress Controller configmap. | {} | | **controller.config.entries** | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs]({{< ref "/nic/configuration/global-configuration/configmap-resource.md" >}}) for the list of supported ConfigMap keys. | {} | | **controller.customPorts** | A list of custom ports to expose on the NGINX Ingress Controller pod. Follows the conventional Kubernetes yaml syntax for container ports. | [] | | **controller.defaultTLS.cert** | The base64-encoded TLS certificate for the default HTTPS server. **Note:** It is recommended that you specify your own certificate. Alternatively, omitting the default server secret completely will configure NGINX to reject TLS connections to the default server. | @@ -166,28 +166,28 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.wildcardTLS.cert** | The base64-encoded TLS certificate for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | | **controller.wildcardTLS.key** | The base64-encoded TLS key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. If the parameter is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. | None | | **controller.wildcardTLS.secret** | The secret with a TLS certificate and key for every Ingress/VirtualServer host that has TLS enabled but no secret specified. The value must follow the following format: `/`. Used as an alternative to specifying a certificate and key using `controller.wildcardTLS.cert` and `controller.wildcardTLS.key` parameters. | None | -| **controller.nodeSelector** | The node selector for pod assignment for the Ingress Controller pods. | {} | -| **controller.terminationGracePeriodSeconds** | The termination grace period of the Ingress Controller pod. | 30 | -| **controller.tolerations** | The tolerations of the Ingress Controller pods. | [] | -| **controller.affinity** | The affinity of the Ingress Controller pods. | {} | -| **controller.topologySpreadConstraints** | The topology spread constraints of the Ingress controller pods. | {} | -| **controller.env** | The additional environment variables to be set on the Ingress Controller pods. | [] | -| **controller.volumes** | The volumes of the Ingress Controller pods. | [] | -| **controller.volumeMounts** | The volumeMounts of the Ingress Controller pods. | [] | -| **controller.initContainers** | InitContainers for the Ingress Controller pods. | [] | -| **controller.extraContainers** | Extra (eg. sidecar) containers for the Ingress Controller pods. | [] | +| **controller.nodeSelector** | The node selector for pod assignment for the NGINX Ingress Controller pods. | {} | +| **controller.terminationGracePeriodSeconds** | The termination grace period of the NGINX Ingress Controller pod. | 30 | +| **controller.tolerations** | The tolerations of the NGINX Ingress Controller pods. | [] | +| **controller.affinity** | The affinity of the NGINX Ingress Controller pods. | {} | +| **controller.topologySpreadConstraints** | The topology spread constraints of the NGINX Ingress Controller pods. | {} | +| **controller.env** | The additional environment variables to be set on the NGINX Ingress Controller pods. | [] | +| **controller.volumes** | The volumes of the NGINX Ingress Controller pods. | [] | +| **controller.volumeMounts** | The volumeMounts of the NGINX Ingress Controller pods. | [] | +| **controller.initContainers** | InitContainers for the NGINX Ingress Controller pods. | [] | +| **controller.extraContainers** | Extra (eg. sidecar) containers for the NGINX Ingress Controller pods. | [] | | **controller.podSecurityContext**| The SecurityContext for Ingress Controller pods. | "seccompProfile": {"type": "RuntimeDefault"} | | **controller.securityContext** | The SecurityContext for Ingress Controller container. | {} | | **controller.initContainerSecurityContext** | The SecurityContext for Ingress Controller init container when `readOnlyRootFilesystem` is enabled by either setting `controller.securityContext.readOnlyRootFilesystem` or `controller.readOnlyRootFilesystem`to `true`. | {} | -| **controller.resources** | The resources of the Ingress Controller pods. | requests: cpu=100m,memory=128Mi | +| **controller.resources** | The resources of the NGINX Ingress Controller pods. | requests: cpu=100m,memory=128Mi | | **controller.initContainerResources** | The resources of the init container which is used when `readOnlyRootFilesystem` is enabled by either setting `controller.securityContext.readOnlyRootFilesystem` or `controller.readOnlyRootFilesystem`to `true`. | requests: cpu=100m,memory=128Mi | -| **controller.replicaCount** | The number of replicas of the Ingress Controller deployment. | 1 | -| **controller.ingressClass.name** | A class of the Ingress Controller. An IngressClass resource with the name equal to the class must be deployed. Otherwise, the Ingress Controller will fail to start. The Ingress Controller only processes resources that belong to its class - i.e. have the "ingressClassName" field resource equal to the class. The Ingress Controller processes all the VirtualServer/VirtualServerRoute/TransportServer resources that do not have the "ingressClassName" field for all versions of Kubernetes. | nginx | +| **controller.replicaCount** | The number of replicas of the NGINX Ingress Controller deployment. | 1 | +| **controller.ingressClass.name** | A class of the NGINX Ingress Controller. An IngressClass resource with the name equal to the class must be deployed. Otherwise, the NGINX Ingress Controller will fail to start. the NGINX Ingress Controller only processes resources that belong to its class - i.e. have the "ingressClassName" field resource equal to the class. the NGINX Ingress Controller processes all the VirtualServer/VirtualServerRoute/TransportServer resources that do not have the "ingressClassName" field for all versions of Kubernetes. | nginx | | **controller.ingressClass.create** | Creates a new IngressClass object with the name `controller.ingressClass.name`. Set to `false` to use an existing ingressClass created using `kubectl` with the same name. If you use `helm upgrade`, do not change the values from the previous release as helm will delete IngressClass objects managed by helm. If you are upgrading from a release earlier than {{< nic-version >}}, do not set the value to false. | true | | **controller.ingressClass.setAsDefaultIngress** | New Ingresses without an `"ingressClassName"` field specified will be assigned the class specified in `controller.ingressClass.name`. Requires `controller.ingressClass.create`. | false | -| **controller.watchNamespace** | Comma separated list of namespaces the Ingress Controller should watch for resources. By default the Ingress Controller watches all namespaces. Mutually exclusive with `controller.watchNamespaceLabel`. Please note that if configuring multiple namespaces using the Helm cli `--set` option, the string needs to wrapped in double quotes and the commas escaped using a backslash - e.g. `--set controller.watchNamespace="default\,nginx-ingress"`. | "" | -| **controller.watchNamespaceLabel** | Configures the Ingress Controller to watch only those namespaces with label foo=bar. By default the Ingress Controller watches all namespaces. Mutually exclusive with `controller.watchNamespace`. | "" | -| **controller.watchSecretNamespace** | Comma separated list of namespaces the Ingress Controller should watch for resources of type Secret. If this arg is not configured, the Ingress Controller watches the same namespaces for all resources, see `controller.watchNamespace` and `controller.watchNamespaceLabel`. All namespaces included with this argument must be part of either `controller.watchNamespace` or `controller.watchNamespaceLabel`. Please note that if configuring multiple namespaces using the Helm cli `--set` option, the string needs to wrapped in double quotes and the commas escaped using a backslash - e.g. `--set controller.watchSecretNamespace="default\,nginx-ingress"`. | "" | +| **controller.watchNamespace** | Comma separated list of namespaces the NGINX Ingress Controller should watch for resources. By default the NGINX Ingress Controller watches all namespaces. Mutually exclusive with `controller.watchNamespaceLabel`. Please note that if configuring multiple namespaces using the Helm cli `--set` option, the string needs to wrapped in double quotes and the commas escaped using a backslash - e.g. `--set controller.watchNamespace="default\,nginx-ingress"`. | "" | +| **controller.watchNamespaceLabel** | Configures the NGINX Ingress Controller to watch only those namespaces with label foo=bar. By default the NGINX Ingress Controller watches all namespaces. Mutually exclusive with `controller.watchNamespace`. | "" | +| **controller.watchSecretNamespace** | Comma separated list of namespaces the NGINX Ingress Controller should watch for resources of type Secret. If this arg is not configured, the NGINX Ingress Controller watches the same namespaces for all resources, see `controller.watchNamespace` and `controller.watchNamespaceLabel`. All namespaces included with this argument must be part of either `controller.watchNamespace` or `controller.watchNamespaceLabel`. Please note that if configuring multiple namespaces using the Helm cli `--set` option, the string needs to wrapped in double quotes and the commas escaped using a backslash - e.g. `--set controller.watchSecretNamespace="default\,nginx-ingress"`. | "" | | **controller.enableCustomResources** | Enable the custom resources. | true | | **controller.enableOIDC** | Enable OIDC policies. | false | | **controller.enableTLSPassthrough** | Enable TLS Passthrough on default port 443. Requires `controller.enableCustomResources`. | false | @@ -195,46 +195,46 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.enableCertManager** | Enable x509 automated certificate management for VirtualServer resources using cert-manager (cert-manager.io). Requires `controller.enableCustomResources`. | false | | **controller.enableExternalDNS** | Enable integration with ExternalDNS for configuring public DNS entries for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Requires `controller.enableCustomResources`. | false | | **controller.globalConfiguration.create** | Creates the GlobalConfiguration custom resource. Requires `controller.enableCustomResources`. | false | -| **controller.globalConfiguration.spec** | The spec of the GlobalConfiguration for defining the global configuration parameters of the Ingress Controller. | {} | +| **controller.globalConfiguration.spec** | The spec of the GlobalConfiguration for defining the global configuration parameters of the NGINX Ingress Controller. | {} | | **controller.enableSnippets** | Enable custom NGINX configuration snippets in Ingress, VirtualServer, VirtualServerRoute and TransportServer resources. | false | -| **controller.healthStatus** | Add a location "/nginx-health" to the default server. The location responds with the 200 status code for any request. Useful for external health-checking of the Ingress Controller. | false | +| **controller.healthStatus** | Add a location "/nginx-health" to the default server. The location responds with the 200 status code for any request. Useful for external health-checking of the NGINX Ingress Controller. | false | | **controller.healthStatusURI** | Sets the URI of health status location in the default server. Requires `controller.healthStatus`. | "/nginx-health" | | **controller.nginxStatus.enable** | Enable the NGINX stub_status, or the NGINX Plus API. | true | | **controller.nginxStatus.port** | Set the port where the NGINX stub_status or the NGINX Plus API is exposed. | 8080 | | **controller.nginxStatus.allowCidrs** | Add IP/CIDR blocks to the allow list for NGINX stub_status or the NGINX Plus API. Separate multiple IP/CIDR by commas. | 127.0.0.1,::1 | -| **controller.priorityClassName** | The PriorityClass of the Ingress Controller pods. | None | -| **controller.service.create** | Creates a service to expose the Ingress Controller pods. | true | -| **controller.service.type** | The type of service to create for the Ingress Controller. | LoadBalancer | +| **controller.priorityClassName** | The PriorityClass of the NGINX Ingress Controller pods. | None | +| **controller.service.create** | Creates a service to expose the NGINX Ingress Controller pods. | true | +| **controller.service.type** | The type of service to create for the NGINX Ingress Controller. | LoadBalancer | | **controller.service.externalTrafficPolicy** | The externalTrafficPolicy of the service. The value Local preserves the client source IP. | Local | -| **controller.service.annotations** | The annotations of the Ingress Controller service. | {} | +| **controller.service.annotations** | The annotations of the NGINX Ingress Controller service. | {} | | **controller.service.extraLabels** | The extra labels of the service. | {} | | **controller.service.loadBalancerIP** | The static IP address for the load balancer. Requires `controller.service.type` set to `LoadBalancer`. The cloud provider must support this feature. | "" | -| **controller.service.externalIPs** | The list of external IPs for the Ingress Controller service. | [] | -| **controller.service.clusterIP** | The clusterIP for the Ingress Controller service, autoassigned if not specified. | "" | +| **controller.service.externalIPs** | The list of external IPs for the NGINX Ingress Controller service. | [] | +| **controller.service.clusterIP** | The clusterIP for the NGINX Ingress Controller service, autoassigned if not specified. | "" | | **controller.service.loadBalancerSourceRanges** | The IP ranges (CIDR) that are allowed to access the load balancer. Requires `controller.service.type` set to `LoadBalancer`. The cloud provider must support this feature. | [] | | **controller.service.name** | The name of the service. | Autogenerated | -| **controller.service.customPorts** | A list of custom ports to expose through the Ingress Controller service. Follows the conventional Kubernetes yaml syntax for service ports. | [] | -| **controller.service.httpPort.enable** | Enables the HTTP port for the Ingress Controller service. | true | -| **controller.service.httpPort.port** | The HTTP port of the Ingress Controller service. | 80 | +| **controller.service.customPorts** | A list of custom ports to expose through the NGINX Ingress Controller service. Follows the conventional Kubernetes yaml syntax for service ports. | [] | +| **controller.service.httpPort.enable** | Enables the HTTP port for the NGINX Ingress Controller service. | true | +| **controller.service.httpPort.port** | The HTTP port of the NGINX Ingress Controller service. | 80 | | **controller.service.httpPort.nodePort** | The custom NodePort for the HTTP port. Requires `controller.service.type` set to `NodePort`. | "" | -| **controller.service.httpPort.targetPort** | The target port of the HTTP port of the Ingress Controller service. | 80 | -| **controller.service.httpsPort.enable** | Enables the HTTPS port for the Ingress Controller service. | true | -| **controller.service.httpsPort.port** | The HTTPS port of the Ingress Controller service. | 443 | +| **controller.service.httpPort.targetPort** | The target port of the HTTP port of the NGINX Ingress Controller service. | 80 | +| **controller.service.httpsPort.enable** | Enables the HTTPS port for the NGINX Ingress Controller service. | true | +| **controller.service.httpsPort.port** | The HTTPS port of the NGINX Ingress Controller service. | 443 | | **controller.service.httpsPort.nodePort** | The custom NodePort for the HTTPS port. Requires `controller.service.type` set to `NodePort`. | "" | -| **controller.service.httpsPort.targetPort** | The target port of the HTTPS port of the Ingress Controller service. | 443 | -| **controller.serviceAccount.annotations** | The annotations of the Ingress Controller service account. | {} | -| **controller.serviceAccount.name** | The name of the service account of the Ingress Controller pods. Used for RBAC. | Autogenerated | +| **controller.service.httpsPort.targetPort** | The target port of the HTTPS port of the NGINX Ingress Controller service. | 443 | +| **controller.serviceAccount.annotations** | The annotations of the NGINX Ingress Controller service account. | {} | +| **controller.serviceAccount.name** | The name of the service account of the NGINX Ingress Controller pods. Used for RBAC. | Autogenerated | | **controller.serviceAccount.imagePullSecretName** | The name of the secret containing docker registry credentials. Secret must exist in the same namespace as the helm release. | "" | | **controller.serviceAccount.imagePullSecretsNames** | The list of secret names containing docker registry credentials. Secret must exist in the same namespace as the helm release. | [] | -| **controller.reportIngressStatus.enable** | Updates the address field in the status of Ingress resources with an external address of the Ingress Controller. You must also specify the source of the external address either through an external service via `controller.reportIngressStatus.externalService`, `controller.reportIngressStatus.ingressLink` or the `external-status-address` entry in the ConfigMap via `controller.config.entries`. **Note:** `controller.config.entries.external-status-address` takes precedence over the others. | true | -| **controller.reportIngressStatus.externalService** | Specifies the name of the service with the type LoadBalancer through which the Ingress Controller is exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. `controller.reportIngressStatus.enable` must be set to `true`. The default is autogenerated and enabled when `controller.service.create` is set to `true` and `controller.service.type` is set to `LoadBalancer`. | Autogenerated | -| **controller.reportIngressStatus.ingressLink** | Specifies the name of the IngressLink resource, which exposes the Ingress Controller pods via a BIG-IP system. The IP of the BIG-IP system is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. `controller.reportIngressStatus.enable` must be set to `true`. | "" | +| **controller.reportIngressStatus.enable** | Updates the address field in the status of Ingress resources with an external address of the NGINX Ingress Controller. You must also specify the source of the external address either through an external service via `controller.reportIngressStatus.externalService`, `controller.reportIngressStatus.ingressLink` or the `external-status-address` entry in the ConfigMap via `controller.config.entries`. **Note:** `controller.config.entries.external-status-address` takes precedence over the others. | true | +| **controller.reportIngressStatus.externalService** | Specifies the name of the service with the type LoadBalancer through which the NGINX Ingress Controller is exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. `controller.reportIngressStatus.enable` must be set to `true`. The default is autogenerated and enabled when `controller.service.create` is set to `true` and `controller.service.type` is set to `LoadBalancer`. | Autogenerated | +| **controller.reportIngressStatus.ingressLink** | Specifies the name of the IngressLink resource, which exposes the NGINX Ingress Controller pods via a BIG-IP system. The IP of the BIG-IP system is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. `controller.reportIngressStatus.enable` must be set to `true`. | "" | | **controller.reportIngressStatus.enableLeaderElection** | Enable Leader election to avoid multiple replicas of the controller reporting the status of Ingress resources. `controller.reportIngressStatus.enable` must be set to `true`. | true | | **controller.reportIngressStatus.leaderElectionLockName** | Specifies the name of the ConfigMap, within the same namespace as the controller, used as the lock for leader election. controller.reportIngressStatus.enableLeaderElection must be set to true. | Autogenerated | | **controller.reportIngressStatus.annotations** | The annotations of the leader election configmap. | {} | -| **controller.pod.annotations** | The annotations of the Ingress Controller pod. | {} | -| **controller.pod.extraLabels** | The additional extra labels of the Ingress Controller pod. | {} | -| **controller.appprotect.enable** | Enables the App Protect WAF module in the Ingress Controller. | false | +| **controller.pod.annotations** | The annotations of the NGINX Ingress Controller pod. | {} | +| **controller.pod.extraLabels** | The additional extra labels of the NGINX Ingress Controller pod. | {} | +| **controller.appprotect.enable** | Enables the App Protect WAF module in the NGINX Ingress Controller. | false | | **controller.appprotect.v5** | Enables App Protect WAF v5. | false | | **controller.appprotect.volumes** | Volumes for App Protect WAF v5. | [{"name": "app-protect-bd-config", "emptyDir": {}},{"name": "app-protect-config", "emptyDir": {}},{"name": "app-protect-bundles", "emptyDir": {}}] | | **controller.appprotect.enforcer.host** | Host that the App Protect WAF v5 Enforcer runs on. | "127.0.0.1" | @@ -249,26 +249,26 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.appprotect.configManager.image.digest** | The digest of the App Protect WAF v5 Configuration Manager. Takes precedence over tag if set. | "" | | **controller.appprotect.configManager.image.pullPolicy** | The pull policy for the App Protect WAF v5 Configuration Manager image. | IfNotPresent | | **controller.appprotect.configManager.securityContext** | The security context for App Protect WAF v5 Configuration Manager container. | {"allowPrivilegeEscalation":false,"runAsUser":101,"runAsNonRoot":true,"capabilities":{"drop":["all"]}} | -| **controller.appprotectdos.enable** | Enables the App Protect DoS module in the Ingress Controller. | false | -| **controller.appprotectdos.enable** | Enables the App Protect DoS module in the Ingress Controller. | false | +| **controller.appprotectdos.enable** | Enables the App Protect DoS module in the NGINX Ingress Controller. | false | +| **controller.appprotectdos.enable** | Enables the App Protect DoS module in the NGINX Ingress Controller. | false | | **controller.appprotectdos.debug** | Enable debugging for App Protect DoS. | false | | **controller.appprotectdos.maxDaemons** | Max number of ADMD instances. | 1 | | **controller.appprotectdos.maxWorkers** | Max number of nginx processes to support. | Number of CPU cores in the machine | | **controller.appprotectdos.memory** | RAM memory size to consume in MB. | 50% of free RAM in the container or 80MB, the smaller | -| **controller.readyStatus.enable** | Enables the readiness endpoint `"/nginx-ready"`. The endpoint returns a success code when NGINX has loaded all the config after the startup. This also configures a readiness probe for the Ingress Controller pods that uses the readiness endpoint. | true | +| **controller.readyStatus.enable** | Enables the readiness endpoint `"/nginx-ready"`. The endpoint returns a success code when NGINX has loaded all the config after the startup. This also configures a readiness probe for the NGINX Ingress Controller pods that uses the readiness endpoint. | true | | **controller.readyStatus.port** | The HTTP port for the readiness endpoint. | 8081 | -| **controller.readyStatus.initialDelaySeconds** | The number of seconds after the Ingress Controller pod has started before readiness probes are initiated. | 0 | +| **controller.readyStatus.initialDelaySeconds** | The number of seconds after the NGINX Ingress Controller pod has started before readiness probes are initiated. | 0 | | **controller.enableLatencyMetrics** | Enable collection of latency metrics for upstreams. Requires `prometheus.create`. | false | | **controller.minReadySeconds** | Specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. [docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#min-ready-seconds) | 0 | | **controller.autoscaling.enabled** | Enables HorizontalPodAutoscaling. | false | -| **controller.autoscaling.annotations** | The annotations of the Ingress Controller HorizontalPodAutoscaler. | {} | +| **controller.autoscaling.annotations** | The annotations of the NGINX Ingress Controller HorizontalPodAutoscaler. | {} | | **controller.autoscaling.behavior** | Behavior configuration for the HPA. | {} | | **controller.autoscaling.minReplicas** | Minimum number of replicas for the HPA. | 1 | | **controller.autoscaling.maxReplicas** | Maximum number of replicas for the HPA. | 3 | | **controller.autoscaling.targetCPUUtilizationPercentage** | The target CPU utilization percentage. | 50 | | **controller.autoscaling.targetMemoryUtilizationPercentage** | The target memory utilization percentage. | 50 | | **controller.podDisruptionBudget.enabled** | Enables PodDisruptionBudget. | false | -| **controller.podDisruptionBudget.annotations** | The annotations of the Ingress Controller pod disruption budget | {} | +| **controller.podDisruptionBudget.annotations** | The annotations of the NGINX Ingress Controller pod disruption budget | {} | | **controller.podDisruptionBudget.minAvailable** | The number of Ingress Controller pods that should be available. This is a mutually exclusive setting with "maxUnavailable". | 0 | | **controller.podDisruptionBudget.maxUnavailable** | The number of Ingress Controller pods that can be unavailable. This is a mutually exclusive setting with "minAvailable". | 0 | | **controller.strategy** | Specifies the strategy used to replace old Pods with new ones. Docs for [Deployment update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) and [Daemonset update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy) | {} | @@ -297,7 +297,7 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **serviceInsight.secret** | The namespace / name of a Kubernetes TLS Secret. If specified, this secret is used to secure the Service Insight endpoint with TLS connections. | "" | | **serviceNameOverride** | Used to prevent cloud load balancers from being replaced due to service name change during helm upgrades. | "" | | **nginxServiceMesh.enable** | Enable integration with NGINX Service Mesh. See the NGINX Service Mesh docs for more details. Requires `controller.nginxplus`. | false | -| **nginxServiceMesh.enableEgress** | Enable NGINX Service Mesh workloads to route egress traffic through the Ingress Controller. See the NGINX Service Mesh docs for more details. Requires `nginxServiceMesh.enable`. | false | +| **nginxServiceMesh.enableEgress** | Enable NGINX Service Mesh workloads to route egress traffic through the NGINX Ingress Controller. See the NGINX Service Mesh docs for more details. Requires `nginxServiceMesh.enable`. | false | |**nginxAgent.enable** | Enable NGINX Agent 3.x to allow [connecting to NGINX One Console]({{< ref "/nginx-one/k8s/add-nic.md" >}}) or to integrate NGINX Agent 2.x for [Security Monitoring]({{< ref "/nic/tutorials/security-monitoring.md" >}}) . | false | |**nginxAgent.logLevel** | Log level for NGINX Agent. | "error" | |**nginxAgent.dataplaneKeySecretName** | Name of the Kubernetes Secret containing the Data Plane key used to authenticate to NGINX One Console. Learn more [here]({{< ref "/nginx-one/k8s/add-nic.md" >}}). Required when `nginxAgent.enable` is set to `true`. Requires NGINX Agent 3.x. | "" |