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..36597020c --- /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 & 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 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 af947d320..1ede09099 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. -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** file 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..672bdfb0f --- /dev/null +++ b/content/includes/use-cases/credential-download-instructions.md @@ -0,0 +1,25 @@ +--- +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..5f7e6af73 --- /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 >}} + +{{< tabs name="docker_login" >}} + +{{% 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 f91225abb..7bb2a5ffa 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/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/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 6b16b279c..e1f79746a 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -9,103 +9,51 @@ 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 >}} - 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`. +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. -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. +- [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" >}}) -### Upgrade the CRDs +## Install the Helm chart using the OCI Registry -{{< 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 >}} +Run the following commands to install the chart with the release name _my-release_ (Which you can customize): -To upgrade the CRDs, pull the chart sources as described in [Pull the Chart](#pull-the-chart) and then run: - -```shell -kubectl apply -f crds/ -``` +{{< tabs name="registry-chart-versions" >}} -Alternatively, CRDs can be upgraded without pulling the chart by running: +{{% tab name="NGINX Open Source" %}} ```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml +helm install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} ``` -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: - -```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 >}} - -## 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): - -- For NGINX: - - ```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`) - - ```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`. +{{% /tab %}} -### Upgrade the chart +{{% tab name="NGINX Plus" %}} -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`: +This assumes you have pushed NGINX Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`: ```shell -helm upgrade my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} +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 ``` -### Uninstall the chart - -To uninstall/delete the release `my-release`: +{{% /tab %}} -```shell -helm uninstall my-release -``` - -The command removes all the Kubernetes components associated with the release and deletes the release. +{{< /tabs >}} -Uninstalling the release does not remove the CRDs. To remove the CRDs, see [Uninstall the CRDs](#uninstall-the-crds). -### Edge version +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). -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,197 +62,75 @@ 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 - selectorLabels: {app: -nginx-ingress} - ``` +```shell +helm install my-release . +``` -5. Run `helm upgrade` with following arguments set: +{{% /tab %}} - ```shell - --set serviceNameOverride="-nginx-ingress" - --set controller.name="" - ``` +{{% tab name="NGINX Plus" %}} - It could look as follows: +```shell +helm install my-release . --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true +``` - ```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 - ``` +{{% /tab %}} -6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events: +{{< /tabs >}} - ```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. {{}} |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 | @@ -318,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. | @@ -340,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 | @@ -369,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" | @@ -423,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) | {} | @@ -471,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. | "" | @@ -492,3 +318,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. Requires NGINX Agent 2.x. | 50000 | |**nginxAgent.customConfigMap** | The name of a custom ConfigMap to use instead of the one provided by default. Requires NGINX Agent 2.x.| "" | {{}} + +## 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..7cc5e8372 100644 --- a/content/nic/installation/installing-nic/installation-with-manifests.md +++ b/content/nic/installation/installing-nic/installation-with-manifests.md @@ -2,27 +2,27 @@ 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 --- 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/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/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 new file mode 100644 index 000000000..f07d77ff4 --- /dev/null +++ b/content/nic/installation/nic-images/add-image-to-cluster.md @@ -0,0 +1,167 @@ +--- +title: Add an NGINX Ingress Controller image to your cluster +toc: true +weight: 150 +nd-content-type: how-to +nd-product: NIC +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. + +## Before you begin + +To follow these steps, you will need the following pre-requisite: + +- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.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 deployments + +If you are using Helm for deployment, there are two main methods: using a _chart_ or _source_. + +### Add the image from chart + +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 +``` +```json +{ +"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 +``` +```json +{ +"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 +``` +```json +{ +"name": "nginx-ic-dos/nginx-plus-ingress", +"tags": [ + "{{< nic-version >}}-ubi", + "{{< nic-version >}}" +] +} +``` + +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. + +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. +1. Open the `values.yaml` file in an editor. + + You must change a few lines NGINX Ingress Controller with NGINX Plus to be deployed. + + 1. Change the `nginxplus` argument to `true`. + 1. Change the `repository` argument to the NGINX Ingress Controller image you intend to use. + 1. 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: {} + +## 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: + +```shell +helm install nicdev01 -n nginx-ingress --create-namespace -f values.yaml . +``` + +The above command will install NGINX Ingress Controller in the `nginx-ingress` namespace. + +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. + +## 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. + +## Download an image for local use + +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 +``` + +Replace the contents of `` with the contents of the JWT token itself. +Once you have successfully pulled the image, you can then tag it as needed. + +{{< include "/nic/installation/jwt-password-note.md" >}} diff --git a/content/nic/installation/nic-images/get-image-using-jwt.md b/content/nic/installation/nic-images/get-image-using-jwt.md deleted file mode 100644 index 1dff0c74b..000000000 --- a/content/nic/installation/nic-images/get-image-using-jwt.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Get the NGINX Ingress Controller image with JWT -toc: true -weight: 150 -nd-content-type: how-to -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. - -## 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 the image using alternative 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. - -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 - -You will need the following information from [MyF5](https://my.f5.com) for these steps: - -- 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 - -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. - -## 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" >}} - ---- - -## 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 - -If you are using Helm for deployment, there are two main methods: using *sources* or *charts*. - -### Helm Source - -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. - -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. -1. Open the `values.yaml` file in an editor. - - You must change a few lines NGINX Ingress Controller with NGINX Plus to be deployed. - - 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: {} - - ## 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: - -```shell -helm install nicdev01 -n nginx-ingress --create-namespace -f values.yaml . -``` - -The above command will install NGINX Ingress Controller in the `nginx-ingress` namespace. - -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 >}}" - ] - } -``` - ---- - -## Pulling 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: - -```shell -docker login private-registry.nginx.com --username= --password=none -``` - -Replace the contents of `` with the contents of the JWT token itself. -Once you have successfully pulled the image, you can then tag it as needed. - -{{< include "/nic/installation/jwt-password-note.md" >}} diff --git a/content/nic/installation/nic-images/get-registry-image.md b/content/nic/installation/nic-images/registry-download.md similarity index 62% rename from content/nic/installation/nic-images/get-registry-image.md rename to content/nic/installation/nic-images/registry-download.md index 9cf8dd08a..c37c00e05 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,38 +7,37 @@ 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 registry. 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. - ## 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: -- [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. +- [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: -## Set up Docker for F5 Container Registry +- [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 [an image from DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) -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: +### Download your subscription credential files -```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 -``` +{{< include "use-cases/credential-download-instructions.md" >}} + +### 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 -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" >}}). +Identify which image you need using the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) topic. -To pull an image, follow these steps. Replace `` with the specific version you need, for example, `{{< nic-version >}}`. +Next, pull the image from `private-registry.nginx.com`. + +Replace `` with the specific version you need, for example, `{{< nic-version >}}`. - For NGINX Plus Ingress Controller, run: @@ -66,7 +65,6 @@ To pull an image, follow these steps. Replace `` with the specific docker pull private-registry.nginx.com/nap/waf-enforcer: ``` - - For NGINX Plus Ingress Controller with NGINX App Protect DoS, run: ```shell @@ -79,10 +77,14 @@ To pull an image, follow these steps. Replace `` with the specific 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": [ @@ -92,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": [ @@ -102,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": [ @@ -165,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. @@ -177,17 +187,8 @@ 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. - **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/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..ae5f3982a --- /dev/null +++ b/content/nic/installation/upgrade-version.md @@ -0,0 +1,318 @@ +--- +# 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 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`. + +Check the [release notes](https://www.github.com/nginx/kubernetes-ingress/releases) for a new release for any special upgrade procedures. +{{< /call-out >}} + +### 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 + +- 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 + +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. + +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" >}} + +{{% 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 %}} + +{{< /tabs >}} + +{{< call-out "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). + +```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. 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 >}} + +| **Level arguments** | **Format arguments** | +|---------------------|----------------------| +| `trace` | `json` | +| `debug` | `text` | +| `info` | `glog` | +| `warning` | | +| `error` | | +| `fatal` | | + +{{< tabs name="structured logging" >}} + +{{% tab name="Helm" %}} + +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. + +```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 %}} + +{{< /tabs >}} + +### 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. + +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 + +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 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. + +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. {{}} + +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: + +```shell +kubectl describe deployments -n +``` + +Copy the key=value under `Selector`, such as: + +```shell +Selector: app=nginx-ingress-nginx-ingress +``` + +Check out the latest available tag using `git checkout v{{< nic-version >}}` + +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. + +```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 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 +``` + +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 +``` + +Check out the latest available tag using `git checkout v{{< nic-version >}}` + +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. + +```shell +selectorLabels: {app: -nginx-ingress} +``` + +Run `helm upgrade` with following arguments set: + +```shell +--set serviceNameOverride="-nginx-ingress" +--set controller.name="" +``` + +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 +``` + +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 %}} + +{{< /tabs >}} diff --git a/content/nic/releases.md b/content/nic/releases.md index 2d55829f8..e7182a11b 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -158,10 +158,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`. +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/installing-nic/upgrade-to-v4.md#update-custom-resource-apiversion" >}}) 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: @@ -205,7 +205,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 @@ -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. 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 | 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..096ba4661 --- /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 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 + +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