From 35be40b4b2a45829f0127fc03dc558db2121f68b Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Mon, 11 Apr 2022 22:18:06 -0700 Subject: [PATCH 01/10] Release 2.2.0 --- CHANGELOG.md | 6 +++ README.md | 4 +- deployments/daemon-set/nginx-ingress.yaml | 2 +- .../daemon-set/nginx-plus-ingress.yaml | 2 +- deployments/deployment/nginx-ingress.yaml | 2 +- .../deployment/nginx-plus-ingress.yaml | 2 +- .../helm-chart-dos-arbitrator/README.md | 2 +- deployments/helm-chart/Chart.yaml | 8 ++-- deployments/helm-chart/README.md | 4 +- deployments/helm-chart/values-icp.yaml | 2 +- deployments/helm-chart/values-nsm.yaml | 2 +- deployments/helm-chart/values-plus.yaml | 2 +- deployments/helm-chart/values.yaml | 2 +- docs/content/app-protect-dos/configuration.md | 2 +- .../installation-with-helm-dos-arbitrator.md | 2 +- docs/content/app-protect-dos/installation.md | 4 +- docs/content/app-protect/configuration.md | 4 +- docs/content/app-protect/installation.md | 10 ++--- .../configuration/configuration-examples.md | 4 +- .../configmap-resource.md | 16 ++++---- .../global-configuration/custom-templates.md | 2 +- .../handling-host-and-listener-collisions.md | 2 +- ...advanced-configuration-with-annotations.md | 38 +++++++++---------- .../ingress-resources/basic-configuration.md | 2 +- .../cross-namespace-configuration.md | 4 +- .../ingress-resources/custom-annotations.md | 4 +- docs/content/configuration/policy-resource.md | 4 +- .../configuration/transportserver-resource.md | 2 +- ...server-and-virtualserverroute-resources.md | 6 +-- .../building-ingress-controller-image.md | 6 +-- .../installation/installation-with-helm.md | 4 +- .../installation-with-manifests.md | 2 +- .../installation-with-operator.md | 4 +- .../pulling-ingress-controller-image.md | 24 ++++++------ .../using-the-jwt-token-docker-secret.md | 12 +++--- .../intro/nginx-ingress-controllers.md | 4 +- docs/content/intro/nginx-plus.md | 6 +-- docs/content/releases.md | 30 +++++++++++++++ docs/content/technical-specifications.md | 25 ++++++------ 39 files changed, 151 insertions(+), 112 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8e26c32879..09351ff860 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +### 2.2.0 + +An automatically generated list of changes can be found on Github at: [2.2.0 Release](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0) + +A curated list of changes can be found in the [Releases](http://docs.nginx.com/nginx-ingress-controller/releases/) page on NGINX Documentation website. + ### 2.1.2 An automatically generated list of changes can be found on Github at: [2.1.2 Release](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.1.2) diff --git a/README.md b/README.md index 4a5b82d1ec..b55418c468 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus We publish Ingress controller releases on GitHub. See our [releases page](https://github.com/nginxinc/kubernetes-ingress/releases). -The latest stable release is [2.1.2](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.1.2). For production use, we recommend that you choose the latest stable release. As an alternative, you can choose the *edge* version built from the [latest commit](https://github.com/nginxinc/kubernetes-ingress/commits/main) from the main branch. The edge version is useful for experimenting with new features that are not yet published in a stable release. +The latest stable release is [2.2.0](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0). For production use, we recommend that you choose the latest stable release. As an alternative, you can choose the *edge* version built from the [latest commit](https://github.com/nginxinc/kubernetes-ingress/commits/main) from the main branch. The edge version is useful for experimenting with new features that are not yet published in a stable release. To use the Ingress controller, you need to have access to: * An Ingress controller image. @@ -66,7 +66,7 @@ The table below summarizes the options regarding the images, manifests, helm cha | Version | Description | Image for NGINX | Image for NGINX Plus | Installation Manifests and Helm Chart | Documentation and Examples | | ------- | ----------- | --------------- | -------------------- | ---------------------------------------| -------------------------- | -| Latest stable release | For production use | Use the 2.1.2 images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | Use the 2.1.2 images from the [F5 Container Registry](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image/) or the [AWS Marketplace](https://aws.amazon.com/marketplace/search/?CREATOR=741df81b-dfdc-4d36-b8da-945ea66b522c&FULFILLMENT_OPTION_TYPE=CONTAINER&filters=CREATOR%2CFULFILLMENT_OPTION_TYPE) or [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/deployments/helm-chart). | [Documentation](https://docs.nginx.com/nginx-ingress-controller/). [Examples](https://docs.nginx.com/nginx-ingress-controller/configuration/configuration-examples/). | +| Latest stable release | For production use | Use the 2.2.0 images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | Use the 2.2.0 images from the [F5 Container Registry](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image/) or the [AWS Marketplace](https://aws.amazon.com/marketplace/search/?CREATOR=741df81b-dfdc-4d36-b8da-945ea66b522c&FULFILLMENT_OPTION_TYPE=CONTAINER&filters=CREATOR%2CFULFILLMENT_OPTION_TYPE) or [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/deployments/helm-chart). | [Documentation](https://docs.nginx.com/nginx-ingress-controller/). [Examples](https://docs.nginx.com/nginx-ingress-controller/configuration/configuration-examples/). | | Edge/Nightly | For testing and experimenting | Use the edge or nightly images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/main/docs/content/installation/building-ingress-controller-image.md). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/main/docs/content/installation/building-ingress-controller-image.md). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/main/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/main/deployments/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/main/docs/content). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples). | ## Contacts diff --git a/deployments/daemon-set/nginx-ingress.yaml b/deployments/daemon-set/nginx-ingress.yaml index afbe0d921e..cabf9769c9 100644 --- a/deployments/daemon-set/nginx-ingress.yaml +++ b/deployments/daemon-set/nginx-ingress.yaml @@ -18,7 +18,7 @@ spec: spec: serviceAccountName: nginx-ingress containers: - - image: nginx/nginx-ingress:2.1.2 + - image: nginx/nginx-ingress:2.2.0 imagePullPolicy: IfNotPresent name: nginx-ingress ports: diff --git a/deployments/daemon-set/nginx-plus-ingress.yaml b/deployments/daemon-set/nginx-plus-ingress.yaml index 4fc112a30e..4d2ff8a0cc 100644 --- a/deployments/daemon-set/nginx-plus-ingress.yaml +++ b/deployments/daemon-set/nginx-plus-ingress.yaml @@ -18,7 +18,7 @@ spec: spec: serviceAccountName: nginx-ingress containers: - - image: nginx-plus-ingress:2.1.2 + - image: nginx-plus-ingress:2.2.0 imagePullPolicy: IfNotPresent name: nginx-plus-ingress ports: diff --git a/deployments/deployment/nginx-ingress.yaml b/deployments/deployment/nginx-ingress.yaml index c9cfbccae3..cf43ef8074 100644 --- a/deployments/deployment/nginx-ingress.yaml +++ b/deployments/deployment/nginx-ingress.yaml @@ -19,7 +19,7 @@ spec: spec: serviceAccountName: nginx-ingress containers: - - image: nginx/nginx-ingress:2.1.2 + - image: nginx/nginx-ingress:2.2.0 imagePullPolicy: IfNotPresent name: nginx-ingress ports: diff --git a/deployments/deployment/nginx-plus-ingress.yaml b/deployments/deployment/nginx-plus-ingress.yaml index 5ae2ab9e83..c616dfa8d0 100644 --- a/deployments/deployment/nginx-plus-ingress.yaml +++ b/deployments/deployment/nginx-plus-ingress.yaml @@ -19,7 +19,7 @@ spec: spec: serviceAccountName: nginx-ingress containers: - - image: nginx-plus-ingress:2.1.2 + - image: nginx-plus-ingress:2.2.0 imagePullPolicy: IfNotPresent name: nginx-plus-ingress ports: diff --git a/deployments/helm-chart-dos-arbitrator/README.md b/deployments/helm-chart-dos-arbitrator/README.md index a9ba1d9b5a..05567f1553 100644 --- a/deployments/helm-chart-dos-arbitrator/README.md +++ b/deployments/helm-chart-dos-arbitrator/README.md @@ -16,7 +16,7 @@ This step is required if you're installing the chart using its sources. Addition 1. Clone the Ingress controller repo: ```console - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.1 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` 2. Change your working directory to /deployments/helm-chart-dos-arbitrator: ```console diff --git a/deployments/helm-chart/Chart.yaml b/deployments/helm-chart/Chart.yaml index 368260bea8..bd2b41c6ac 100644 --- a/deployments/helm-chart/Chart.yaml +++ b/deployments/helm-chart/Chart.yaml @@ -1,13 +1,13 @@ name: nginx-ingress -version: 0.12.2 -appVersion: 2.1.2 +version: 0.13.0 +appVersion: 2.2.0 apiVersion: v1 kubeVersion: ">= 1.19.0-0" description: NGINX Ingress Controller -icon: https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.1.2/deployments/helm-chart/chart-icon.png +icon: https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.2.0/deployments/helm-chart/chart-icon.png home: https://github.com/nginxinc/kubernetes-ingress sources: - - https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/deployments/helm-chart + - https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/deployments/helm-chart keywords: - ingress - nginx diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index 9cc6bdd6cd..1b236cf275 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -23,7 +23,7 @@ This step is required if you're installing the chart using its sources. Addition 1. Clone the Ingress controller repo: ```console - $ git clone https://github.com/nginxinc/kubernetes-ingress --branch v2.1.1 + $ git clone https://github.com/nginxinc/kubernetes-ingress --branch v2.2.0 ``` **Note**: If you want to use the experimental repository (`edge`), remove the `--branch` flag and value. @@ -156,7 +156,7 @@ Parameter | Description | Default `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. | 1 `controller.image.repository` | The image repository of the Ingress controller. | nginx/nginx-ingress -`controller.image.tag` | The tag of the Ingress controller image. | 2.1.2 +`controller.image.tag` | The tag of the Ingress controller image. | 2.2.0 `controller.image.pullPolicy` | The pull policy for the Ingress controller image. | IfNotPresent `controller.config.name` | The name of the ConfigMap used by the Ingress controller. | Autogenerated `controller.config.annotations` | The annotations of the Ingress controller configmap. | {} diff --git a/deployments/helm-chart/values-icp.yaml b/deployments/helm-chart/values-icp.yaml index f403590ebb..36e488e0ae 100644 --- a/deployments/helm-chart/values-icp.yaml +++ b/deployments/helm-chart/values-icp.yaml @@ -3,7 +3,7 @@ controller: nginxplus: true image: repository: mycluster.icp:8500/kube-system/nginx-plus-ingress - tag: "2.1.2" + tag: "2.2.0" nodeSelector: beta.kubernetes.io/arch: "amd64" proxy: true diff --git a/deployments/helm-chart/values-nsm.yaml b/deployments/helm-chart/values-nsm.yaml index 9ae603fae3..93b2589309 100644 --- a/deployments/helm-chart/values-nsm.yaml +++ b/deployments/helm-chart/values-nsm.yaml @@ -2,7 +2,7 @@ controller: nginxplus: true image: repository: nginx-plus-ingress - tag: "2.1.1" + tag: "2.2.0" enableLatencyMetrics: true nginxServiceMesh: enable: true diff --git a/deployments/helm-chart/values-plus.yaml b/deployments/helm-chart/values-plus.yaml index a72b1b15ab..d983927ce3 100644 --- a/deployments/helm-chart/values-plus.yaml +++ b/deployments/helm-chart/values-plus.yaml @@ -2,4 +2,4 @@ controller: nginxplus: true image: repository: nginx-plus-ingress - tag: "2.1.2" + tag: "2.2.0" diff --git a/deployments/helm-chart/values.yaml b/deployments/helm-chart/values.yaml index 542aa81b2a..04bcef7534 100644 --- a/deployments/helm-chart/values.yaml +++ b/deployments/helm-chart/values.yaml @@ -49,7 +49,7 @@ controller: repository: nginx/nginx-ingress ## The tag of the Ingress controller image. - tag: "2.1.2" + tag: "2.2.0" ## The pull policy for the Ingress controller image. pullPolicy: IfNotPresent diff --git a/docs/content/app-protect-dos/configuration.md b/docs/content/app-protect-dos/configuration.md index fcc8025af2..529d521cf2 100644 --- a/docs/content/app-protect-dos/configuration.md +++ b/docs/content/app-protect-dos/configuration.md @@ -9,7 +9,7 @@ docs: "DOCS-580" --- This document describes how to configure the NGINX App Protect DoS module -> Check out the complete [NGINX Ingress Controller with App Protect DoS example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect-dos). +> Check out the complete [NGINX Ingress Controller with App Protect DoS example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect-dos). ## App Protect DoS Configuration diff --git a/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md b/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md index ce3443fb96..ed2f754a3a 100644 --- a/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md +++ b/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md @@ -19,7 +19,7 @@ This step is required if you're installing the chart using its sources. Addition 1. Clone the Ingress controller repo: ```console - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.2 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` 2. Change your working directory to /deployments/helm-chart-dos-arbitrator: ```console diff --git a/docs/content/app-protect-dos/installation.md b/docs/content/app-protect-dos/installation.md index 15e3639d1e..b960fbd13a 100644 --- a/docs/content/app-protect-dos/installation.md +++ b/docs/content/app-protect-dos/installation.md @@ -19,7 +19,7 @@ This document provides an overview of the steps required to use NGINX App Protec * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). 2. Clone the Ingress controller repo: ``` - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.2 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 $ cd kubernetes-ingress ``` @@ -63,4 +63,4 @@ Take the steps below to set up and deploy the NGINX Ingress Controller and App P 3. Enable the App Protect Dos module by adding the `enable-app-protect-dos` [cli argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-app-protect-dos) to your Deployment or DaemonSet file. 4. [Deploy the Ingress Controller](/nginx-ingress-controller/installation/installation-with-manifests/#3-deploy-the-ingress-controller). -For more information, see the [Configuration guide](/nginx-ingress-controller/app-protect-dos/configuration),the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect-dos) and the [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources/dos). +For more information, see the [Configuration guide](/nginx-ingress-controller/app-protect-dos/configuration),the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect-dos) and the [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/dos). diff --git a/docs/content/app-protect/configuration.md b/docs/content/app-protect/configuration.md index 1a8b19c06e..3ece821599 100644 --- a/docs/content/app-protect/configuration.md +++ b/docs/content/app-protect/configuration.md @@ -9,13 +9,13 @@ docs: "DOCS-578" --- This document describes how to configure the NGINX App Protect module -> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). +> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). ## Global Configuration The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect module. See [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#modules) for the complete list. The App Protect parameters use the `app-protect*` prefix. -> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). +> Check out the complete [NGINX Ingress Controller with App Protect example resources on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). ## Enable App Protect for an Ingress Resource diff --git a/docs/content/app-protect/installation.md b/docs/content/app-protect/installation.md index 5baf6a434a..911a205856 100644 --- a/docs/content/app-protect/installation.md +++ b/docs/content/app-protect/installation.md @@ -23,9 +23,9 @@ Take the steps below to either configure a Docker Registry secret in your Kubern For NGINX Plus Ingress Controller with App Protect, pull from `private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`: ``` - $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.1.2 + $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.2.0 ``` - `2.1.2` will pull down the Debian based image. The other available image tag is `2.1.2-ubi` for the UBI based image. + `2.2.0` will pull down the Debian based image. The other available image tag is `2.2.0-ubi` for the UBI based image. - Use the docker registry API to list the available image tags for the repository. @@ -35,8 +35,8 @@ Take the steps below to either configure a Docker Registry secret in your Kubern { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ - "2.1.2-ubi", - "2.1.2" + "2.2.0-ubi", + "2.2.0" ] } ``` @@ -74,4 +74,4 @@ Take the steps below to set up and deploy the NGINX Ingress Controller and App P 3. Enable the App Protect module by adding the `enable-app-protect` [cli argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-app-protect) to your Deployment or DaemonSet file. 4. [Deploy the Ingress Controller](/nginx-ingress-controller/installation/installation-with-manifests/#3-deploy-the-ingress-controller). -For more information, see the [Configuration guide](/nginx-ingress-controller/app-protect/configuration) and the [NGINX Ingress Controller with App Protect examples on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). +For more information, see the [Configuration guide](/nginx-ingress-controller/app-protect/configuration) and the [NGINX Ingress Controller with App Protect examples on GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). diff --git a/docs/content/configuration/configuration-examples.md b/docs/content/configuration/configuration-examples.md index 3ee5aaa0c2..493938fb68 100644 --- a/docs/content/configuration/configuration-examples.md +++ b/docs/content/configuration/configuration-examples.md @@ -10,5 +10,5 @@ docs: "DOCS-584" Our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress) includes a number of configuration examples: -* [*Examples*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples) show how to use advanced NGINX features in Ingress resources with annotations. -* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases. +* [*Examples*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples) show how to use advanced NGINX features in Ingress resources with annotations. +* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases. diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index bc85015662..4572305ddc 100644 --- a/docs/content/configuration/global-configuration/configmap-resource.md +++ b/docs/content/configuration/global-configuration/configmap-resource.md @@ -86,10 +86,10 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres |``worker-shutdown-timeout`` | Sets the value of the [worker_shutdown_timeout](https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout) directive. | N/A | | |``server-names-hash-bucket-size`` | Sets the value of the [server_names_hash_bucket_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | ``256`` | | |``server-names-hash-max-size`` | Sets the value of the [server_names_hash_max_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | ``1024`` | | -|``resolver-addresses`` | Sets the value of the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) addresses. Note: If you use a DNS name (ex., ``kube-dns.kube-system.svc.cluster.local`` ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. As a consequence, If the name cannot be resolved or the DNS server doesn't respond, NGINX Plus will fail to start or reload. To avoid this, consider using only IP addresses as resolver addresses. Supported in NGINX Plus only. | N/A | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/externalname-services). | -|``resolver-ipv6`` | Enables IPv6 resolution in the resolver. Supported in NGINX Plus only. | ``True`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/externalname-services). | -|``resolver-valid`` | Sets the time NGINX caches the resolved DNS records. Supported in NGINX Plus only. | TTL value of a DNS record | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/externalname-services). | -|``resolver-timeout`` | Sets the [resolver_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_timeout) for name resolution. Supported in NGINX Plus only. | ``30s`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/externalname-services). | +|``resolver-addresses`` | Sets the value of the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) addresses. Note: If you use a DNS name (ex., ``kube-dns.kube-system.svc.cluster.local`` ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. As a consequence, If the name cannot be resolved or the DNS server doesn't respond, NGINX Plus will fail to start or reload. To avoid this, consider using only IP addresses as resolver addresses. Supported in NGINX Plus only. | N/A | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | +|``resolver-ipv6`` | Enables IPv6 resolution in the resolver. Supported in NGINX Plus only. | ``True`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | +|``resolver-valid`` | Sets the time NGINX caches the resolved DNS records. Supported in NGINX Plus only. | TTL value of a DNS record | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | +|``resolver-timeout`` | Sets the [resolver_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_timeout) for name resolution. Supported in NGINX Plus only. | ``30s`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | |``keepalive-timeout`` | Sets the value of the [keepalive_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout) directive. | ``65s`` | | |``keepalive-requests`` | Sets the value of the [keepalive_requests](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests) directive. | ``100`` | | |``variables-hash-bucket-size`` | Sets the value of the [variables_hash_bucket_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_bucket_size) directive. | ``256`` | | @@ -104,9 +104,9 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres |``error-log-level`` | Sets the global [error log level](https://nginx.org/en/docs/ngx_core_module.html#error_log) for NGINX. | ``notice`` | | |``access-log-off`` | Disables the [access log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log). | ``False`` | | |``default-server-access-log-off`` | Disables the [access log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) for the default server. If access log is disabled globally (``access-log-off: "True"``), then the default server access log is always disabled. | ``False`` | | -|``log-format`` | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for HTTP and HTTPS traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by ``\n``). In that case, the Ingress Controller will replace every ``\n`` character with a space character. All ``'`` characters must be escaped. | See the [template file](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-log-format). | +|``log-format`` | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for HTTP and HTTPS traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by ``\n``). In that case, the Ingress Controller will replace every ``\n`` character with a space character. All ``'`` characters must be escaped. | See the [template file](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-log-format). | |``log-format-escaping`` | Sets the characters escaping for the variables of the log format. Supported values: ``json`` (JSON escaping), ``default`` (the default escaping) ``none`` (disables escaping). | ``default`` | | -|``stream-log-format`` | Sets the custom [log format](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format) for TCP, UDP, and TLS Passthrough traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by ``\n``). In that case, the Ingress Controller will replace every ``\n`` character with a space character. All ``'`` characters must be escaped. | See the [template file](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/internal/configs/version1/nginx.tmpl). | | +|``stream-log-format`` | Sets the custom [log format](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format) for TCP, UDP, and TLS Passthrough traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by ``\n``). In that case, the Ingress Controller will replace every ``\n`` character with a space character. All ``'`` characters must be escaped. | See the [template file](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/internal/configs/version1/nginx.tmpl). | | |``stream-log-format-escaping`` | Sets the characters escaping for the variables of the stream log format. Supported values: ``json`` (JSON escaping), ``default`` (the default escaping) ``none`` (disables escaping). | ``default`` | | {{% /table %}} @@ -142,7 +142,7 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | |``http2`` | Enables HTTP/2 in servers with SSL enabled. | ``False`` | | -|``proxy-protocol`` | Enables PROXY Protocol for incoming connections. | ``False`` | [Proxy Protocol](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/proxy-protocol). | +|``proxy-protocol`` | Enables PROXY Protocol for incoming connections. | ``False`` | [Proxy Protocol](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/proxy-protocol). | {{% /table %}} ### Backend Services (Upstreams) @@ -166,7 +166,7 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres |``http-snippets`` | Sets a custom snippet in http context. | N/A | | |``location-snippets`` | Sets a custom snippet in location context. | N/A | | |``server-snippets`` | Sets a custom snippet in server context. | N/A | | -|``stream-snippets`` | Sets a custom snippet in stream context. | N/A | [Support for TCP/UDP Load Balancing](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/tcp-udp). | +|``stream-snippets`` | Sets a custom snippet in stream context. | N/A | [Support for TCP/UDP Load Balancing](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/tcp-udp). | |``main-template`` | Sets the main NGINX configuration template. | By default the template is read from the file in the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | |``ingress-template`` | Sets the NGINX configuration template for an Ingress resource. | By default the template is read from the file on the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | |``virtualserver-template`` | Sets the NGINX configuration template for an VirtualServer resource. | By default the template is read from the file on the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | diff --git a/docs/content/configuration/global-configuration/custom-templates.md b/docs/content/configuration/global-configuration/custom-templates.md index 215fa3cce7..81e1df3eed 100644 --- a/docs/content/configuration/global-configuration/custom-templates.md +++ b/docs/content/configuration/global-configuration/custom-templates.md @@ -9,4 +9,4 @@ docs: "DOCS-587" --- -The Ingress Controller uses templates to generate NGINX configuration for Ingress resources, VirtualServer resources and the main NGINX configuration file. You can customize the templates and apply them via the ConfigMap. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-templates). +The Ingress Controller uses templates to generate NGINX configuration for Ingress resources, VirtualServer resources and the main NGINX configuration file. You can customize the templates and apply them via the ConfigMap. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-templates). diff --git a/docs/content/configuration/handling-host-and-listener-collisions.md b/docs/content/configuration/handling-host-and-listener-collisions.md index cd45c942fe..b2f18731c7 100644 --- a/docs/content/configuration/handling-host-and-listener-collisions.md +++ b/docs/content/configuration/handling-host-and-listener-collisions.md @@ -80,7 +80,7 @@ Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` a It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. See the [Cross-namespace Configuration](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/) doc for more information. -It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources/cross-namespace-configuration) on GitHub. +It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/cross-namespace-configuration) on GitHub. It is *not* possible to merge configuration for multiple TransportServer resources. diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md index 271d921720..2d540a3a01 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -134,7 +134,7 @@ The table below summarizes the available annotations. | ---| ---| ---| ---| --- | |``nginx.org/proxy-hide-headers`` | ``proxy-hide-headers`` | Sets the value of one or more [proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directives. Example: ``"nginx.org/proxy-hide-headers": "header-a,header-b"`` | N/A | | |``nginx.org/proxy-pass-headers`` | ``proxy-pass-headers`` | Sets the value of one or more [proxy_pass_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directives. Example: ``"nginx.org/proxy-pass-headers": "header-a,header-b"`` | N/A | | -|``nginx.org/rewrites`` | N/A | Configures URI rewriting. | N/A | [Rewrites Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/rewrites). | +|``nginx.org/rewrites`` | N/A | Configures URI rewriting. | N/A | [Rewrites Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/rewrites). | {{% /table %}} ### Auth and SSL/TLS @@ -148,10 +148,10 @@ The table below summarizes the available annotations. |``nginx.org/hsts-max-age`` | ``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | | |``nginx.org/hsts-include-subdomains`` | ``hsts-include-subdomains`` | Adds the ``includeSubDomains`` directive to the HSTS header. | ``False`` | | |``nginx.org/hsts-behind-proxy`` | ``hsts-behind-proxy`` | Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. | ``False`` | | -|``nginx.com/jwt-key`` | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/jwt). | -|``nginx.com/jwt-realm`` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/jwt). | -|``nginx.com/jwt-token`` | N/A | Specifies a variable that contains JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/jwt). | -|``nginx.com/jwt-login-url`` | N/A | Specifies a URL to which a client is redirected in case of an invalid or missing JWT. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/jwt). | +|``nginx.com/jwt-key`` | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | +|``nginx.com/jwt-realm`` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | +|``nginx.com/jwt-token`` | N/A | Specifies a variable that contains JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | +|``nginx.com/jwt-login-url`` | N/A | Specifies a URL to which a client is redirected in case of an invalid or missing JWT. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | {{% /table %}} ### Listeners @@ -169,19 +169,19 @@ The table below summarizes the available annotations. |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | |``nginx.org/lb-method`` | ``lb-method`` | Sets the [load balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify ``"round_robin"``. | ``"random two least_conn"`` | | -|``nginx.org/ssl-services`` | N/A | Enables HTTPS or gRPC over SSL when connecting to the endpoints of services. | N/A | [SSL Services Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/ssl-services). | -|``nginx.org/grpc-services`` | N/A | Enables gRPC for services. Note: requires HTTP/2 (see ``http2`` ConfigMap key); only works for Ingresses with TLS termination enabled. | N/A | [GRPC Services Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/grpc-services). | -|``nginx.org/websocket-services`` | N/A | Enables WebSocket for services. | N/A | [WebSocket support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/websocket). | +|``nginx.org/ssl-services`` | N/A | Enables HTTPS or gRPC over SSL when connecting to the endpoints of services. | N/A | [SSL Services Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/ssl-services). | +|``nginx.org/grpc-services`` | N/A | Enables gRPC for services. Note: requires HTTP/2 (see ``http2`` ConfigMap key); only works for Ingresses with TLS termination enabled. | N/A | [GRPC Services Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/grpc-services). | +|``nginx.org/websocket-services`` | N/A | Enables WebSocket for services. | N/A | [WebSocket support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/websocket). | |``nginx.org/max-fails`` | ``max-fails`` | Sets the value of the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the ``server`` directive. | ``1`` | | |``nginx.org/max-conns`` | N\A | Sets the value of the [max_conns](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns) parameter of the ``server`` directive. | ``0`` | | |``nginx.org/upstream-zone-size`` | ``upstream-zone-size`` | Sets the size of the shared memory [zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone) for upstreams. For NGINX, the special value 0 disables the shared memory zones. For NGINX Plus, shared memory zones are required and cannot be disabled. The special value 0 will be ignored. | ``256K`` | | |``nginx.org/fail-timeout`` | ``fail-timeout`` | Sets the value of the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the ``server`` directive. | ``10s`` | | -|``nginx.com/sticky-cookie-services`` | N/A | Configures session persistence. | N/A | [Session Persistence](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/session-persistence). | +|``nginx.com/sticky-cookie-services`` | N/A | Configures session persistence. | N/A | [Session Persistence](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/session-persistence). | |``nginx.org/keepalive`` | ``keepalive`` | Sets the value of the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. Note that ``proxy_set_header Connection "";`` is added to the generated configuration when the value > 0. | ``0`` | | -|``nginx.com/health-checks`` | N/A | Enables active health checks. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/health-checks). | -|``nginx.com/health-checks-mandatory`` | N/A | Configures active health checks as mandatory. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/health-checks). | -|``nginx.com/health-checks-mandatory-queue`` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | ``0`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/health-checks). | -|``nginx.com/slow-start`` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly added servers, configure [mandatory active health checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/health-checks). | ``"0s"`` | | +|``nginx.com/health-checks`` | N/A | Enables active health checks. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | +|``nginx.com/health-checks-mandatory`` | N/A | Configures active health checks as mandatory. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | +|``nginx.com/health-checks-mandatory-queue`` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | ``0`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | +|``nginx.com/slow-start`` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly added servers, configure [mandatory active health checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | ``"0s"`` | | {{% /table %}} ### Snippets and Custom Templates @@ -200,11 +200,11 @@ The table below summarizes the available annotations. {{% table %}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``appprotect.f5.com/app-protect-policy`` | N/A | The name of the App Protect Policy for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace of the Ingress Resource is used. If not specified but ``appprotect.f5.com/app-protect-enable`` is true, a default policy id applied. If the referenced policy resource does not exist, or policy is invalid, this annotation will be ignored, and the default policy will be applied. | N/A | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). | -|``appprotect.f5.com/app-protect-enable`` | N/A | Enable App Protect for the Ingress Resource. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). | -|``appprotect.f5.com/app-protect-security-log-enable`` | N/A | Enable the [security log](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) for App Protect. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). | -|``appprotect.f5.com/app-protect-security-log`` | N/A | The App Protect log configuration for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace as the Ingress Resource is used. If not specified the default is used which is: filter: ``illegal``, format: ``default``. Multiple configurations can be specified in a comma separated list. Both log configurations and destinations list (see below) must be of equal length. Configs and destinations are paired by the list indices. | N/A | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). | -|``appprotect.f5.com/app-protect-security-log-destination`` | N/A | The destination of the security log. For more information check the [DESTINATION argument](/nginx-app-protect/troubleshooting/#app-protect-logging-overview). Multiple destinations can be specified in a coma separated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. | ``syslog:server=localhost:514`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect). | +|``appprotect.f5.com/app-protect-policy`` | N/A | The name of the App Protect Policy for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace of the Ingress Resource is used. If not specified but ``appprotect.f5.com/app-protect-enable`` is true, a default policy id applied. If the referenced policy resource does not exist, or policy is invalid, this annotation will be ignored, and the default policy will be applied. | N/A | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | +|``appprotect.f5.com/app-protect-enable`` | N/A | Enable App Protect for the Ingress Resource. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | +|``appprotect.f5.com/app-protect-security-log-enable`` | N/A | Enable the [security log](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) for App Protect. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | +|``appprotect.f5.com/app-protect-security-log`` | N/A | The App Protect log configuration for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace as the Ingress Resource is used. If not specified the default is used which is: filter: ``illegal``, format: ``default``. Multiple configurations can be specified in a comma separated list. Both log configurations and destinations list (see below) must be of equal length. Configs and destinations are paired by the list indices. | N/A | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | +|``appprotect.f5.com/app-protect-security-log-destination`` | N/A | The destination of the security log. For more information check the [DESTINATION argument](/nginx-app-protect/troubleshooting/#app-protect-logging-overview). Multiple destinations can be specified in a coma separated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. | ``syslog:server=localhost:514`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | {{% /table %}} ### App Protect DoS @@ -214,5 +214,5 @@ The table below summarizes the available annotations. {{% table %}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``appprotectdos.f5.com/app-protect-dos-resource`` | N/A | Enable App Protect DoS for the Ingress Resource by specifying a [DosProtectedResource](/nginx-ingress-controller/app-protect-dos/dos-protected/). | N/A | [Example for App Protect DoS](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/appprotect-dos). | +|``appprotectdos.f5.com/app-protect-dos-resource`` | N/A | Enable App Protect DoS for the Ingress Resource by specifying a [DosProtectedResource](/nginx-ingress-controller/app-protect-dos/dos-protected/). | N/A | [Example for App Protect DoS](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect-dos). | {{% /table %}} diff --git a/docs/content/configuration/ingress-resources/basic-configuration.md b/docs/content/configuration/ingress-resources/basic-configuration.md index 8424b9ad1d..fe37e89048 100644 --- a/docs/content/configuration/ingress-resources/basic-configuration.md +++ b/docs/content/configuration/ingress-resources/basic-configuration.md @@ -51,7 +51,7 @@ Here is a breakdown of what this Ingress resource definition means: * The rule with the path `/coffee` instructs NGINX to distribute the requests with the `/coffee` URI among the pods of the *coffee* service, which is deployed with the name `coffee‑svc` in the cluster. * Both rules instruct NGINX to distribute the requests to `port 80` of the corresponding service (the `servicePort` field). -> For complete instructions on deploying the Ingress and Secret resources in the cluster, see the [complete-example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/complete-example) in our GitHub repo. +> For complete instructions on deploying the Ingress and Secret resources in the cluster, see the [complete-example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/complete-example) in our GitHub repo. > To learn more about the Ingress resource, see the [Ingress resource documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the Kubernetes docs. diff --git a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md index bb36de6992..3f75d41576 100644 --- a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md +++ b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md @@ -9,6 +9,6 @@ docs: "DOCS-594" --- -You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/mergeable-ingress-types) example on our GitHub. +You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/mergeable-ingress-types) example on our GitHub. -As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources/cross-namespace-configuration) example on our GitHub. +As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/cross-namespace-configuration) example on our GitHub. diff --git a/docs/content/configuration/ingress-resources/custom-annotations.md b/docs/content/configuration/ingress-resources/custom-annotations.md index 1852c9a484..932aca508b 100644 --- a/docs/content/configuration/ingress-resources/custom-annotations.md +++ b/docs/content/configuration/ingress-resources/custom-annotations.md @@ -23,7 +23,7 @@ Custom annotations allow you to add an annotation for an NGINX feature that is n ## Usage -The Ingress Controller generates NGINX configuration for Ingress resources by executing a configuration template. See [NGINX template](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/internal/configs/version1/nginx.ingress.tmpl) or [NGINX Plus template](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/internal/configs/version1/nginx-plus.ingress.tmpl). +The Ingress Controller generates NGINX configuration for Ingress resources by executing a configuration template. See [NGINX template](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/internal/configs/version1/nginx.ingress.tmpl) or [NGINX Plus template](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/internal/configs/version1/nginx-plus.ingress.tmpl). To support custom annotations, the template has access to the information about the Ingress resource - its *name*, *namespace* and *annotations*. It is possible to check if a particular annotation present in the Ingress resource and conditionally insert NGINX configuration directives at multiple NGINX contexts - `http`, `server`, `location` or `upstream`. Additionally, you can get the value that is set to the annotation. @@ -132,4 +132,4 @@ deny all; ## Example -See the [custom annotations example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/examples/custom-annotations). +See the [custom annotations example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/examples/custom-annotations). diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index 81a0e2d497..1d26a47e67 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -13,7 +13,7 @@ The Policy resource allows you to configure features like access control and rat The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/examples/custom-resources/access-control). +This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/examples/custom-resources/access-control). ## Prerequisites @@ -297,7 +297,7 @@ NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP #### Prerequisites -For the OIDC feature to work, it is necessary to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/), otherwise NGINX Plus will fail to reload. Additionally, it is necessary to configure a resolver, so that NGINX Plus can resolve the IDP authorization endpoint. For an example of the necessary configuration see the documentation [here](https://github.com/nginxinc/kubernetes-ingress/blob/v2.1.2/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). +For the OIDC feature to work, it is necessary to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/), otherwise NGINX Plus will fail to reload. Additionally, it is necessary to configure a resolver, so that NGINX Plus can resolve the IDP authorization endpoint. For an example of the necessary configuration see the documentation [here](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). > **Note**: The configuration in the example doesn't enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens. diff --git a/docs/content/configuration/transportserver-resource.md b/docs/content/configuration/transportserver-resource.md index f4aa9ad7c7..b74d7f2c46 100644 --- a/docs/content/configuration/transportserver-resource.md +++ b/docs/content/configuration/transportserver-resource.md @@ -10,7 +10,7 @@ docs: "DOCS-598" The TransportServer resource allows you to configure TCP, UDP, and TLS Passthrough load balancing. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the TransportServer resource. To see additional examples of using the resource for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.1/examples/custom-resources) folder in our GitHub repo. +This document is the reference documentation for the TransportServer resource. To see additional examples of using the resource for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources) folder in our GitHub repo. ## Prerequisites diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index 4483598150..a806c61bbd 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -12,7 +12,7 @@ docs: "DOCS-599" The VirtualServer and VirtualServerRoute resources are new load balancing configuration, introduced in release 1.5 as an alternative to the Ingress resource. The resources enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. The resources are implemented as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources) folder in our GitHub repo. +This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources) folder in our GitHub repo. ## VirtualServer Specification @@ -277,7 +277,7 @@ tls: |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``upstream-123`` are valid. The name must be unique among all upstreams of the resource. | ``string`` | Yes | -|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. For NGINX Plus only, services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) are also supported (check the [prerequisites](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/externalname-services#prerequisites) ). | ``string`` | Yes | +|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. For NGINX Plus only, services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) are also supported (check the [prerequisites](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services#prerequisites) ). | ``string`` | Yes | |``subselector`` | Selects the pods within the service using label keys and values. By default, all pods of the service are selected. Note: the specified labels are expected to be present in the pods when they are created. If the pod labels are updated, the Ingress Controller will not see that change until the number of the pods is changed. | ``map[string]string`` | No | |``use-cluster-ip`` | Enables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like ``lb-method`` and ``next-upstream``) will have no effect, as the Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | ``boolean`` | No | |``port`` | The port of the service. If the service doesn't define that port, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. The port must fall into the range ``1..65535``. | ``uint16`` | Yes | @@ -552,7 +552,7 @@ proxy: |``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | |``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | |``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | -|``rewritePath`` | The rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/custom-resources/rewrites) example. | ``string`` | No | +|``rewritePath`` | The rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/rewrites) example. | ``string`` | No | {{% /table %}} ### Action.Proxy.RequestHeaders diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index 33be4c1aae..8693549d3e 100644 --- a/docs/content/installation/building-ingress-controller-image.md +++ b/docs/content/installation/building-ingress-controller-image.md @@ -32,7 +32,7 @@ We build the image using the make utility and the provided `Makefile`. Let’s c 1. Clone the Ingress Controller repo: ``` - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.2 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 $ cd kubernetes-ingress ``` @@ -47,7 +47,7 @@ We build the image using the make utility and the provided `Makefile`. Let’s c ``` `myregistry.example.com/nginx-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry. - As a result, the image **myregistry.example.com/nginx-ingress:2.1.2** is built. Note that the tag `2.1.2` comes from the `VERSION` variable, defined in the Makefile. + As a result, the image **myregistry.example.com/nginx-ingress:2.2.0** is built. Note that the tag `2.2.0` comes from the `VERSION` variable, defined in the Makefile. * For **NGINX Plus**, first, make sure that the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) of your license are located in the root of the project: ``` @@ -60,7 +60,7 @@ We build the image using the make utility and the provided `Makefile`. Let’s c ``` `myregistry.example.com/nginx-plus-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry. - As a result, the image **myregistry.example.com/nginx-plus-ingress:2.1.2** is built. Note that the tag `2.1.2` comes from the `VERSION` variable, defined in the Makefile. + As a result, the image **myregistry.example.com/nginx-plus-ingress:2.2.0** is built. Note that the tag `2.2.0` comes from the `VERSION` variable, defined in the Makefile. **Note**: In the event of a patch version of [NGINX Plus being released](/nginx/releases/), make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the `make` command. diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index 197ee76c1e..42f37887a1 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -28,7 +28,7 @@ This step is required if you're installing the chart using its sources. Addition 1. Clone the Ingress controller repo: ```console - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.2 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` 2. Change your working directory to /deployments/helm-chart: ```console @@ -160,7 +160,7 @@ The following tables lists the configurable parameters of the NGINX Ingress cont |``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. | 1 | |``controller.image.repository`` | The image repository of the Ingress controller. | nginx/nginx-ingress | -|``controller.image.tag`` | The tag of the Ingress controller image. | 2.1.2 | +|``controller.image.tag`` | The tag of the Ingress controller image. | 2.2.0 | |``controller.image.pullPolicy`` | The pull policy for the Ingress controller image. | IfNotPresent | |``controller.config.name`` | The name of the ConfigMap used by the Ingress controller. | Autogenerated | |``controller.config.entries`` | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) for the list of supported ConfigMap keys. | {} | diff --git a/docs/content/installation/installation-with-manifests.md b/docs/content/installation/installation-with-manifests.md index 553db50eb0..5acf15d8bf 100644 --- a/docs/content/installation/installation-with-manifests.md +++ b/docs/content/installation/installation-with-manifests.md @@ -21,7 +21,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). 2. Clone the Ingress controller repo and change into the deployments folder: ``` - $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.1.1 + $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 $ cd kubernetes-ingress/deployments ``` diff --git a/docs/content/installation/installation-with-operator.md b/docs/content/installation/installation-with-operator.md index a837459551..61a36f9434 100644 --- a/docs/content/installation/installation-with-operator.md +++ b/docs/content/installation/installation-with-operator.md @@ -8,6 +8,8 @@ toc: true docs: "DOCS-604" --- +**Note: an NGINX Ingress Operator version compatible with the 2.2.0 NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version.** + This document describes how to install the NGINX Ingress Controller in your Kubernetes cluster using the NGINX Ingress Operator. ## Prerequisites @@ -33,7 +35,7 @@ spec: type: deployment image: repository: nginx/nginx-ingress - tag: 2.1.2 + tag: 2.2.0 pullPolicy: Always serviceType: NodePort nginxPlus: False diff --git a/docs/content/installation/pulling-ingress-controller-image.md b/docs/content/installation/pulling-ingress-controller-image.md index a99a0c8ad1..0de76a95ad 100644 --- a/docs/content/installation/pulling-ingress-controller-image.md +++ b/docs/content/installation/pulling-ingress-controller-image.md @@ -35,12 +35,12 @@ Before you can pull the image, make sure that the following software is installe 2. Use Docker to pull the required image from `private-registry.nginx.com`. Choose the image from the available images listed in the [tech specs guide]({{< relref "technical-specifications#images-with-nginx-plus" >}}). For NGINX Plus Ingress Controller, pull from `private-registry.nginx.com/nginx-ic/nginx-plus-ingress`. For example: ``` - $ docker pull private-registry.nginx.com/nginx-ic/nginx-plus-ingress:2.1.2 + $ docker pull private-registry.nginx.com/nginx-ic/nginx-plus-ingress:2.2.0 ``` For NGINX Plus Ingress Controller with App Protect, pull from `private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress`. For example: ``` - $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.1.2 + $ docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.2.0 ``` To list the available image tags for the repositories, you can also use the Docker registry API. For example: @@ -49,10 +49,10 @@ Before you can pull the image, make sure that the following software is installe { "name": "nginx-ic/nginx-plus-ingress", "tags": [ - "2.1.2-alpine", - "2.1.2-ot", - "2.1.2-ubi", - "2.1.2" + "2.2.0-alpine", + "2.2.0-ot", + "2.2.0-ubi", + "2.2.0" ] } @@ -60,8 +60,8 @@ Before you can pull the image, make sure that the following software is installe { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ - "2.1.2-ubi", - "2.1.2" + "2.2.0-ubi", + "2.2.0" ] } ``` @@ -72,12 +72,12 @@ Before you can pull the image, make sure that the following software is installe - Replace `` in the examples below with the correct path to your private Docker registry. ``` - $ docker tag private-registry.nginx.com/nginx-ic/nginx-plus-ingress:2.1.2 /nginx-ic/nginx-plus-ingress:2.1.2 - $ docker push /nginx-ic/nginx-plus-ingress:2.1.2 + $ docker tag private-registry.nginx.com/nginx-ic/nginx-plus-ingress:2.2.0 /nginx-ic/nginx-plus-ingress:2.2.0 + $ docker push /nginx-ic/nginx-plus-ingress:2.2.0 ``` or for NGINX App Protect enabled image ``` - $ docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.1.2 /nginx-ic-nap/nginx-plus-ingress:2.1.2 - $ docker push /nginx-ic-nap/nginx-plus-ingress:2.1.2 + $ docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:2.2.0 /nginx-ic-nap/nginx-plus-ingress:2.2.0 + $ docker push /nginx-ic-nap/nginx-plus-ingress:2.2.0 ``` diff --git a/docs/content/installation/using-the-jwt-token-docker-secret.md b/docs/content/installation/using-the-jwt-token-docker-secret.md index 9188fdd63a..5ba1c959df 100644 --- a/docs/content/installation/using-the-jwt-token-docker-secret.md +++ b/docs/content/installation/using-the-jwt-token-docker-secret.md @@ -42,10 +42,10 @@ This document explains how to use the NGINX Plus Ingress Controller image from t { "name": "nginx-ic/nginx-plus-ingress", "tags": [ - "2.1.2-alpine", - "2.1.2-ot", - "2.1.2-ubi", - "2.1.2" + "2.2.0-alpine", + "2.2.0-ot", + "2.2.0-ubi", + "2.2.0" ] } @@ -53,8 +53,8 @@ This document explains how to use the NGINX Plus Ingress Controller image from t { "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ - "2.1.2-ubi", - "2.1.2" + "2.2.0-ubi", + "2.2.0" ] } ``` diff --git a/docs/content/intro/nginx-ingress-controllers.md b/docs/content/intro/nginx-ingress-controllers.md index 293271fa12..28f65d0e73 100644 --- a/docs/content/intro/nginx-ingress-controllers.md +++ b/docs/content/intro/nginx-ingress-controllers.md @@ -29,11 +29,11 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres | NGINX version | [Custom](https://github.com/kubernetes/ingress-nginx/tree/main/images/nginx) NGINX build that includes several third-party modules | NGINX official mainline [build](https://github.com/nginxinc/docker-nginx) | NGINX Plus | | Commercial support | N/A | N/A | Included | | **Load balancing configuration via the Ingress resource** | -| Merging Ingress rules with the same host | Supported | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/mergeable-ingress-types) | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/mergeable-ingress-types) | +| Merging Ingress rules with the same host | Supported | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/mergeable-ingress-types) | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/mergeable-ingress-types) | | HTTP load balancing extensions - Annotations | See the [supported annotations](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/) | See the [supported annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/) | See the [supported annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/)| | HTTP load balancing extensions -- ConfigMap | See the [supported ConfigMap keys](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/) | See the [supported ConfigMap keys](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) | See the [supported ConfigMap keys](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) | | TCP/UDP | Supported via a ConfigMap | Supported via custom resources | Supported via custom resources | -| Websocket | Supported | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/websocket) | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/websocket) | +| Websocket | Supported | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/websocket) | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/websocket) | | TCP SSL Passthrough | Supported via a ConfigMap | Supported via custom resources | Supported via custom resources | | JWT validation | Not supported | Not supported | Supported | | Session persistence | Supported via a third-party module | Not supported | Supported | diff --git a/docs/content/intro/nginx-plus.md b/docs/content/intro/nginx-plus.md index 33c0951794..fefa7ffad1 100644 --- a/docs/content/intro/nginx-plus.md +++ b/docs/content/intro/nginx-plus.md @@ -18,9 +18,9 @@ Below are the key characteristics that NGINX Plus brings on top of NGINX into th * *Real-time metrics* A number metrics about how NGINX Plus and applications are performing are available through the API or a [built-in dashboard](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/status-page/). Optionally, the metrics can be exported to [Prometheus](https://docs.nginx.com/nginx-ingress-controller/logging-and-monitoring/prometheus/). * *Additional load balancing methods*. The following additional methods are available: `least_time` and `random two least_time` and their derivatives. See the [documentation](https://nginx.org/en/docs/http/ngx_http_upstream_module.html) for the complete list of load balancing methods. -* *Session persistence* The *sticky cookie* method is available. See the [Session Persistence](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/session-persistence) example. -* *Active health checks*. See the [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/health-checks) example. -* *JWT validation*. See the [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.1.2/examples/jwt) example. +* *Session persistence* The *sticky cookie* method is available. See the [Session Persistence](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/session-persistence) example. +* *Active health checks*. See the [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks) example. +* *JWT validation*. See the [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt) example. See [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) and [Annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/) doc for the complete list of available NGINX Plus features. Note that such features are configured through annotations that start with `nginx.com`, for example, `nginx.com/health-checks`. diff --git a/docs/content/releases.md b/docs/content/releases.md index 578c98f6bd..7b09e317fe 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -7,6 +7,36 @@ toc: true docs: "DOCS-616" --- +## NGINX Ingress Controller 2.2.0 + +12 Apr 2022 + +FEATURES: +* [2576](https://github.com/nginxinc/kubernetes-ingress/pull/2576) Add support for IPv6. +* [2572](https://github.com/nginxinc/kubernetes-ingress/pull/2572) Automate provisioning of Certificate resources for VirtualServer resources using cert-manager. + +ENHANCEMENTS: +* [2346](https://github.com/nginxinc/kubernetes-ingress/pull/2346) Use os.ReadDir for lightweight directory reading. Thanks to [Eng Zer Jun](https://github.com/Juneezee). +* [2360](https://github.com/nginxinc/kubernetes-ingress/pull/2360) Add NGINX App Protect reconnect period directive. +* [2479](https://github.com/nginxinc/kubernetes-ingress/pull/2479) Add cli argument to configure NGINX App Protect log level. +* [2455](https://github.com/nginxinc/kubernetes-ingress/pull/2455) Increase memory available for NGINX App Protect xml parser. + +CHANGES: +* [2580](https://github.com/nginxinc/kubernetes-ingress/pull/2580) Create -enable-oidc command line argument for OIDC policy. +* [2566](https://github.com/nginxinc/kubernetes-ingress/pull/2566) Unbind policy from preview policies. + +FIXES: +* [2378](https://github.com/nginxinc/kubernetes-ingress/pull/2378) Fix healthcheck ports. +* [2404](https://github.com/nginxinc/kubernetes-ingress/pull/2404) Start nginx with -e stderr parameter. +* [2414](https://github.com/nginxinc/kubernetes-ingress/pull/2414) Fix in file nginx-plus.virtualserver.tmpl ApDosMonitor->ApDosMonitorURI. + +HELM CHART: +* [2525](https://github.com/nginxinc/kubernetes-ingress/pull/2525) Extend helm chart to include NGINX Service Mesh fields. +* [2294](https://github.com/nginxinc/kubernetes-ingress/pull/2294) Add extra containers to helm chart. Thanks to [Márk Sági-Kazár](https://github.com/sagikazarmark). + + +For a complete list of changes, upgrade instructions and resources, see the [NGINX Ingress Controller Release Notes](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.0.0). + ## NGINX Ingress Controller 2.1.2 29 Mar 2022 diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 5a2e80e109..3736d3e051 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -22,9 +22,10 @@ We explicitly test the NGINX Ingress Controller (NIC) on a range of Kubernetes p {{% table %}} | NIC Version | Supported Kubernetes Version | NIC Helm Chart Version | NIC Operator Version | NGINX / NGINX Plus version | | --- | --- | --- | --- | --- | +| 2.2.0 | 1.23 - 1.19 | 0.13.0 | 0.6.0 | 1.21.6 / R26 | | 2.1.2 | 1.23 - 1.19 | 0.12.1 | 0.5.1 | 1.21.6 / R26 | | 2.0.3 | 1.22 - 1.19 | 0.11.3 | 0.4.0 | 1.21.3 / R25 | -| 1.12.3 | 1.21 - 1.16 | 0.10.3 | 0.3.0 | 1.21.0 / R24 | +| 1.12.4 | 1.21 - 1.16 | 0.10.4 | 0.3.0 | 1.21.6 / R26 | | 1.11.3 | 1.20 - 1.16 | 0.9.0 | 0.2.0 | 1.21.0 / R23 P1 | | 1.10.1 | 1.19 - 1.16 | 0.8.0 | 0.1.0 | 1.19.8 / R23 | | 1.9.1 | 1.18 - 1.16 | 0.7.1 | 0.0.7 | 1.19.3 / R22 | @@ -43,11 +44,11 @@ All images include NGINX 1.21.6. {{% table %}} |Name | Base image | Third-party modules | DockerHub image | Architectures | | ---| ---| ---| --- | --- | -|Alpine-based image | ``nginx:1.21.6-alpine``, which is based on ``alpine:3.15`` | | ``nginx/nginx-ingress:2.1.2-alpine`` | arm/v7, arm64, amd64, ppc64le, s390x | -|Alpine-based image with OpenTracing | ``nginx:1.21.6-alpine``, which is based on ``alpine:3.15`` | NGINX OpenTracing module, OpenTracing library, OpenTracing tracers for Jaeger, Zipkin and Datadog | ``nginx/nginx-ingress:2.1.2-alpine-ot`` | arm/v7, arm64, amd64, ppc64le, s390x | -|Debian-based image | ``nginx:1.21.6``, which is based on ``debian:bullseye-slim`` | | ``nginx/nginx-ingress:2.1.2`` | arm/v7, arm64, amd64, ppc64le, s390x | -|Debian-based image with OpenTracing | ``nginx:1.21.6``, which is based on ``debian:bullseye-slim`` | NGINX OpenTracing module, OpenTracing library, OpenTracing tracers for Jaeger, Zipkin and Datadog | ``nginx/nginx-ingress:2.1.2-ot`` | arm/v7, arm64, amd64, ppc64le, s390x | -|Ubi-based image | ``redhat/ubi8`` | | ``nginx/nginx-ingress:2.1.2-ubi`` | arm64, amd64, s390x | +|Alpine-based image | ``nginx:1.21.6-alpine``, which is based on ``alpine:3.15`` | | ``nginx/nginx-ingress:2.2.0-alpine`` | arm/v7, arm64, amd64, ppc64le, s390x | +|Alpine-based image with OpenTracing | ``nginx:1.21.6-alpine``, which is based on ``alpine:3.15`` | NGINX OpenTracing module, OpenTracing library, OpenTracing tracers for Jaeger, Zipkin and Datadog | ``nginx/nginx-ingress:2.2.0-alpine-ot`` | arm/v7, arm64, amd64, ppc64le, s390x | +|Debian-based image | ``nginx:1.21.6``, which is based on ``debian:bullseye-slim`` | | ``nginx/nginx-ingress:2.2.0`` | arm/v7, arm64, amd64, ppc64le, s390x | +|Debian-based image with OpenTracing | ``nginx:1.21.6``, which is based on ``debian:bullseye-slim`` | NGINX OpenTracing module, OpenTracing library, OpenTracing tracers for Jaeger, Zipkin and Datadog | ``nginx/nginx-ingress:2.2.0-ot`` | arm/v7, arm64, amd64, ppc64le, s390x | +|Ubi-based image | ``redhat/ubi8`` | | ``nginx/nginx-ingress:2.2.0-ubi`` | arm64, amd64, s390x | {{% /table %}} ### Images with NGINX Plus @@ -59,14 +60,14 @@ NGINX Plus images are available through the F5 Container registry `private-regis {{% table %}} |Name | Base image | Third-party modules | F5 Container Registry Image | Architectures | | ---| ---| --- | --- | --- | -|Alpine-based image | ``alpine:3.15`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.1.2-alpine` | arm64, amd64 | -|Debian-based image | ``debian:bullseye-slim`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.1.2` | arm64, amd64 | -|Debian-based image with OpenTracing | ``debian:bullseye-slim`` | NGINX Plus OpenTracing module, OpenTracing tracers for Jaeger, Zipkin and Datadog; NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.1.2-ot` | arm64, amd64 | -|Debian-based image with App Protect WAF| ``debian:buster-slim`` | NGINX Plus App Protect WAF module; NGINX Plus JavaScript module | `nginx-ic-nap/nginx-plus-ingress:2.1.2` | amd64 | +|Alpine-based image | ``alpine:3.15`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.2.0-alpine` | arm64, amd64 | +|Debian-based image | ``debian:bullseye-slim`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.2.0` | arm64, amd64 | +|Debian-based image with OpenTracing | ``debian:bullseye-slim`` | NGINX Plus OpenTracing module, OpenTracing tracers for Jaeger, Zipkin and Datadog; NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.2.0-ot` | arm64, amd64 | +|Debian-based image with App Protect WAF| ``debian:buster-slim`` | NGINX Plus App Protect WAF module; NGINX Plus JavaScript module | `nginx-ic-nap/nginx-plus-ingress:2.2.0` | amd64 | |Debian-based image with App Protect DoS | ``debian:buster-slim`` | NGINX Plus App Protect DoS module; NGINX Plus JavaScript module | | amd64 | |Debian-based image with App Protect WAF and DoS | ``debian:buster-slim`` | NGINX Plus App Protect WAF and DoS modules; NGINX Plus JavaScript module | | amd64 | -|Ubi-based image | ``redhat/ubi8`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.1.2-ubi` | arm64, amd64, s390x | -|Ubi-based image with App Protect WAF | ``redhat/ubi8`` | NGINX Plus App Protect WAF module; NGINX Plus JavaScript module | `nginx-ic-nap/nginx-plus-ingress:2.1.2-ubi` | amd64 | +|Ubi-based image | ``redhat/ubi8`` | NGINX Plus JavaScript module | `nginx-ic/nginx-plus-ingress:2.2.0-ubi` | arm64, amd64, s390x | +|Ubi-based image with App Protect WAF | ``redhat/ubi8`` | NGINX Plus App Protect WAF module; NGINX Plus JavaScript module | `nginx-ic-nap/nginx-plus-ingress:2.2.0-ubi` | amd64 | |Ubi-based image with App Protect DoS | ``redhat/ubi8`` | NGINX Plus App Protect DoS module; NGINX Plus JavaScript module | | amd64 | |Ubi-based image with App Protect WAF and DoS | ``redhat/ubi8`` | NGINX Plus App Protect WAF and DoS modules; NGINX Plus JavaScript module | | amd64 | {{% /table %}} From 90d49e452825d081893bef4f882d26edf76102f0 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 09:01:27 -0700 Subject: [PATCH 02/10] Update docs/content/releases.md Co-authored-by: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> --- docs/content/releases.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/content/releases.md b/docs/content/releases.md index 7b09e317fe..3d7fe239c6 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -11,6 +11,16 @@ docs: "DOCS-616" 12 Apr 2022 +OVERVIEW: + +* Support for automatic provisioning and management of Certificate resources for VirtualServer resources using [cert-manager](https://cert-manager.io/docs/). Examples for configuring cert-manager with NGINX Ingress Controller can be found [here](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/certmanager). Please note that ACME type Issuers are not yet supported for use with VirtualServer resources. + +* Full support for IPv6 using the NGINX Ingress Controller [VirtualServer and VirtualServerRoute](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources) custom resources, and Ingress resources. + +* The [-enable-preview-policies](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#-enable-preview-policies) cli argument has been deprecated and is no longer required for the usage of any Policy resource type. This argument will be removed completely in v2.6.0. + +* A new [-enable-oidc](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#-enable-oidc) cli argument has been added to enable OIDC policies. Previously, this behaviour was achieved through the usage of the `-enable-preview-policies` cli argument. + FEATURES: * [2576](https://github.com/nginxinc/kubernetes-ingress/pull/2576) Add support for IPv6. * [2572](https://github.com/nginxinc/kubernetes-ingress/pull/2572) Automate provisioning of Certificate resources for VirtualServer resources using cert-manager. From 3f3b9ca50048e30ef6c210d2bc6a62d245794a8d Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 09:17:17 -0700 Subject: [PATCH 03/10] Update README.md Co-authored-by: Brian Ehlert --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cb6fa65d05..56b7ba199d 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,9 @@ Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus We publish Ingress controller releases on GitHub. See our [releases page](https://github.com/nginxinc/kubernetes-ingress/releases). -The latest stable release is [2.2.0](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0). For production use, we recommend that you choose the latest stable release. As an alternative, you can choose the *edge* version built from the [latest commit](https://github.com/nginxinc/kubernetes-ingress/commits/main) from the main branch. The edge version is useful for experimenting with new features that are not yet published in a stable release. +The latest stable release is [2.2.0](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0). For production use, we recommend that you choose the latest stable release. + +The edge version is useful for experimenting with new features that are not yet published in a stable release. To use, choose the *edge* version built from the [latest commit](https://github.com/nginxinc/kubernetes-ingress/commits/main) from the main branch. To use the Ingress controller, you need to have access to: * An Ingress controller image. From 0e4a295fe03f300969642a326f16b3f524acee84 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 09:44:21 -0700 Subject: [PATCH 04/10] Update docs/content/releases.md Co-authored-by: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> --- docs/content/releases.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/content/releases.md b/docs/content/releases.md index 3d7fe239c6..ce26c0e675 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -45,7 +45,16 @@ HELM CHART: * [2294](https://github.com/nginxinc/kubernetes-ingress/pull/2294) Add extra containers to helm chart. Thanks to [Márk Sági-Kazár](https://github.com/sagikazarmark). -For a complete list of changes, upgrade instructions and resources, see the [NGINX Ingress Controller Release Notes](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.0.0). +UPGRADE: +* For NGINX, use the 2.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=2.1.0), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress). +* For NGINX Plus, use the 2.2.0 images from the F5 Container registry or build your own image using the 2.2.0 source code. +* For Helm, use version 0.13.0 of the chart. If you're using custom resources like VirtualServer and TransportServer (`controller.enableCustomResources` is set to `true`), after you run the `helm upgrade` command, the CRDs will not be upgraded. After running the `helm upgrade` command, run `kubectl apply -f deployments/helm-chart/crds` to upgrade the CRDs. +* When upgrading using the [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), make sure to update the [ClusterRole](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/deployments/rbac/rbac.yaml). This is required to enable the cert-manager for VirtualServer resources integration. +* The -enable-preview-policies cli argument has been deprecated, and is no longer required for any Policy resources. +* Enabling OIDC Policies now requires the use of -enable-oidc cli argument instead of the -enable-preview-policies cli argument. + +SUPPORTED PLATFORMS: +We will provide technical support for the NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider and which passes the Kubernetes conformance tests. This release was fully tested on the following Kubernetes versions: 1.19-1.23. ## NGINX Ingress Controller 2.1.2 From 69a90144280322105605beedeb8a1bb44e3f2a6f Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 09:55:21 -0700 Subject: [PATCH 05/10] Update docs/content/releases.md Co-authored-by: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> --- docs/content/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/releases.md b/docs/content/releases.md index ce26c0e675..9f786b9577 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -46,7 +46,7 @@ HELM CHART: UPGRADE: -* For NGINX, use the 2.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=2.1.0), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress). +* For NGINX, use the 2.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=2.2.0), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress). * For NGINX Plus, use the 2.2.0 images from the F5 Container registry or build your own image using the 2.2.0 source code. * For Helm, use version 0.13.0 of the chart. If you're using custom resources like VirtualServer and TransportServer (`controller.enableCustomResources` is set to `true`), after you run the `helm upgrade` command, the CRDs will not be upgraded. After running the `helm upgrade` command, run `kubectl apply -f deployments/helm-chart/crds` to upgrade the CRDs. * When upgrading using the [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/), make sure to update the [ClusterRole](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/deployments/rbac/rbac.yaml). This is required to enable the cert-manager for VirtualServer resources integration. From bb2c898d9117468e025d69a7f00d4a1b9a9a7c71 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 09:55:30 -0700 Subject: [PATCH 06/10] Update docs/content/releases.md Co-authored-by: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> --- docs/content/releases.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/content/releases.md b/docs/content/releases.md index 9f786b9577..3de06ea249 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -43,8 +43,6 @@ FIXES: HELM CHART: * [2525](https://github.com/nginxinc/kubernetes-ingress/pull/2525) Extend helm chart to include NGINX Service Mesh fields. * [2294](https://github.com/nginxinc/kubernetes-ingress/pull/2294) Add extra containers to helm chart. Thanks to [Márk Sági-Kazár](https://github.com/sagikazarmark). - - UPGRADE: * For NGINX, use the 2.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=2.2.0), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress). * For NGINX Plus, use the 2.2.0 images from the F5 Container registry or build your own image using the 2.2.0 source code. From 017f5cfe7409846a2246bfe3ef0a4fa2e23005e8 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 10:04:35 -0700 Subject: [PATCH 07/10] add change to makefile --- docs/content/releases.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/content/releases.md b/docs/content/releases.md index 3de06ea249..53ce326bf7 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -15,17 +15,17 @@ OVERVIEW: * Support for automatic provisioning and management of Certificate resources for VirtualServer resources using [cert-manager](https://cert-manager.io/docs/). Examples for configuring cert-manager with NGINX Ingress Controller can be found [here](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/certmanager). Please note that ACME type Issuers are not yet supported for use with VirtualServer resources. -* Full support for IPv6 using the NGINX Ingress Controller [VirtualServer and VirtualServerRoute](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources) custom resources, and Ingress resources. +* Full support for IPv6 using the NGINX Ingress Controller [VirtualServer and VirtualServerRoute](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources) custom resources, and Ingress resources. * The [-enable-preview-policies](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#-enable-preview-policies) cli argument has been deprecated and is no longer required for the usage of any Policy resource type. This argument will be removed completely in v2.6.0. -* A new [-enable-oidc](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#-enable-oidc) cli argument has been added to enable OIDC policies. Previously, this behaviour was achieved through the usage of the `-enable-preview-policies` cli argument. +* A new [-enable-oidc](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#-enable-oidc) cli argument has been added to enable OIDC policies. Previously, this behaviour was achieved through the usage of the `-enable-preview-policies` cli argument. FEATURES: * [2576](https://github.com/nginxinc/kubernetes-ingress/pull/2576) Add support for IPv6. * [2572](https://github.com/nginxinc/kubernetes-ingress/pull/2572) Automate provisioning of Certificate resources for VirtualServer resources using cert-manager. -ENHANCEMENTS: +IMPROVEMENTS: * [2346](https://github.com/nginxinc/kubernetes-ingress/pull/2346) Use os.ReadDir for lightweight directory reading. Thanks to [Eng Zer Jun](https://github.com/Juneezee). * [2360](https://github.com/nginxinc/kubernetes-ingress/pull/2360) Add NGINX App Protect reconnect period directive. * [2479](https://github.com/nginxinc/kubernetes-ingress/pull/2479) Add cli argument to configure NGINX App Protect log level. @@ -34,6 +34,7 @@ ENHANCEMENTS: CHANGES: * [2580](https://github.com/nginxinc/kubernetes-ingress/pull/2580) Create -enable-oidc command line argument for OIDC policy. * [2566](https://github.com/nginxinc/kubernetes-ingress/pull/2566) Unbind policy from preview policies. +* [2582](https://github.com/nginxinc/kubernetes-ingress/pull/2582) Rename Make targets from `openshift` to `ubi`. FIXES: * [2378](https://github.com/nginxinc/kubernetes-ingress/pull/2378) Fix healthcheck ports. From 48c0d931d7da5378c645863f834701f98321b668 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 10:43:44 -0700 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Jodie Putrino --- CHANGELOG.md | 2 +- deployments/helm-chart/README.md | 2 +- .../installation-with-helm-dos-arbitrator.md | 2 +- .../global-configuration/configmap-resource.md | 2 +- .../advanced-configuration-with-annotations.md | 8 ++++---- .../ingress-resources/basic-configuration.md | 2 +- .../ingress-resources/cross-namespace-configuration.md | 4 ++-- docs/content/configuration/policy-resource.md | 3 ++- .../virtualserver-and-virtualserverroute-resources.md | 2 +- docs/content/installation/installation-with-helm.md | 2 +- docs/content/installation/installation-with-operator.md | 4 +++- 11 files changed, 18 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 09351ff860..cee3df9cf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ An automatically generated list of changes can be found on Github at: [2.2.0 Release](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0) -A curated list of changes can be found in the [Releases](http://docs.nginx.com/nginx-ingress-controller/releases/) page on NGINX Documentation website. +A curated list of changes can be found on the [Releases](http://docs.nginx.com/nginx-ingress-controller/releases/) page on the NGINX Documentation website. ### 2.1.2 diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index 1b236cf275..bfe4067a8b 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -156,7 +156,7 @@ Parameter | Description | Default `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. | 1 `controller.image.repository` | The image repository of the Ingress controller. | nginx/nginx-ingress -`controller.image.tag` | The tag of the Ingress controller image. | 2.2.0 +`controller.image.tag` | The tag of the Ingress Controller image. | 2.2.0 `controller.image.pullPolicy` | The pull policy for the Ingress controller image. | IfNotPresent `controller.config.name` | The name of the ConfigMap used by the Ingress controller. | Autogenerated `controller.config.annotations` | The annotations of the Ingress controller configmap. | {} diff --git a/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md b/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md index ed2f754a3a..276f9fb582 100644 --- a/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md +++ b/docs/content/app-protect-dos/installation-with-helm-dos-arbitrator.md @@ -17,7 +17,7 @@ docs: "DOCS-582" This step is required if you're installing the chart using its sources. Additionally, the step is also required for managing the custom resource definitions (CRDs), which the Ingress Controller requires by default, or for upgrading/deleting the CRDs. -1. Clone the Ingress controller repo: +1. Clone the Ingress Controller repo: ```console $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index 4572305ddc..4a66565228 100644 --- a/docs/content/configuration/global-configuration/configmap-resource.md +++ b/docs/content/configuration/global-configuration/configmap-resource.md @@ -86,7 +86,7 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres |``worker-shutdown-timeout`` | Sets the value of the [worker_shutdown_timeout](https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout) directive. | N/A | | |``server-names-hash-bucket-size`` | Sets the value of the [server_names_hash_bucket_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | ``256`` | | |``server-names-hash-max-size`` | Sets the value of the [server_names_hash_max_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | ``1024`` | | -|``resolver-addresses`` | Sets the value of the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) addresses. Note: If you use a DNS name (ex., ``kube-dns.kube-system.svc.cluster.local`` ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. As a consequence, If the name cannot be resolved or the DNS server doesn't respond, NGINX Plus will fail to start or reload. To avoid this, consider using only IP addresses as resolver addresses. Supported in NGINX Plus only. | N/A | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | +|``resolver-addresses`` | Sets the value of the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) addresses. Note: If you use a DNS name (for example, ``kube-dns.kube-system.svc.cluster.local`` ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. If the name cannot be resolved or the DNS server doesn't respond, NGINX Plus will fail to start or reload. To avoid this, we recommend using IP addresses as resolver addresses instead of DNS names. Supported in NGINX Plus only. | N/A | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | |``resolver-ipv6`` | Enables IPv6 resolution in the resolver. Supported in NGINX Plus only. | ``True`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | |``resolver-valid`` | Sets the time NGINX caches the resolved DNS records. Supported in NGINX Plus only. | TTL value of a DNS record | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | |``resolver-timeout`` | Sets the [resolver_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_timeout) for name resolution. Supported in NGINX Plus only. | ``30s`` | [Support for Type ExternalName Services](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/externalname-services). | diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md index 2d540a3a01..1b8276c0d7 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -150,7 +150,7 @@ The table below summarizes the available annotations. |``nginx.org/hsts-behind-proxy`` | ``hsts-behind-proxy`` | Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. | ``False`` | | |``nginx.com/jwt-key`` | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | |``nginx.com/jwt-realm`` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | -|``nginx.com/jwt-token`` | N/A | Specifies a variable that contains JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | +|``nginx.com/jwt-token`` | N/A | Specifies a variable that contains a JSON Web Token. | By default, a JWT is expected in the ``Authorization`` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | |``nginx.com/jwt-login-url`` | N/A | Specifies a URL to which a client is redirected in case of an invalid or missing JWT. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/jwt). | {{% /table %}} @@ -180,8 +180,8 @@ The table below summarizes the available annotations. |``nginx.org/keepalive`` | ``keepalive`` | Sets the value of the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. Note that ``proxy_set_header Connection "";`` is added to the generated configuration when the value > 0. | ``0`` | | |``nginx.com/health-checks`` | N/A | Enables active health checks. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | |``nginx.com/health-checks-mandatory`` | N/A | Configures active health checks as mandatory. | ``False`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | -|``nginx.com/health-checks-mandatory-queue`` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | ``0`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | -|``nginx.com/slow-start`` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly added servers, configure [mandatory active health checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | ``"0s"`` | | +|``nginx.com/health-checks-mandatory-queue`` | N/A | When active health checks are mandatory, creates a queue where incoming requests are temporarily stored while NGINX Plus is checking the health of the endpoints after a configuration reload. | ``0`` | [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | +|``nginx.com/slow-start`` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly-added servers, configure [mandatory active health checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/health-checks). | ``"0s"`` | | {{% /table %}} ### Snippets and Custom Templates @@ -204,7 +204,7 @@ The table below summarizes the available annotations. |``appprotect.f5.com/app-protect-enable`` | N/A | Enable App Protect for the Ingress Resource. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | |``appprotect.f5.com/app-protect-security-log-enable`` | N/A | Enable the [security log](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) for App Protect. | ``False`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | |``appprotect.f5.com/app-protect-security-log`` | N/A | The App Protect log configuration for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace as the Ingress Resource is used. If not specified the default is used which is: filter: ``illegal``, format: ``default``. Multiple configurations can be specified in a comma separated list. Both log configurations and destinations list (see below) must be of equal length. Configs and destinations are paired by the list indices. | N/A | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | -|``appprotect.f5.com/app-protect-security-log-destination`` | N/A | The destination of the security log. For more information check the [DESTINATION argument](/nginx-app-protect/troubleshooting/#app-protect-logging-overview). Multiple destinations can be specified in a coma separated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. | ``syslog:server=localhost:514`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | +|``appprotect.f5.com/app-protect-security-log-destination`` | N/A | The destination of the security log. For more information check the [DESTINATION argument](/nginx-app-protect/troubleshooting/#app-protect-logging-overview). Multiple destinations can be specified in a comma-separated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. | ``syslog:server=localhost:514`` | [Example for App Protect](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/appprotect). | {{% /table %}} ### App Protect DoS diff --git a/docs/content/configuration/ingress-resources/basic-configuration.md b/docs/content/configuration/ingress-resources/basic-configuration.md index fe37e89048..e0059a81f0 100644 --- a/docs/content/configuration/ingress-resources/basic-configuration.md +++ b/docs/content/configuration/ingress-resources/basic-configuration.md @@ -51,7 +51,7 @@ Here is a breakdown of what this Ingress resource definition means: * The rule with the path `/coffee` instructs NGINX to distribute the requests with the `/coffee` URI among the pods of the *coffee* service, which is deployed with the name `coffee‑svc` in the cluster. * Both rules instruct NGINX to distribute the requests to `port 80` of the corresponding service (the `servicePort` field). -> For complete instructions on deploying the Ingress and Secret resources in the cluster, see the [complete-example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/complete-example) in our GitHub repo. +> For complete instructions on deploying the Ingress and Secret resources in the cluster, see the [complete example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/complete-example) in our GitHub repo. > To learn more about the Ingress resource, see the [Ingress resource documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the Kubernetes docs. diff --git a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md index 3f75d41576..88c808f0d8 100644 --- a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md +++ b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md @@ -9,6 +9,6 @@ docs: "DOCS-594" --- -You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/mergeable-ingress-types) example on our GitHub. +You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/mergeable-ingress-types) example in our GitHub repo. -As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/cross-namespace-configuration) example on our GitHub. +As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/cross-namespace-configuration) example in our GitHub repo. diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index 1d26a47e67..91c72e2527 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -297,7 +297,8 @@ NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP #### Prerequisites -For the OIDC feature to work, it is necessary to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/), otherwise NGINX Plus will fail to reload. Additionally, it is necessary to configure a resolver, so that NGINX Plus can resolve the IDP authorization endpoint. For an example of the necessary configuration see the documentation [here](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). +In order to use OIDC, you need to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/). If you don't set up zone synchronization, NGINX Plus will fail to reload. +You also need to configure a resolver, which NGINX Plus will use to resolve the IDP authorization endpoint. You can find an example configuration [in our GitHub repo](https://github.com/nginxinc/kubernetes-ingress/blob/v2.2.0/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). > **Note**: The configuration in the example doesn't enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens. diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index a806c61bbd..1260dadf59 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -552,7 +552,7 @@ proxy: |``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | |``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | |``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | -|``rewritePath`` | The rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/rewrites) example. | ``string`` | No | +|``rewritePath`` | The rewritten URI. If the route path is a regular expression -- starts with `~` -- the `rewritePath` can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v2.2.0/examples/custom-resources/rewrites) example. | ``string`` | No | {{% /table %}} ### Action.Proxy.RequestHeaders diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index 42f37887a1..c888e3dea0 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -160,7 +160,7 @@ The following tables lists the configurable parameters of the NGINX Ingress cont |``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. | 1 | |``controller.image.repository`` | The image repository of the Ingress controller. | nginx/nginx-ingress | -|``controller.image.tag`` | The tag of the Ingress controller image. | 2.2.0 | +|``controller.image.tag`` | The tag of the Ingress Controller image. | 2.2.0 | |``controller.image.pullPolicy`` | The pull policy for the Ingress controller image. | IfNotPresent | |``controller.config.name`` | The name of the ConfigMap used by the Ingress controller. | Autogenerated | |``controller.config.entries`` | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) for the list of supported ConfigMap keys. | {} | diff --git a/docs/content/installation/installation-with-operator.md b/docs/content/installation/installation-with-operator.md index 61a36f9434..d984ff8d2f 100644 --- a/docs/content/installation/installation-with-operator.md +++ b/docs/content/installation/installation-with-operator.md @@ -8,7 +8,9 @@ toc: true docs: "DOCS-604" --- -**Note: an NGINX Ingress Operator version compatible with the 2.2.0 NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version.** +{{< note >}} +An NGINX Ingress Operator version compatible with the 2.2.0 NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version. +{{< /note >}} This document describes how to install the NGINX Ingress Controller in your Kubernetes cluster using the NGINX Ingress Operator. From 3c1bed4e4d0d93e7467c143b5967968396618148 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 10:52:18 -0700 Subject: [PATCH 09/10] Capitalize Controller everywhere --- CHANGELOG.md | 12 +-- README.md | 30 +++--- build/Dockerfile | 6 +- cmd/nginx-ingress/main.go | 22 ++--- deployments/README.md | 5 +- .../helm-chart-dos-arbitrator/README.md | 2 +- deployments/helm-chart/README.md | 94 +++++++++---------- deployments/helm-chart/values.yaml | 72 +++++++------- docs/content/app-protect-dos/installation.md | 6 +- .../command-line-arguments.md | 20 ++-- .../configmap-resource.md | 4 +- .../reporting-resources-status.md | 85 +++++++++-------- ...advanced-configuration-with-annotations.md | 4 +- docs/content/configuration/security.md | 2 +- ...server-and-virtualserverroute-resources.md | 4 +- .../installation/installation-with-helm.md | 84 ++++++++--------- .../installation-with-manifests.md | 36 +++---- .../installation-with-operator.md | 2 +- .../running-multiple-ingress-controllers.md | 8 +- .../using-aws-marketplace-image.md | 8 +- .../using-the-jwt-token-docker-secret.md | 2 +- .../intro/nginx-ingress-controllers.md | 14 +-- docs/content/intro/nginx-plus.md | 10 +- docs/content/intro/overview.md | 12 +-- .../logging-and-monitoring/prometheus.md | 2 +- .../logging-and-monitoring/status-page.md | 4 +- docs/content/releases.md | 1 + examples/appprotect-dos/README.md | 8 +- examples/appprotect/README.md | 8 +- examples/complete-example/README.md | 10 +- .../custom-resources/certmanager/README.md | 10 +- examples/custom-resources/dos/README.md | 4 +- examples/custom-resources/waf/README.md | 4 +- examples/custom-templates/README.md | 6 +- examples/grpc-services/README.md | 2 +- examples/health-checks/README.md | 6 +- examples/jwt/README.md | 2 +- examples/mergeable-ingress-types/README.md | 18 ++-- examples/proxy-protocol/README.md | 6 +- examples/rbac/README.md | 2 +- examples/session-persistence/README.md | 6 +- examples/tcp-udp/README.md | 23 +++-- examples/websocket/README.md | 2 +- 43 files changed, 332 insertions(+), 336 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cee3df9cf5..1a888105b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -937,7 +937,7 @@ UPGRADE: * [221](https://github.com/nginxinc/kubernetes-ingress/pull/221): Add git commit info to the IC log. * [220](https://github.com/nginxinc/kubernetes-ingress/pull/220): Update dependencies. * [213](https://github.com/nginxinc/kubernetes-ingress/pull/213): Add main snippets to allow Main context customization. Thanks to [Dewen Kong](https://github.com/kongdewen). -* [211](https://github.com/nginxinc/kubernetes-ingress/pull/211): Minimize the number of configuration reloads when the Ingress controller starts; fix a problem with endpoints updates for Plus. +* [211](https://github.com/nginxinc/kubernetes-ingress/pull/211): Minimize the number of configuration reloads when the Ingress Controller starts; fix a problem with endpoints updates for Plus. * [208](https://github.com/nginxinc/kubernetes-ingress/pull/208): Add worker-shutdown-timeout configmap key. Thanks to [Aleksandr Lysenko](https://github.com/Sarga). * [199](https://github.com/nginxinc/kubernetes-ingress/pull/199): Add support for Kubernetes ssl-redirect annotation. Thanks to [Luke Seelenbinder](https://github.com/lseelenbinder). * [194](https://github.com/nginxinc/kubernetes-ingress/pull/194) Add keepalive configmap key and annotation. @@ -952,18 +952,18 @@ UPGRADE: * [175](https://github.com/nginxinc/kubernetes-ingress/pull/175): Add support for JWT for NGINX Plus. * [171](https://github.com/nginxinc/kubernetes-ingress/pull/171): Allow NGINX to listen on non-standard ports. Thanks to [Stanislav Seletskiy](https://github.com/seletskiy). -* [170](https://github.com/nginxinc/kubernetes-ingress/pull/170): Add the default server. **Note**: The Ingress controller will fail to start if there are no cert and key for the default server. You can pass a TLS Secret for the default server as an argument to the Ingress controller or add a cert and a key to the Docker image. +* [170](https://github.com/nginxinc/kubernetes-ingress/pull/170): Add the default server. **Note**: The Ingress Controller will fail to start if there are no cert and key for the default server. You can pass a TLS Secret for the default server as an argument to the Ingress Controller or add a cert and a key to the Docker image. * [169](https://github.com/nginxinc/kubernetes-ingress/pull/169): Ignore Ingress resources with empty hostnames. * [168](https://github.com/nginxinc/kubernetes-ingress/pull/168): Add the `nginx.org/lb-method` annotation. Thanks to [Sajal Kayan](https://github.com/sajal). * [166](https://github.com/nginxinc/kubernetes-ingress/pull/166): Watch Secret resources for updates. **Note**: If a Secret referenced by one or more Ingress resources becomes invalid or gets removed, the configuration for those Ingress resources will be disabled until there is a valid Secret. * [160](https://github.com/nginxinc/kubernetes-ingress/pull/160): Add support for events. See the details [here](https://github.com/nginxinc/kubernetes-ingress/pull/160). -* [157](https://github.com/nginxinc/kubernetes-ingress/pull/157): Add graceful termination - when the Ingress controller receives `SIGTERM`, it shutdowns itself as well as NGINX, using `nginx -s quit`. +* [157](https://github.com/nginxinc/kubernetes-ingress/pull/157): Add graceful termination - when the Ingress Controller receives `SIGTERM`, it shutdowns itself as well as NGINX, using `nginx -s quit`. ### 0.9.0 * [156](https://github.com/nginxinc/kubernetes-ingress/pull/156): Write a pem file with an SSL certificate and key atomically. * [155](https://github.com/nginxinc/kubernetes-ingress/pull/155): Remove http2 annotation (http/2 can be enabled globally in the ConfigMap). -* [154](https://github.com/nginxinc/kubernetes-ingress/pull/154): Merge NGINX and NGINX Plus Ingress controller implementations. +* [154](https://github.com/nginxinc/kubernetes-ingress/pull/154): Merge NGINX and NGINX Plus Ingress Controller implementations. * [151](https://github.com/nginxinc/kubernetes-ingress/pull/151): Use k8s.io/client-go. * [146](https://github.com/nginxinc/kubernetes-ingress/pull/146): Fix health status. * [141](https://github.com/nginxinc/kubernetes-ingress/pull/141): Set `worker_processes` to `auto` in NGINX configuration. Thanks to [Andreas Krüger](https://github.com/woopstar). @@ -995,7 +995,7 @@ Fix the issue with single service Ingress resources without any Ingress rules: t * [88](https://github.com/nginxinc/kubernetes-ingress/pull/88): Support for the `proxy_hide_header` and the `proxy_pass_header` directives via annotations and in the configmap. Thanks to [Nico Schieder](https://github.com/thetechnick). * [85](https://github.com/nginxinc/kubernetes-ingress/pull/85): Add the configmap settings to support perfect forward secrecy. Thanks to [Nico Schieder](https://github.com/thetechnick). * [84](https://github.com/nginxinc/kubernetes-ingress/pull/84): Secret retry: If a certificate Secret referenced in an Ingress object is not found, -the Ingress controller will reject the Ingress object. but retries every 5s. Thanks to [Nico Schieder](https://github.com/thetechnick). +the Ingress Controller will reject the Ingress object. but retries every 5s. Thanks to [Nico Schieder](https://github.com/thetechnick). * [81](https://github.com/nginxinc/kubernetes-ingress/pull/81): Add configmap options to turn on the PROXY protocol. Thanks to [Nico Schieder](https://github.com/thetechnick). * Update NGINX version to 1.11.8. * Documentation fixes: [104](https://github.com/nginxinc/kubernetes-ingress/pull/104/files) and [97](https://github.com/nginxinc/kubernetes-ingress/pull/97/files). Thanks to [Ruilin Huang](https://github.com/hrl) and [Justin Garrison](https://github.com/rothgar). @@ -1027,4 +1027,4 @@ The previous version was 0.3 ### Notes -* Except when mentioned otherwise, the controller refers both to the NGINX and the NGINX Plus Ingress controllers. +* Except when mentioned otherwise, the controller refers both to the NGINX and the NGINX Plus Ingress Controllers. diff --git a/README.md b/README.md index 56b7ba199d..498a89326a 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ # NGINX Ingress Controller -This repo provides an implementation of an Ingress controller for NGINX and NGINX Plus. +This repo provides an implementation of an Ingress Controller for NGINX and NGINX Plus. -**Note**: this project is different from the NGINX Ingress controller in [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx) repo. See [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-ingress-controllers) to find out about the key differences. +**Note**: this project is different from the NGINX Ingress Controller in [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx) repo. See [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-ingress-controllers) to find out about the key differences. ## What is the Ingress? @@ -23,25 +23,25 @@ See the [Ingress User Guide](https://kubernetes.io/docs/user-guide/ingress/) to ## What is the Ingress Controller? -The Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer running externally. Different load balancers require different Ingress controller implementations. +The Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer running externally. Different load balancers require different Ingress Controller implementations. -In the case of NGINX, the Ingress controller is deployed in a pod along with the load balancer. +In the case of NGINX, the Ingress Controller is deployed in a pod along with the load balancer. ## NGINX Ingress Controller -NGINX Ingress controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination. +NGINX Ingress Controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination. -Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) and [Annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/) docs to learn more about the supported features and customization options. +Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress Controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) and [Annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/) docs to learn more about the supported features and customization options. -As an alternative to the Ingress, NGINX Ingress controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute resources doc](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/). +As an alternative to the Ingress, NGINX Ingress Controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute resources doc](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/). TCP, UDP and TLS Passthrough load balancing is also supported. See the [TransportServer resource doc](https://docs.nginx.com/nginx-ingress-controller/configuration/transportserver-resource/). -Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus) to learn more about NGINX Ingress controller with NGINX Plus. +Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus) to learn more about NGINX Ingress Controller with NGINX Plus. ## Getting Started -1. Install the NGINX Ingress controller using the Kubernetes [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or the [helm chart](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/). +1. Install the NGINX Ingress Controller using the Kubernetes [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or the [helm chart](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/). 1. Configure load balancing for a simple web application: * Use the Ingress resource. See the [Cafe example](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/complete-example). * Or the VirtualServer resource. See the [Basic configuration](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/basic-configuration) example. @@ -51,14 +51,14 @@ Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus ## NGINX Ingress Controller Releases -We publish Ingress controller releases on GitHub. See our [releases page](https://github.com/nginxinc/kubernetes-ingress/releases). +We publish Ingress Controller releases on GitHub. See our [releases page](https://github.com/nginxinc/kubernetes-ingress/releases). -The latest stable release is [2.2.0](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0). For production use, we recommend that you choose the latest stable release. +The latest stable release is [2.2.0](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v2.2.0). For production use, we recommend that you choose the latest stable release. The edge version is useful for experimenting with new features that are not yet published in a stable release. To use, choose the *edge* version built from the [latest commit](https://github.com/nginxinc/kubernetes-ingress/commits/main) from the main branch. -To use the Ingress controller, you need to have access to: -* An Ingress controller image. +To use the Ingress Controller, you need to have access to: +* An Ingress Controller image. * Installation manifests or a Helm chart. * Documentation and examples. @@ -73,7 +73,7 @@ The table below summarizes the options regarding the images, manifests, helm cha ## Contacts -We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress controller, please create an issue or send a pull request on Github. +We’d like to hear your feedback! If you have any suggestions or experience issues with our Ingress Controller, please create an issue or send a pull request on Github. You can contact us directly via [kubernetes@nginx.com](mailto:kubernetes@nginx.com). ## Contributing @@ -82,5 +82,5 @@ If you'd like to contribute to the project, please read our [Contributing guide] ## Support -For NGINX Plus customers NGINX Ingress controller (when used with NGINX Plus) is covered +For NGINX Plus customers NGINX Ingress Controller (when used with NGINX Plus) is covered by the support contract. diff --git a/build/Dockerfile b/build/Dockerfile index 70984944c0..41df93fa13 100644 --- a/build/Dockerfile +++ b/build/Dockerfile @@ -101,9 +101,9 @@ LABEL name="NGINX Ingress Controller" \ vendor="NGINX Inc" \ version="${IC_VERSION}" \ release="1" \ - summary="The Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ - description="The Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ - io.k8s.description="The NGINX Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ + summary="The Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ + description="The Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ + io.k8s.description="The NGINX Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources." \ io.openshift.tags="nginx,ingress-controller,ingress,controller,kubernetes,openshift" RUN dnf --nodocs install -y shadow-utils ca-certificates \ diff --git a/cmd/nginx-ingress/main.go b/cmd/nginx-ingress/main.go index 5830441cbb..0f1fd4de70 100644 --- a/cmd/nginx-ingress/main.go +++ b/cmd/nginx-ingress/main.go @@ -50,21 +50,21 @@ var ( healthStatus = flag.Bool("health-status", false, `Add a location based on the value of health-status-uri to the default server. The location responds with the 200 status code for any request. - Useful for external health-checking of the Ingress controller`) + Useful for external health-checking of the Ingress Controller`) healthStatusURI = flag.String("health-status-uri", "/nginx-health", `Sets the URI of health status location in the default server. Requires -health-status`) proxyURL = flag.String("proxy", "", `Use a proxy server to connect to Kubernetes API started by "kubectl proxy" command. For testing purposes only. - The Ingress controller does not start NGINX and does not write any generated NGINX configuration files to disk`) + The Ingress Controller does not start NGINX and does not write any generated NGINX configuration files to disk`) watchNamespace = flag.String("watch-namespace", api_v1.NamespaceAll, - `Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces`) + `Namespace to watch for Ingress resources. By default the Ingress Controller watches all namespaces`) nginxConfigMaps = flag.String("nginx-configmaps", "", `A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, - but the Ingress controller is not able to fetch it from Kubernetes API, the Ingress controller will fail to start. + but the Ingress Controller is not able to fetch it from Kubernetes API, the Ingress Controller will fail to start. Format: /`) nginxPlus = flag.Bool("nginx-plus", false, "Enable support for NGINX Plus") @@ -83,10 +83,10 @@ var ( appProtectDosMemory = flag.Int("app-protect-dos-memory", 0, "RAM memory size to consume in MB. Requires -nginx-plus and -enable-app-protect-dos.") ingressClass = flag.String("ingress-class", "nginx", - `A class of the Ingress controller. + `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 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.`) @@ -94,8 +94,8 @@ var ( `A Secret with a TLS certificate and key for TLS termination of the default server. Format: /. If not set, than the certificate and key in the file "/etc/nginx/secrets/default" are used. If "/etc/nginx/secrets/default" doesn't exist, the Ingress Controller will configure NGINX to reject TLS connections to the default server. - If a secret is set, but the Ingress controller is not able to fetch it from Kubernetes API or it is not set and the Ingress Controller - fails to read the file "/etc/nginx/secrets/default", the Ingress controller will fail to start.`) + If a secret is set, but the Ingress Controller is not able to fetch it from Kubernetes API or it is not set and the Ingress Controller + fails to read the file "/etc/nginx/secrets/default", the Ingress Controller will fail to start.`) versionFlag = flag.Bool("version", false, "Print the version, git-commit hash and build date and exit") @@ -115,7 +115,7 @@ var ( (default for NGINX "nginx.transportserver.tmpl"; default for NGINX Plus "nginx-plus.transportserver.tmpl")`) externalService = flag.String("external-service", "", - `Specifies the name of the service with the type LoadBalancer through which the Ingress controller pods are exposed externally. + `Specifies the name of the service with the type LoadBalancer through which the Ingress Controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. For Ingress resources only: Requires -report-ingress-status.`) ingressLink = flag.String("ingresslink", "", @@ -148,7 +148,7 @@ var ( wildcardTLSSecret = flag.String("wildcard-tls-secret", "", `A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified. Format: /. If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. - If the argument is set, but the Ingress controller is not able to fetch the Secret from Kubernetes API, the Ingress controller will fail to start.`) + If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start.`) enablePrometheusMetrics = flag.Bool("enable-prometheus-metrics", false, "Enable exposing NGINX or NGINX Plus metrics in the Prometheus format") @@ -210,7 +210,7 @@ func main() { fmt.Println(versionInfo) os.Exit(0) } - glog.Infof("Starting NGINX Ingress controller %v PlusFlag=%v", versionInfo, *nginxPlus) + glog.Infof("Starting NGINX Ingress Controller %v PlusFlag=%v", versionInfo, *nginxPlus) if startupCheckFn != nil { err := startupCheckFn() diff --git a/deployments/README.md b/deployments/README.md index 3dd6c97c78..813085d3b6 100644 --- a/deployments/README.md +++ b/deployments/README.md @@ -1,6 +1,3 @@ # Installation -This folder includes Kubernetes manifests for installing NGINX or NGINX Plus Ingress controller. Read the installation instructions [here](https://docs.nginx.com/nginx-ingress-controller/installation/). - - - +This folder includes Kubernetes manifests for installing NGINX or NGINX Plus Ingress Controller. Read the installation instructions [here](https://docs.nginx.com/nginx-ingress-controller/installation/). diff --git a/deployments/helm-chart-dos-arbitrator/README.md b/deployments/helm-chart-dos-arbitrator/README.md index 05567f1553..5c554cac92 100644 --- a/deployments/helm-chart-dos-arbitrator/README.md +++ b/deployments/helm-chart-dos-arbitrator/README.md @@ -14,7 +14,7 @@ This chart deploys the NGINX App Protect DoS Arbitrator in your Kubernetes clust This step is required if you're installing the chart using its sources. Additionally, the step is also required for managing the custom resource definitions (CRDs), which the Ingress Controller requires by default, or for upgrading/deleting the CRDs. -1. Clone the Ingress controller repo: +1. Clone the Ingress Controller repo: ```console $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index bfe4067a8b..b4eaf18b1a 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -2,7 +2,7 @@ ## Introduction -This chart deploys the NGINX Ingress controller in your Kubernetes cluster. +This chart deploys the NGINX Ingress Controller in your Kubernetes cluster. ## Prerequisites @@ -11,8 +11,8 @@ This chart deploys the NGINX Ingress controller in your Kubernetes cluster. - Git. - If you’d like to use NGINX Plus: - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` parameter. - - Alternatively, pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image). - - Alternatively, you can build an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image). + - Alternatively, pull an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image). + - Alternatively, you can build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image). - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. - If you’d like to use App Protect DoS, please install App Protect DoS Arbitrator helm chart. Make sure to install in the same namespace as the NGINX Ingress Controller. Note that if you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because it is not possible to install more than one Arbitrator in a single namespace. @@ -21,7 +21,7 @@ This chart deploys the NGINX Ingress controller in your Kubernetes cluster. This step is required if you're installing the chart using its sources. Additionally, the step is also required for managing the custom resource definitions (CRDs), which the Ingress Controller requires by default, or for upgrading/deleting the CRDs. -1. Clone the Ingress controller repo: +1. Clone the Ingress Controller repo: ```console $ git clone https://github.com/nginxinc/kubernetes-ingress --branch v2.2.0 ``` @@ -60,7 +60,7 @@ For NGINX: $ helm install my-release nginx-stable/nginx-ingress ``` -For NGINX Plus: (assuming you have pushed the Ingress controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) +For NGINX Plus: (assuming you have pushed the Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) ```console $ helm install my-release nginx-stable/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` @@ -83,9 +83,9 @@ $ helm install my-release -f values-plus.yaml . **Note**: If you want to use the experimental repository, replace the value in the `tag` field inside the yaml files with `edge`. -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. +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. -When deploying the Ingress controller, make sure to use your own TLS certificate and key for the default server rather than the default pre-generated ones. Read the [Configuration](#Configuration) section below to see how to configure a TLS certificate and key for the default server. Note that the default server returns the Not Found page with the 404 status code for all requests for domains for which there are no Ingress rules defined. +When deploying the Ingress Controller, make sure to use your own TLS certificate and key for the default server rather than the default pre-generated ones. Read the [Configuration](#Configuration) section below to see how to configure a TLS certificate and key for the default server. Note that the default server returns the Not Found page with the 404 status code for all requests for domains for which there are no Ingress rules defined. ## Upgrading the Chart @@ -144,22 +144,22 @@ See [running multiple ingress controllers](https://docs.nginx.com/nginx-ingress- ## Configuration -The following tables lists the configurable parameters of the NGINX Ingress controller chart and their default values. +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.nginxplus` | Deploys the Ingress controller for NGINX Plus. | false +`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.nginxplus` | Deploys the Ingress Controller for NGINX Plus. | false `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.hostNetwork` | Enables the Ingress Controller pods to use the host's network namespace. | false `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. | 1 -`controller.image.repository` | The image repository of the Ingress controller. | nginx/nginx-ingress +`controller.image.repository` | The image repository of the Ingress Controller. | nginx/nginx-ingress `controller.image.tag` | The tag of the Ingress Controller image. | 2.2.0 -`controller.image.pullPolicy` | The pull policy for the Ingress controller image. | IfNotPresent -`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.image.pullPolicy` | The pull policy for the Ingress Controller image. | IfNotPresent +`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.config.entries` | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) 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. If not specified, a pre-generated self-signed certificate is used. **Note:** It is recommended that you specify your own certificate. | A pre-generated self-signed certificate. @@ -168,19 +168,19 @@ Parameter | Description | Default `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.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.resources` | The resources of the Ingress controller pods. | {} -`controller.replicaCount` | The number of replicas of the Ingress controller deployment. | 1 -`controller.ingressClass` | 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.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.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.resources` | The resources of the Ingress Controller pods. | {} +`controller.replicaCount` | The number of replicas of the Ingress Controller deployment. | 1 +`controller.ingressClass` | 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.setAsDefaultIngress` | New Ingresses without an `"ingressClassName"` field specified will be assigned the class specified in `controller.ingressClass`. | false -`controller.watchNamespace` | Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces. | "" +`controller.watchNamespace` | Namespace to watch for Ingress resources. By default the Ingress Controller watches all namespaces. | "" `controller.enableCustomResources` | Enable the custom resources. | true `controller.enablePreviewPolicies` | Enable preview policies. This parameter is deprecated. To enable OIDC Policies please use `controller.enableOIDC` instead. | false `controller.enableOIDC` | Enable OIDC policies. | false @@ -189,34 +189,34 @@ Parameter | Description | Default `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.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 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 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.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 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.externalIPs` | The list of external IPs for the Ingress Controller service. | [] `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 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.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 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.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.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 Ingress Controller service. | 443 +`controller.serviceAccount.name` | The name of the service account of the 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.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.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.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 @@ -238,8 +238,8 @@ Parameter | Description | Default `prometheus.scheme` | Configures the HTTP scheme to use for connections to the Prometheus endpoint. | http `prometheus.secret` | The namespace / name of a Kubernetes TLS Secret. If specified, this secret is used to secure the Prometheus endpoint with TLS connections. | "" `nginxServiceMesh.enable` | Enable integration with NGINX Service Mesh. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/) 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](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/#enabling-egress) for more details. Requires `nginxServiceMesh.enable`. | false +`nginxServiceMesh.enableEgress` | Enable NGINX Service Mesh workloads to route egress traffic through the Ingress Controller. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/#enabling-egress) for more details. Requires `nginxServiceMesh.enable`. | false ## Notes -* The values-icp.yaml file is used for deploying the Ingress controller on IBM Cloud Private. See the [blog post](https://www.nginx.com/blog/nginx-ingress-controller-ibm-cloud-private/) for more details. -* The values-nsm.yaml file is used for deploying the Ingress controller with NGINX Service Mesh. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/) for more details. +* The values-icp.yaml file is used for deploying the Ingress Controller on IBM Cloud Private. See the [blog post](https://www.nginx.com/blog/nginx-ingress-controller-ibm-cloud-private/) for more details. +* The values-nsm.yaml file is used for deploying the Ingress Controller with NGINX Service Mesh. See the NGINX Service Mesh [docs](https://docs.nginx.com/nginx-service-mesh/tutorials/kic/deploy-with-kic/) for more details. diff --git a/deployments/helm-chart/values.yaml b/deployments/helm-chart/values.yaml index 04bcef7534..3dce340510 100644 --- a/deployments/helm-chart/values.yaml +++ b/deployments/helm-chart/values.yaml @@ -1,12 +1,12 @@ controller: - ## The name of the Ingress controller daemonset or deployment. + ## The name of the Ingress Controller daemonset or deployment. ## Autogenerated if not set or set to "". # name: nginx-ingress - ## The kind of the Ingress controller installation - deployment or daemonset. + ## The kind of the Ingress Controller installation - deployment or daemonset. kind: deployment - ## Deploys the Ingress controller for NGINX Plus. + ## Deploys the Ingress Controller for NGINX Plus. nginxplus: false # Timeout in milliseconds which the Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. @@ -32,7 +32,7 @@ controller: ## RAM memory size to consume in MB. memory: 0 - ## Enables the Ingress controller pods to use the host's network namespace. + ## Enables the Ingress Controller pods to use the host's network namespace. hostNetwork: false ## Enables debugging for NGINX. Uses the nginx-debug binary. Requires error-log-level: debug in the ConfigMap via `controller.config.entries`. @@ -45,17 +45,17 @@ controller: customPorts: [] image: - ## The image repository of the Ingress controller. + ## The image repository of the Ingress Controller. repository: nginx/nginx-ingress - ## The tag of the Ingress controller image. + ## The tag of the Ingress Controller image. tag: "2.2.0" - ## The pull policy for the Ingress controller image. + ## The pull policy for the Ingress Controller image. pullPolicy: IfNotPresent config: - ## The name of the ConfigMap used by the Ingress controller. + ## The name of the ConfigMap used by the Ingress Controller. ## Autogenerated if not set or set to "". # name: nginx-config @@ -96,13 +96,13 @@ controller: ## Format: / secret: - ## The node selector for pod assignment for the Ingress controller pods. + ## The node selector for pod assignment for the Ingress Controller pods. nodeSelector: {} - ## The termination grace period of the Ingress controller pod. + ## The termination grace period of the Ingress Controller pod. terminationGracePeriodSeconds: 30 - ## The resources of the Ingress controller pods. + ## The resources of the Ingress Controller pods. resources: {} # limits: # cpu: 100m @@ -111,44 +111,44 @@ controller: # cpu: 100m # memory: 64Mi - ## The tolerations of the Ingress controller pods. + ## The tolerations of the Ingress Controller pods. tolerations: [] - ## The affinity of the Ingress controller pods. + ## The affinity of the Ingress Controller pods. affinity: {} - ## The volumes of the Ingress controller pods. + ## The volumes of the Ingress Controller pods. volumes: [] # - name: extra-conf # configMap: # name: extra-conf - ## The volumeMounts of the Ingress controller pods. + ## The volumeMounts of the Ingress Controller pods. volumeMounts: [] # - name: extra-conf # mountPath: /etc/nginx/conf.d/extra.conf # subPath: extra.conf - ## InitContainers for the Ingress controller pods. + ## InitContainers for the Ingress Controller pods. initContainers: [] # - name: init-container # image: busybox:1.34 # command: ['sh', '-c', 'echo this is initial setup!'] - ## Extra containers for the Ingress controller pods. + ## Extra containers for the Ingress Controller pods. extraContainers: [] # - name: container # image: busybox:1.34 # command: ['sh', '-c', 'echo this is a sidecar!'] - ## The number of replicas of the Ingress controller deployment. + ## The number of replicas of the Ingress Controller deployment. replicaCount: 1 - ## A class of the Ingress controller. + ## A class of the Ingress Controller. ## 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 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 resources that do not have the "ingressClassName" field for all versions of kubernetes. ingressClass: nginx @@ -156,7 +156,7 @@ controller: ## New Ingresses without an ingressClassName field specified will be assigned the class specified in `controller.ingressClass`. setAsDefaultIngress: false - ## Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces. + ## Namespace to watch for Ingress resources. By default the Ingress Controller watches all namespaces. watchNamespace: "" ## Enable the custom resources. @@ -192,7 +192,7 @@ controller: enableSnippets: false ## Add a location based on the value of health-status-uri to the default server. The location responds with the 200 status code for any request. - ## Useful for external health-checking of the Ingress controller. + ## Useful for external health-checking of the Ingress Controller. healthStatus: false ## Sets the URI of health status location in the default server. Requires controller.healthStatus. @@ -209,16 +209,16 @@ controller: allowCidrs: "127.0.0.1" service: - ## Creates a service to expose the Ingress controller pods. + ## Creates a service to expose the Ingress Controller pods. create: true - ## The type of service to create for the Ingress controller. + ## The type of service to create for the Ingress Controller. type: LoadBalancer ## The externalTrafficPolicy of the service. The value Local preserves the client source IP. externalTrafficPolicy: Local - ## The annotations of the Ingress controller service. + ## The annotations of the Ingress Controller service. annotations: {} ## The extra labels of the service. @@ -227,7 +227,7 @@ controller: ## The static IP address for the load balancer. Requires controller.service.type set to LoadBalancer. The cloud provider must support this feature. loadBalancerIP: "" - ## The list of external IPs for the Ingress controller service. + ## The list of external IPs for the Ingress Controller service. externalIPs: [] ## 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. @@ -238,36 +238,36 @@ controller: # name: nginx-ingress httpPort: - ## Enables the HTTP port for the Ingress controller service. + ## Enables the HTTP port for the Ingress Controller service. enable: true - ## The HTTP port of the Ingress controller service. + ## The HTTP port of the Ingress Controller service. port: 80 ## The custom NodePort for the HTTP port. Requires controller.service.type set to NodePort. nodePort: "" - ## The HTTP port on the POD where the Ingress controller service is running. + ## The HTTP port on the POD where the Ingress Controller service is running. targetPort: 80 httpsPort: - ## Enables the HTTPS port for the Ingress controller service. + ## Enables the HTTPS port for the Ingress Controller service. enable: true - ## The HTTPS port of the Ingress controller service. + ## The HTTPS port of the Ingress Controller service. port: 443 ## The custom NodePort for the HTTPS port. Requires controller.service.type set to NodePort. nodePort: "" - ## The HTTPS port on the POD where the Ingress controller service is running. + ## The HTTPS port on the POD where the Ingress Controller service is running. targetPort: 443 - ## A list of custom ports to expose through the Ingress controller service. Follows the conventional Kubernetes yaml syntax for service ports. + ## A list of custom ports to expose through the Ingress Controller service. Follows the conventional Kubernetes yaml syntax for service ports. customPorts: [] serviceAccount: - ## The name of the service account of the Ingress controller pods. Used for RBAC. + ## The name of the service account of the Ingress Controller pods. Used for RBAC. ## Autogenerated if not set or set to "". # name: nginx-ingress @@ -276,13 +276,13 @@ controller: imagePullSecretName: "" reportIngressStatus: - ## Updates the address field in the status of Ingress resources with an external address of the Ingress controller. + ## 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. enable: true - ## Specifies the name of the service with the type LoadBalancer through which the Ingress controller is exposed externally. + ## 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 matches the created service (see controller.service.create). diff --git a/docs/content/app-protect-dos/installation.md b/docs/content/app-protect-dos/installation.md index b960fbd13a..c6a502aaf5 100644 --- a/docs/content/app-protect-dos/installation.md +++ b/docs/content/app-protect-dos/installation.md @@ -13,11 +13,11 @@ This document provides an overview of the steps required to use NGINX App Protec ## Prerequisites -1. Make sure you have access to the Ingress controller image: - * For NGINX Plus Ingress controller, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. +1. Make sure you have access to the Ingress Controller image: + * For NGINX Plus Ingress Controller, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. * To pull from the F5 Container registry in your Kubernetes cluster, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). -2. Clone the Ingress controller repo: +2. Clone the Ingress Controller repo: ``` $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 $ cd kubernetes-ingress diff --git a/docs/content/configuration/global-configuration/command-line-arguments.md b/docs/content/configuration/global-configuration/command-line-arguments.md index 03bd7f3624..e106959cec 100644 --- a/docs/content/configuration/global-configuration/command-line-arguments.md +++ b/docs/content/configuration/global-configuration/command-line-arguments.md @@ -31,7 +31,7 @@ Secret with a TLS certificate and key for TLS termination of the default server. * If not set, certificate and key in the file `/etc/nginx/secrets/default` are used. * If `/etc/nginx/secrets/default` doesn't exist, the Ingress Controller will configure NGINX to reject TLS connections to the default server. -* If a secret is set, but the Ingress controller is not able to fetch it from Kubernetes API, or it is not set and the Ingress Controller fails to read the file "/etc/nginx/secrets/default", the Ingress controller will fail to start. +* If a secret is set, but the Ingress Controller is not able to fetch it from Kubernetes API, or it is not set and the Ingress Controller fails to read the file "/etc/nginx/secrets/default", the Ingress Controller will fail to start. Format: `/`   @@ -43,7 +43,7 @@ A Secret with a TLS certificate and key for TLS termination of every Ingress/Vir * If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. -* If the argument is set, but the Ingress controller is not able to fetch the Secret from Kubernetes API, the Ingress controller will fail to start. +* If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start. Format: `/`   @@ -99,7 +99,7 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). ### -external-service `` -Specifies the name of the service with the type LoadBalancer through which the Ingress controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. +Specifies the name of the service with the type LoadBalancer through which the Ingress Controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. For Ingress resources only: Requires [-report-ingress-status](#cmdoption-report-ingress-status).   @@ -127,7 +127,7 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). Adds 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. +Useful for external health-checking of the Ingress Controller.   @@ -139,10 +139,10 @@ Sets the URI of health status location in the default server. Requires [-health- ### -ingress-class `` -A class of the Ingress controller. +A class of the Ingress Controller. A corresponding 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 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 resources that do not have the `ingressClassName` field. @@ -181,7 +181,7 @@ Path to the main NGINX configuration template. ### -nginx-configmaps `` -A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, but the Ingress controller is not able to fetch it from Kubernetes API, the Ingress controller will fail to start. +A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, but the Ingress Controller is not able to fetch it from Kubernetes API, the Ingress Controller will fail to start. Format: `/`   @@ -235,7 +235,7 @@ Format: `[1024 - 65535]` (default `8080`) Use a proxy server to connect to Kubernetes API started by "kubectl proxy" command. **For testing purposes only**. -The Ingress controller does not start NGINX and does not write any generated NGINX configuration files to disk. +The Ingress Controller does not start NGINX and does not write any generated NGINX configuration files to disk.   @@ -287,7 +287,7 @@ A comma-separated list of pattern=N settings for file-filtered logging. ### -watch-namespace `` -Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces. +Namespace to watch for Ingress resources. By default the Ingress Controller watches all namespaces.   @@ -310,7 +310,7 @@ Format: `[1024 - 65535]` (default `9113`) A Secret with a TLS certificate and key for TLS termination of the Prometheus metrics endpoint. * If the argument is not set, the prometheus endpoint will not use a TLS connection. -* If the argument is set, but the Ingress controller is not able to fetch the Secret from Kubernetes API, the Ingress controller will fail to start. +* If the argument is set, but the Ingress Controller is not able to fetch the Secret from Kubernetes API, the Ingress Controller will fail to start. Format: `/`   diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index 4a66565228..b86dfc5faa 100644 --- a/docs/content/configuration/global-configuration/configmap-resource.md +++ b/docs/content/configuration/global-configuration/configmap-resource.md @@ -13,7 +13,7 @@ The ConfigMap resources allows you to customize or fine tune NGINX behavior. For ## Using ConfigMap -1. Our [installation instructions](/nginx-ingress-controller/installation/installation-with-manifests) deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use through the [command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) of the Ingress controller. +1. Our [installation instructions](/nginx-ingress-controller/installation/installation-with-manifests) deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress Controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use through the [command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) of the Ingress Controller. 1. Create a ConfigMap file with the name *nginx-config.yaml* and set the values that make sense for your setup: @@ -124,7 +124,7 @@ See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingres {{% table %}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | +|``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | |``ssl-redirect`` | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | ``True`` | | |``hsts`` | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) : the HSTS header is added to the responses from backends. The ``preload`` directive is included in the header. | ``False`` | | |``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | | diff --git a/docs/content/configuration/global-configuration/reporting-resources-status.md b/docs/content/configuration/global-configuration/reporting-resources-status.md index 50c9ab65f0..ec855e6cf6 100644 --- a/docs/content/configuration/global-configuration/reporting-resources-status.md +++ b/docs/content/configuration/global-configuration/reporting-resources-status.md @@ -1,7 +1,7 @@ --- title: Reporting Resources Status -description: +description: weight: 1900 doctypes: [""] aliases: @@ -22,7 +22,7 @@ NAME HOSTS ADDRESS PORTS AGE cafe-ingress cafe.example.com 12.13.23.123 80, 443 2m ``` -The Ingress controller must be configured to report an Ingress status: +The Ingress Controller must be configured to report an Ingress status: 1. Use the command-line flag `-report-ingress-status`. 2. Define a source for an external address. This can be either of: @@ -31,7 +31,7 @@ The Ingress controller must be configured to report an Ingress status: See the docs about [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). -Notes: The Ingress controller does not clear the status of Ingress resources when it is being shut down. +Notes: The Ingress Controller does not clear the status of Ingress resources when it is being shut down. ## VirtualServer and VirtualServerRoute Resources @@ -49,7 +49,7 @@ $ kubectl get virtualservers In order to see additional addresses or extra information about the `Status` of the resource, use the following command: ``` $ kubectl describe virtualserver -. . . +. . . Status: External Endpoints: Ip: 12.13.23.123 @@ -59,43 +59,43 @@ Status: State: Valid ``` -### Status Specification +### Status Specification The following fields are reported in both VirtualServer and VirtualServerRoute status: -{{% table %}} -|Field | Description | Type | -| ---| ---| --- | -|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` an ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | -|``Reason`` | The reason of the last update. | ``string`` | -|``Message`` | Additional information about the state. | ``string`` | -|``ExternalEndpoints`` | A list of external endpoints for which the hosts of the resource are publicly accessible. | [[]externalEndpoint](#externalendpoint) | -{{% /table %}} +{{% table %}} +|Field | Description | Type | +| ---| ---| --- | +|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` an ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | +|``Reason`` | The reason of the last update. | ``string`` | +|``Message`` | Additional information about the state. | ``string`` | +|``ExternalEndpoints`` | A list of external endpoints for which the hosts of the resource are publicly accessible. | [[]externalEndpoint](#externalendpoint) | +{{% /table %}} The following field is reported in the VirtualServerRoute status only: -{{% table %}} -|Field | Description | Type | -| ---| ---| --- | -|``ReferencedBy`` | The VirtualServer that references this VirtualServerRoute. Format is ``namespace/name`` | ``string`` | -{{% /table %}} +{{% table %}} +|Field | Description | Type | +| ---| ---| --- | +|``ReferencedBy`` | The VirtualServer that references this VirtualServerRoute. Format is ``namespace/name`` | ``string`` | +{{% /table %}} ### ExternalEndpoint -{{% table %}} -|Field | Description | Type | -| ---| ---| --- | -|``IP`` | The external IP address. | ``string`` | -|``Ports`` | A list of external ports. | ``string`` | -{{% /table %}} +{{% table %}} +|Field | Description | Type | +| ---| ---| --- | +|``IP`` | The external IP address. | ``string`` | +|``Ports`` | A list of external ports. | ``string`` | +{{% /table %}} -The Ingress controller must be configured to report a VirtualServer or VirtualServerRoute status: +The Ingress Controller must be configured to report a VirtualServer or VirtualServerRoute status: -1. If you want the Ingress controller to report the `externalEndpoints`, define a source for an external address (Note: the rest of the fields will be reported without the external address configured). This can be either of: +1. If you want the Ingress Controller to report the `externalEndpoints`, define a source for an external address (Note: the rest of the fields will be reported without the external address configured). This can be either of: 1. A user defined address, specified in the `external-status-address` ConfigMap key. 2. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. See the docs about [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). -Notes: The Ingress controller does not clear the status of VirtualServer and VirtualServerRoute resources when it is being shut down. +Notes: The Ingress Controller does not clear the status of VirtualServer and VirtualServerRoute resources when it is being shut down. ## Policy Resources @@ -116,16 +116,16 @@ Status: State: Valid ``` -### Status Specification +### Status Specification The following fields are reported in Policy status: -{{% table %}} -|Field | Description | Type | -| ---| ---| --- | -|``State`` | Current state of the resource. Can be ``Valid`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | -|``Reason`` | The reason of the last update. | ``string`` | -|``Message`` | Additional information about the state. | ``string`` | -{{% /table %}} +{{% table %}} +|Field | Description | Type | +| ---| ---| --- | +|``State`` | Current state of the resource. Can be ``Valid`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | +|``Reason`` | The reason of the last update. | ``string`` | +|``Message`` | Additional information about the state. | ``string`` | +{{% /table %}} ## TransportServer Resources @@ -150,11 +150,10 @@ Status: ### Status Specification The following fields are reported in TransportServer status: -{{% table %}} -|Field | Description | Type | -| ---| ---| --- | -|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | -|``Reason`` | The reason of the last update. | ``string`` | -|``Message`` | Additional information about the state. | ``string`` | -{{% /table %}} - +{{% table %}} +|Field | Description | Type | +| ---| ---| --- | +|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | +|``Reason`` | The reason of the last update. | ``string`` | +|``Message`` | Additional information about the state. | ``string`` | +{{% /table %}} diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md index 1b8276c0d7..c4af0f55df 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -108,7 +108,7 @@ The table below summarizes the available annotations. {{% table %}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``kubernetes.io/ingress.class`` | N/A | Specifies which Ingress controller must handle the Ingress resource. Set to ``nginx`` to make NGINX Ingress controller handle it. | N/A | [Multiple Ingress controllers](/nginx-ingress-controller/installation/running-multiple-ingress-controllers). | +|``kubernetes.io/ingress.class`` | N/A | Specifies which Ingress Controller must handle the Ingress resource. Set to ``nginx`` to make NGINX Ingress Controller handle it. | N/A | [Multiple Ingress Controllers](/nginx-ingress-controller/installation/running-multiple-ingress-controllers). | {{% /table %}} ### General Customization @@ -142,7 +142,7 @@ The table below summarizes the available annotations. {{% table %}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/redirect-to-https`` | ``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | +|``nginx.org/redirect-to-https`` | ``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | |``ingress.kubernetes.io/ssl-redirect`` | ``ssl-redirect`` | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | ``True`` | | |``nginx.org/hsts`` | ``hsts`` | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/)\ : the HSTS header is added to the responses from backends. The ``preload`` directive is included in the header. | ``False`` | | |``nginx.org/hsts-max-age`` | ``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | | diff --git a/docs/content/configuration/security.md b/docs/content/configuration/security.md index 471541ca7c..c7d335c7a4 100644 --- a/docs/content/configuration/security.md +++ b/docs/content/configuration/security.md @@ -1,6 +1,6 @@ --- title: Security -description: "NGINX Ingress controller security recommendations." +description: "NGINX Ingress Controller security recommendations." weight: 1500 doctypes: [""] toc: true diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index 1260dadf59..bb0b064056 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -57,7 +57,7 @@ spec: |``policies`` | A list of policies. | [[]policy](#virtualserverpolicy) | No | |``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | |``routes`` | A list of routes. | [[]route](#virtualserver-route) | No | -|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServer resource. | ``string`` | No | +|``ingressClassName`` | Specifies which Ingress Controller must handle the VirtualServer resource. | ``string`` | No | |``http-snippets`` | Sets a custom snippet in the http context. | ``string`` | No | |``server-snippets`` | Sets a custom snippet in server context. Overrides the ``server-snippets`` ConfigMap key. | ``string`` | No | {{% /table %}} @@ -217,7 +217,7 @@ Note that each subroute must have a `path` that starts with the same prefix (her |``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. Must be the same as the ``host`` of the VirtualServer that references this resource. | ``string`` | Yes | |``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | |``subroutes`` | A list of subroutes. | [[]subroute](#virtualserverroutesubroute) | No | -|``ingressClassName`` | Specifies which Ingress controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | +|``ingressClassName`` | Specifies which Ingress Controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | {{% /table %}} ### VirtualServerRoute.Subroute diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index c888e3dea0..011e102a41 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -17,8 +17,8 @@ This document describes how to install the NGINX Ingress Controller in your Kube - Git. - If you’d like to use NGINX Plus: - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` parameter. - - Alternatively, pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). - - Alternatively, you can build an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). + - Alternatively, pull an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). + - Alternatively, you can build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. - If you’d like to use App Protect DoS, please install App Protect DoS Arbitrator helm chart. Make sure to install in the same namespace as the NGINX Ingress Controller. Note that if you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because it is not possible to install more than one Arbitrator in a single namespace. @@ -26,7 +26,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube This step is required if you're installing the chart using its sources. Additionally, the step is also required for managing the custom resource definitions (CRDs), which the Ingress Controller requires by default, or for upgrading/deleting the CRDs. -1. Clone the Ingress controller repo: +1. Clone the Ingress Controller repo: ```console $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 ``` @@ -61,7 +61,7 @@ For NGINX: $ helm install my-release nginx-stable/nginx-ingress ``` -For NGINX Plus: (assuming you have pushed the Ingress controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) +For NGINX Plus: (assuming you have pushed the Ingress Controller image `nginx-plus-ingress` to your private registry `myregistry.example.com`) ```console $ helm install my-release nginx-stable/nginx-ingress --set controller.image.repository=myregistry.example.com/nginx-plus-ingress --set controller.nginxplus=true ``` @@ -79,9 +79,9 @@ For NGINX Plus: $ 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. +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. -When deploying the Ingress controller, make sure to use your own TLS certificate and key for the default server rather than the default pre-generated ones. Read the [Configuration](#configuration) section below to see how to configure a TLS certificate and key for the default server. Note that the default server returns the Not Found page with the 404 status code for all requests for domains for which there are no Ingress rules defined. +When deploying the Ingress Controller, make sure to use your own TLS certificate and key for the default server rather than the default pre-generated ones. Read the [Configuration](#configuration) section below to see how to configure a TLS certificate and key for the default server. Note that the default server returns the Not Found page with the 404 status code for all requests for domains for which there are no Ingress rules defined. ## Upgrading the Chart @@ -141,14 +141,14 @@ See [running multiple ingress controllers](/nginx-ingress-controller/installatio ## Configuration -The following tables lists the configurable parameters of the NGINX Ingress controller chart and their default values. +The following tables lists the configurable parameters of the NGINX Ingress Controller chart and their default values. {{% table %}} |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.nginxplus`` | Deploys the Ingress controller for NGINX Plus. | false | +|``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.nginxplus`` | Deploys the Ingress Controller for NGINX Plus. | false | |``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. The default is 4000 (or 20000 if `controller.appprotect.enable` is true). If set to 0, the default value will be used. | 0 | |``controller.appprotect.enable`` | Enables the App Protect module in the Ingress Controller. | false | |``controller.appprotectdos.enable`` | Enables the App Protect DoS module in the Ingress Controller. | false | @@ -156,13 +156,13 @@ The following tables lists the configurable parameters of the NGINX Ingress cont |``controller.appprotectdos.maxWorkers`` | Max number of nginx processes to support. | Number of CPU cores in the machine |``controller.appprotectdos.maxDaemons`` | Max number of ADMD instances. | 1 |``controller.appprotectdos.memory`` | RAM memory size to consume in MB. | 50% of free RAM in the container or 80MB, the smaller -|``controller.hostNetwork`` | Enables the Ingress controller pods to use the host's network namespace. | false | +|``controller.hostNetwork`` | Enables the Ingress Controller pods to use the host's network namespace. | false | |``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. | 1 | -|``controller.image.repository`` | The image repository of the Ingress controller. | nginx/nginx-ingress | +|``controller.image.repository`` | The image repository of the Ingress Controller. | nginx/nginx-ingress | |``controller.image.tag`` | The tag of the Ingress Controller image. | 2.2.0 | -|``controller.image.pullPolicy`` | The pull policy for the Ingress controller image. | IfNotPresent | -|``controller.config.name`` | The name of the ConfigMap used by the Ingress controller. | Autogenerated | +|``controller.image.pullPolicy`` | The pull policy for the Ingress Controller image. | IfNotPresent | +|``controller.config.name`` | The name of the ConfigMap used by the Ingress Controller. | Autogenerated | |``controller.config.entries`` | The entries of the ConfigMap for customizing NGINX configuration. See [ConfigMap resource docs](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) 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. If not specified, a pre-generated self-signed certificate is used. **Note:** It is recommended that you specify your own certificate. | A pre-generated self-signed certificate. | @@ -171,19 +171,19 @@ 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.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.resources`` | The resources of the Ingress controller pods. | {} | -|``controller.replicaCount`` | The number of replicas of the Ingress controller deployment. | 1 | -|``controller.ingressClass`` | 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.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.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.resources`` | The resources of the Ingress Controller pods. | {} | +|``controller.replicaCount`` | The number of replicas of the Ingress Controller deployment. | 1 | +|``controller.ingressClass`` | 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.setAsDefaultIngress`` | New Ingresses without an ingressClassName field specified will be assigned the class specified in `controller.ingressClass`. | false | -|``controller.watchNamespace`` | Namespace to watch for Ingress resources. By default the Ingress controller watches all namespaces. | "" | +|``controller.watchNamespace`` | Namespace to watch for Ingress resources. By default the Ingress Controller watches all namespaces. | "" | |``controller.enableCustomResources`` | Enable the custom resources. | true | |``controller.enablePreviewPolicies`` | Enable preview policies. This parameter is deprecated. To enable OIDC Policies please use ``controller.enableOIDC`` instead. | false | |``controller.enableOIDC`` | Enable OIDC policies. | false | @@ -191,33 +191,33 @@ The following tables lists the configurable parameters of the NGINX Ingress cont |``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.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 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.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.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.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 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.externalIPs`` | The list of external IPs for the Ingress Controller service. | [] | |``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 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.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 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.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.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 Ingress Controller service. | 443 | +|``controller.serviceAccount.name`` | The name of the service account of the 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.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.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.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 | @@ -233,4 +233,4 @@ The following tables lists the configurable parameters of the NGINX Ingress cont {{% /table %}} ## Notes -* The values-icp.yaml file is used for deploying the Ingress controller on IBM Cloud Private. See the [blog post](https://www.nginx.com/blog/nginx-ingress-controller-ibm-cloud-private/) for more details. +* The values-icp.yaml file is used for deploying the Ingress Controller on IBM Cloud Private. See the [blog post](https://www.nginx.com/blog/nginx-ingress-controller-ibm-cloud-private/) for more details. diff --git a/docs/content/installation/installation-with-manifests.md b/docs/content/installation/installation-with-manifests.md index 5acf15d8bf..5a6c4d516e 100644 --- a/docs/content/installation/installation-with-manifests.md +++ b/docs/content/installation/installation-with-manifests.md @@ -14,12 +14,12 @@ This document describes how to install the NGINX Ingress Controller in your Kube ## Prerequisites -1. Make sure you have access to the 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, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. +1. Make sure you have access to the 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, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. * To pull from the F5 Container registry in your Kubernetes cluster, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). -2. Clone the Ingress controller repo and change into the deployments folder: +2. Clone the Ingress Controller repo and change into the deployments folder: ``` $ git clone https://github.com/nginxinc/kubernetes-ingress.git --branch v2.2.0 $ cd kubernetes-ingress/deployments @@ -27,7 +27,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube ## 1. Configure RBAC -1. Create a namespace and a service account for the Ingress controller: +1. Create a namespace and a service account for the Ingress Controller: ``` $ kubectl apply -f common/ns-and-sa.yaml ``` @@ -116,9 +116,9 @@ If you would like to use the App Protect DoS module, create the following additi ## 3. Deploy the Ingress Controller -We include two options for deploying the Ingress controller: -* *Deployment*. Use a Deployment if you plan to dynamically change the number of Ingress controller replicas. -* *DaemonSet*. Use a DaemonSet for deploying the Ingress controller on every node or a subset of nodes. +We include two options for deploying the Ingress Controller: +* *Deployment*. Use a Deployment if you plan to dynamically change the number of Ingress Controller replicas. +* *DaemonSet*. Use a DaemonSet for deploying the Ingress Controller on every node or a subset of nodes. > Before creating a Deployment or Daemonset resource, make sure to update the [command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) of the Ingress Controller container in the corresponding manifest file according to your requirements. @@ -136,7 +136,7 @@ If you would like to use the App Protect DoS module, need to add arbitrator depl ### 3.1 Run the Ingress Controller * *Use a Deployment*. - When you run the Ingress Controller by using a Deployment, by default, Kubernetes will create one Ingress controller pod. + When you run the Ingress Controller by using a Deployment, by default, Kubernetes will create one Ingress Controller pod. For NGINX, run: ``` @@ -151,9 +151,9 @@ If you would like to use the App Protect DoS module, need to add arbitrator depl **Note**: Update the `nginx-plus-ingress.yaml` with the chosen image from the F5 Container registry; or the container image that you have built. * *Use a DaemonSet*: - When you run the Ingress Controller by using a DaemonSet, Kubernetes will create an Ingress controller pod on every node of the cluster. + When you run the Ingress Controller by using a DaemonSet, Kubernetes will create an Ingress Controller pod on every node of the cluster. - **See also:** See the Kubernetes [DaemonSet docs](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) to learn how to run the Ingress controller on a subset of nodes instead of on every node of the cluster. + **See also:** See the Kubernetes [DaemonSet docs](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) to learn how to run the Ingress Controller on a subset of nodes instead of on every node of the cluster. For NGINX, run: ``` @@ -169,16 +169,16 @@ If you would like to use the App Protect DoS module, need to add arbitrator depl ### 3.2 Check that the Ingress Controller is Running -Run the following command to make sure that the Ingress controller pods are running: +Run the following command to make sure that the Ingress Controller pods are running: ``` $ kubectl get pods --namespace=nginx-ingress ``` ## 4. Get Access to the Ingress Controller -**If you created a daemonset**, ports 80 and 443 of the Ingress controller container are mapped to the same ports of the node where the container is running. To access the Ingress controller, use those ports and an IP address of any node of the cluster where the Ingress controller is running. +**If you created a daemonset**, ports 80 and 443 of the Ingress Controller container are mapped to the same ports of the node where the container is running. To access the Ingress Controller, use those ports and an IP address of any node of the cluster where the Ingress Controller is running. -**If you created a deployment**, below are two options for accessing the Ingress controller pods. +**If you created a deployment**, below are two options for accessing the Ingress Controller pods. ### 4.1 Create a Service for the Ingress Controller Pods @@ -189,7 +189,7 @@ $ kubectl get pods --namespace=nginx-ingress $ kubectl create -f service/nodeport.yaml ``` - Kubernetes will randomly allocate two ports on every node of the cluster. To access the Ingress controller, use an IP address of any node of the cluster along with the two allocated ports. + Kubernetes will randomly allocate two ports on every node of the cluster. To access the Ingress Controller, use an IP address of any node of the cluster along with the two allocated ports. > Read more about the type NodePort in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport). @@ -218,8 +218,8 @@ $ kubectl get pods --namespace=nginx-ingress ``` **Note**: For AWS, additional options regarding an allocated load balancer are available, such as the type of a load balancer and SSL termination. Read the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer) to learn more. - Kubernetes will allocate and configure a cloud load balancer for load balancing the Ingress controller pods. - 2. Use the public IP of the load balancer to access the Ingress controller. To get the public IP: + Kubernetes will allocate and configure a cloud load balancer for load balancing the Ingress Controller pods. + 2. Use the public IP of the load balancer to access the Ingress Controller. To get the public IP: * For GCP or Azure, run: ``` $ kubectl get svc nginx-ingress --namespace=nginx-ingress @@ -239,7 +239,7 @@ $ kubectl get pods --namespace=nginx-ingress ## Uninstall the Ingress Controller -1. Delete the `nginx-ingress` namespace to uninstall the Ingress controller along with all the auxiliary resources that were created: +1. Delete the `nginx-ingress` namespace to uninstall the Ingress Controller along with all the auxiliary resources that were created: ``` $ kubectl delete namespace nginx-ingress ``` diff --git a/docs/content/installation/installation-with-operator.md b/docs/content/installation/installation-with-operator.md index d984ff8d2f..79d3af1f42 100644 --- a/docs/content/installation/installation-with-operator.md +++ b/docs/content/installation/installation-with-operator.md @@ -18,7 +18,7 @@ This document describes how to install the NGINX Ingress Controller in your Kube 1. Make sure you have access to the 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, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. + * For NGINX Plus Ingress Controller, see [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image) for details on how to pull the image from the F5 Docker registry. * To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret). * It is also possible to build your own image and push it to your private Docker registry by following the instructions from [here](/nginx-ingress-controller/installation/building-ingress-controller-image). 1. Install the NGINX Ingress Operator following the [instructions](https://github.com/nginxinc/nginx-ingress-operator/blob/main/docs/installation.md). diff --git a/docs/content/installation/running-multiple-ingress-controllers.md b/docs/content/installation/running-multiple-ingress-controllers.md index f4a53de287..d1425e2371 100644 --- a/docs/content/installation/running-multiple-ingress-controllers.md +++ b/docs/content/installation/running-multiple-ingress-controllers.md @@ -1,7 +1,7 @@ --- title: Running Multiple Ingress Controllers -description: "This document explains how to run multiple NGINX Ingress controllers." +description: "This document explains how to run multiple NGINX Ingress Controllers." weight: 2100 doctypes: [""] aliases: @@ -16,20 +16,20 @@ This document explains the following topics: * How to run NGINX Ingress Controller in the same cluster with another Ingress Controller, such as an Ingress Controller for a cloud HTTP load balancer, and prevent any conflicts between the Ingress Controllers. * How to run multiple NGINX Ingress Controllers. -**Note**: In this document we refer to Ingress, VirtualServer, VirtualServerRoute, and TransportServer resources as configuration resources. +**Note**: In this document we refer to Ingress, VirtualServer, VirtualServerRoute, and TransportServer resources as configuration resources. ## Ingress Class The smooth coexistence of multiple Ingress Controllers in one cluster is provided by the Ingress class concept, which mandates the following: * Every Ingress Controller must only handle Ingress resources for its particular class. -* Ingress resources should have the `ingressClassName` field set to the value, which corresponds to the class of the Ingress Controller the user wants to use. +* Ingress resources should have the `ingressClassName` field set to the value, which corresponds to the class of the Ingress Controller the user wants to use. * VirtualServer, VirtualServerRoute, Policy and TransportServer resources should have the `ingressClassName` field set to the value, which corresponds to the class of the Ingress Controller the user wants to use. ### Configuring Ingress Class The default Ingress class of NGINX Ingress Controller is `nginx`, which means that it only handles configuration resources with the `class` set to `nginx`. You can customize the class through the `-ingress-class` command-line argument. -**Notes**: +**Notes**: * If the class is not set in an Ingress resource, 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` must be set on the IngressClass resource. See Step 3 *Create an IngressClass resource* of the [Create Common Resources](/nginx-ingress-controller/installation/installation-with-manifests/#2-create-common-resources) section. * For VirtualServer, VirtualServerRoute, Policy and TransportServer resources the Ingress Controller will always handle resources with an empty class. diff --git a/docs/content/installation/using-aws-marketplace-image.md b/docs/content/installation/using-aws-marketplace-image.md index c74676d8dd..fbfd997802 100644 --- a/docs/content/installation/using-aws-marketplace-image.md +++ b/docs/content/installation/using-aws-marketplace-image.md @@ -9,10 +9,10 @@ docs: "DOCS-607" This document will walk you through the steps needed to use the NGINX Ingress Controller through the AWS Marketplace. There are additional steps that must be followed in order for the AWS Marketplace NGINX Ingress Controller to work properly. -> **IMPORTANT**: This document uses EKS version 1.19. EKS versions < 1.19 require additional security settings within the NGINX Pod to work properly with marketplace images. +> **IMPORTANT**: This document uses EKS version 1.19. EKS versions < 1.19 require additional security settings within the NGINX Pod to work properly with marketplace images. > This document discusses using eksctl to perform necessary steps to enable the Kubernetes cluster access to deploy NGINX Ingress Controller from the Marketplace. Please make sure you are running a newer version of eksctl and AWS cli. -> **NOTE**: NGINX Ingress controller from the Marketplace does NOT work in AWS Region US-West-1. +> **NOTE**: NGINX Ingress Controller from the Marketplace does NOT work in AWS Region US-West-1. ## Instructions Instructions for using AWS Marketplace: @@ -28,7 +28,7 @@ Instructions for using AWS Marketplace: ## Step by step instructions using eksctl utility. -This assumes you have an existing EKS cluster up and running. If not, please create one before proceeding. This also assumes the namespace for the NGINX Ingress Controller already exists. +This assumes you have an existing EKS cluster up and running. If not, please create one before proceeding. This also assumes the namespace for the NGINX Ingress Controller already exists. 1. Associate your EKS cluster with a “OIDC IAM provider” (replace `--cluster ` and `--region ` with the values of your environment). ``` @@ -79,6 +79,6 @@ kind: ClusterRoleBinding {{< img title="ECR Pull Instructions for the NGINX Ingress Controller" src="./img/ecr-pull-instructions.png" >}} -**Note:** AWS Labs also provides a credential helper - see [their GitHub repo](https://github.com/awslabs/amazon-ecr-credential-helper) for instructions on how to setup and configure. +**Note:** AWS Labs also provides a credential helper - see [their GitHub repo](https://github.com/awslabs/amazon-ecr-credential-helper) for instructions on how to setup and configure. 4. Update the image in the `nginx-plus-ingress.yaml` manifest. diff --git a/docs/content/installation/using-the-jwt-token-docker-secret.md b/docs/content/installation/using-the-jwt-token-docker-secret.md index 5ba1c959df..348fa53356 100644 --- a/docs/content/installation/using-the-jwt-token-docker-secret.md +++ b/docs/content/installation/using-the-jwt-token-docker-secret.md @@ -9,7 +9,7 @@ docs: "DOCS-608" This document explains how to use the NGINX Plus Ingress Controller image from the F5 Docker registry in your Kubernetes cluster by using your NGINX Ingress Controller subscription JWT token. **Please note that an NGINX Plus subscription certificate and key will not work with the F5 Docker registry.** You can also get the image using alternative methods: -* You can use Docker to pull an Ingress controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). +* You can use Docker to pull an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here](/nginx-ingress-controller/installation/pulling-ingress-controller-image). * Please see [here](/nginx-ingress-controller/installation/building-ingress-controller-image) for information on how to build an Ingress Controller image using the source code from this repository and your NGINX Plus subscription certificate and key. * Note that for NGINX Ingress Controller based on NGINX OSS, we provide the image through [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/). diff --git a/docs/content/intro/nginx-ingress-controllers.md b/docs/content/intro/nginx-ingress-controllers.md index 28f65d0e73..8f5101f650 100644 --- a/docs/content/intro/nginx-ingress-controllers.md +++ b/docs/content/intro/nginx-ingress-controllers.md @@ -11,15 +11,15 @@ aliases: --- -There are two NGINX-based Ingress controller implementations out there: the one made by NGINX ([nginxinc/kubernetes-ingress](https://github.com/nginxinc/kubernetes-ingress)) and the one made by Kubernetes ([kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx)). In this document, we explain the key differences between those implementations. This information should help you to choose an appropriate implementation for your requirements or move from one implementation to the other. +There are two NGINX-based Ingress Controller implementations out there: the one made by NGINX ([nginxinc/kubernetes-ingress](https://github.com/nginxinc/kubernetes-ingress)) and the one made by Kubernetes ([kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx)). In this document, we explain the key differences between those implementations. This information should help you to choose an appropriate implementation for your requirements or move from one implementation to the other. ## Which One Am I Using? -If you are unsure about which implementation you are using, check the container image of the Ingress controller that is running. For the nginxinc/kubernetes-ingress Ingress controller its Docker image is published on [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) and available as *nginx/nginx-ingress*. +If you are unsure about which implementation you are using, check the container image of the Ingress Controller that is running. For the nginxinc/kubernetes-ingress Ingress Controller its Docker image is published on [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) and available as *nginx/nginx-ingress*. ## The Key Differences -The table below summarizes the key difference between nginxinc/kubernetes-ingress and kubernetes/ingress-nginx Ingress controllers. Note that the table has two columns for the nginxinc/kubernetes-ingress Ingress controller, as it can be used both with NGINX and NGINX Plus. For more information about nginxinc/kubernetes-ingress with NGINX Plus, read the [NGINX Ingress Controller with NGINX Plus](/nginx-ingress-controller/intro/nginx-plus) documentation. +The table below summarizes the key difference between nginxinc/kubernetes-ingress and kubernetes/ingress-nginx Ingress Controllers. Note that the table has two columns for the nginxinc/kubernetes-ingress Ingress Controller, as it can be used both with NGINX and NGINX Plus. For more information about nginxinc/kubernetes-ingress with NGINX Plus, read the [NGINX Ingress Controller with NGINX Plus](/nginx-ingress-controller/intro/nginx-plus) documentation. {{% table %}} | Aspect or Feature | kubernetes/ingress-nginx | nginxinc/kubernetes-ingress with NGINX | nginxinc/kubernetes-ingress with NGINX Plus | @@ -49,7 +49,7 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres | Helm chart | Supported | Supported | Supported | | Operator | Not supported | Supported | Supported | | **Operational** | -| Reporting the IP address(es) of the Ingress controller into Ingress resources | Supported | Supported | Supported | +| Reporting the IP address(es) of the Ingress Controller into Ingress resources | Supported | Supported | Supported | | Extended Status | Supported via a third-party module | Not supported | Supported | | Prometheus Integration | Supported | Supported | Supported | | Dynamic reconfiguration of endpoints (no configuration reloading) | Supported with a third-party Lua module | Not supported | Supported | @@ -57,10 +57,10 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres Notes: -*1 -- The configuration templates that are used by the Ingress controllers to generate NGINX configuration are different. As a result, for the same Ingress resource the generated NGINX configuration files are different from one Ingress controller to the other, which in turn means that in some cases the behavior of NGINX can be different as well. +*1 -- The configuration templates that are used by the Ingress Controllers to generate NGINX configuration are different. As a result, for the same Ingress resource the generated NGINX configuration files are different from one Ingress Controller to the other, which in turn means that in some cases the behavior of NGINX can be different as well. -*2 -- Because the command-line arguments are different, it is not possible to use the same deployment manifest for deploying the Ingress controllers. +*2 -- Because the command-line arguments are different, it is not possible to use the same deployment manifest for deploying the Ingress Controllers. ## How to Swap an Ingress Controller -If you decide to swap an Ingress controller implementation, be prepared to deal with the differences that were mentioned in the previous section. At minimum, you need to start using a different deployment manifest. +If you decide to swap an Ingress Controller implementation, be prepared to deal with the differences that were mentioned in the previous section. At minimum, you need to start using a different deployment manifest. diff --git a/docs/content/intro/nginx-plus.md b/docs/content/intro/nginx-plus.md index fefa7ffad1..e7fb0c8b9d 100644 --- a/docs/content/intro/nginx-plus.md +++ b/docs/content/intro/nginx-plus.md @@ -1,6 +1,6 @@ --- title: NGINX Ingress Controller with NGINX Plus -description: "This document explains the key characteristics that NGINX Plus brings on top of NGINX into the NGINX Ingress controller." +description: "This document explains the key characteristics that NGINX Plus brings on top of NGINX into the NGINX Ingress Controller." weight: 400 doctypes: ["concept"] toc: true @@ -10,9 +10,9 @@ aliases: --- -NGINX Ingress controller works with both [NGINX](https://nginx.org/) and [NGINX Plus](https://www.nginx.com/products/nginx/) -- a commercial closed source version of NGINX that comes with additional features and support. +NGINX Ingress Controller works with both [NGINX](https://nginx.org/) and [NGINX Plus](https://www.nginx.com/products/nginx/) -- a commercial closed source version of NGINX that comes with additional features and support. -Below are the key characteristics that NGINX Plus brings on top of NGINX into the NGINX Ingress controller. +Below are the key characteristics that NGINX Plus brings on top of NGINX into the NGINX Ingress Controller. ## Additional features @@ -26,8 +26,8 @@ See [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/gl ## Dynamic reconfiguration -Every time the number of pods of services you expose via an Ingress resource changes, the Ingress controller updates the configuration of the load balancer to reflect those changes. For NGINX, the configuration file must be changed and the configuration subsequently reloaded. For NGINX Plus, the dynamic reconfiguration is utilized, which allows NGINX Plus to be updated on-the-fly without reloading the configuration. This prevents increase of memory usage during reloads, especially with a high volume of client requests, as well as increased memory usage when load balancing applications with long-lived connections (WebSocket, applications with file uploading/downloading or streaming). +Every time the number of pods of services you expose via an Ingress resource changes, the Ingress Controller updates the configuration of the load balancer to reflect those changes. For NGINX, the configuration file must be changed and the configuration subsequently reloaded. For NGINX Plus, the dynamic reconfiguration is utilized, which allows NGINX Plus to be updated on-the-fly without reloading the configuration. This prevents increase of memory usage during reloads, especially with a high volume of client requests, as well as increased memory usage when load balancing applications with long-lived connections (WebSocket, applications with file uploading/downloading or streaming). ## Commercial support -Support from NGINX Inc is available for NGINX Plus Ingress controller. +Support from NGINX Inc is available for NGINX Plus Ingress Controller. diff --git a/docs/content/intro/overview.md b/docs/content/intro/overview.md index e37a4a57ad..db47057fe5 100644 --- a/docs/content/intro/overview.md +++ b/docs/content/intro/overview.md @@ -9,7 +9,7 @@ docs: "DOCS-612" -The NGINX Ingress Controller an implementation of a Kubernetes Ingress controller for NGINX and NGINX Plus. +The NGINX Ingress Controller an implementation of a Kubernetes Ingress Controller for NGINX and NGINX Plus. ## What is the Ingress? @@ -25,16 +25,16 @@ See the [Ingress User Guide](https://kubernetes.io/docs/user-guide/ingress/) to ## What is the Ingress Controller? -The Ingress controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer running externally. Different load balancers require different Ingress controller implementations. +The Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer running externally. Different load balancers require different Ingress Controller implementations. -In the case of NGINX, the Ingress controller is deployed in a pod along with the load balancer. +In the case of NGINX, the Ingress Controller is deployed in a pod along with the load balancer. ## NGINX Ingress Controller -NGINX Ingress controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination. +NGINX Ingress Controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination. -Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations) docs to learn more about the supported features and customization options. +Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress Controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations) docs to learn more about the supported features and customization options. -As an alternative to the Ingress, NGINX Ingress controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute Resources doc](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources). +As an alternative to the Ingress, NGINX Ingress Controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute Resources doc](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources). TCP, UDP and TLS Passthrough load balancing is also supported. See the [TransportServer resource doc](/nginx-ingress-controller/configuration/transportserver-resource/). diff --git a/docs/content/logging-and-monitoring/prometheus.md b/docs/content/logging-and-monitoring/prometheus.md index 614e4a4e51..fe1dafe9e2 100644 --- a/docs/content/logging-and-monitoring/prometheus.md +++ b/docs/content/logging-and-monitoring/prometheus.md @@ -16,7 +16,7 @@ The Ingress Controller exposes a number of metrics in the [Prometheus](https://p ## Enabling Metrics If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics: -1. Run the Ingress controller with the `-enable-prometheus-metrics` [command-line argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument). +1. Run the Ingress Controller with the `-enable-prometheus-metrics` [command-line argument](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument). 1. To enable TLS for the Prometheus endpoint, configure the `-prometheus-tls-secret` cli argument with the namespace and name of a TLS Secret. 1. Add the Prometheus port to the list of the ports of the Ingress Controller container in the template of the Ingress Controller pod: ```yaml diff --git a/docs/content/logging-and-monitoring/status-page.md b/docs/content/logging-and-monitoring/status-page.md index ab810d9b80..5996c99b27 100644 --- a/docs/content/logging-and-monitoring/status-page.md +++ b/docs/content/logging-and-monitoring/status-page.md @@ -18,7 +18,7 @@ Prerequisites: 1. The stub status is available on port 8080 by default. It is customizable by the `nginx-status-port` command-line argument. If yours is not on 8080, modify the kubectl proxy command below. To access the status: -1. Use the `kubectl port-forward` command to forward connections to port 8080 on your local machine to port 8080 of an NGINX Ingress controller pod (replace `` with the actual name of a pod):. +1. Use the `kubectl port-forward` command to forward connections to port 8080 on your local machine to port 8080 of an NGINX Ingress Controller pod (replace `` with the actual name of a pod):. ``` $ kubectl port-forward 8080:8080 --namespace=nginx-ingress ``` @@ -35,7 +35,7 @@ Prerequisites: 1. The dashboard is available on port 8080 by default. It is customizable by the `nginx-status-port` command-line argument. If yours is not on 8080, modify the kubectl proxy command below. To access the dashboard: -1. Use the `kubectl port-forward` command to forward connections to port 8080 on your local machine to port 8080 of an NGINX Plus Ingress controller pod (replace `` with the actual name of a pod): +1. Use the `kubectl port-forward` command to forward connections to port 8080 on your local machine to port 8080 of an NGINX Plus Ingress Controller pod (replace `` with the actual name of a pod): ``` $ kubectl port-forward 8080:8080 --namespace=nginx-ingress ``` diff --git a/docs/content/releases.md b/docs/content/releases.md index 53ce326bf7..42720bfe4f 100644 --- a/docs/content/releases.md +++ b/docs/content/releases.md @@ -44,6 +44,7 @@ FIXES: HELM CHART: * [2525](https://github.com/nginxinc/kubernetes-ingress/pull/2525) Extend helm chart to include NGINX Service Mesh fields. * [2294](https://github.com/nginxinc/kubernetes-ingress/pull/2294) Add extra containers to helm chart. Thanks to [Márk Sági-Kazár](https://github.com/sagikazarmark). + UPGRADE: * For NGINX, use the 2.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=2.2.0), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress) or [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress). * For NGINX Plus, use the 2.2.0 images from the F5 Container registry or build your own image using the 2.2.0 source code. diff --git a/examples/appprotect-dos/README.md b/examples/appprotect-dos/README.md index 21d85e759f..b8074258b9 100644 --- a/examples/appprotect-dos/README.md +++ b/examples/appprotect-dos/README.md @@ -1,18 +1,18 @@ # NGINX App Protect DoS Support -In this example we deploy the NGINX Plus Ingress controller with [NGINX App Protect DoS](https://www.nginx.com/products/nginx-app-protect-dos/), a simple web application and then configure load balancing and DOS protection for that application using the Ingress resource. +In this example we deploy the NGINX Plus Ingress Controller with [NGINX App Protect DoS](https://www.nginx.com/products/nginx-app-protect-dos/), a simple web application and then configure load balancing and DOS protection for that application using the Ingress resource. ## Running the Example ## 1. Deploy the Ingress Controller -1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress controller with NGINX App Protect DoS. +1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress Controller with NGINX App Protect DoS. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` -3. Save the HTTPS port of the Ingress controller into a shell variable: +3. Save the HTTPS port of the Ingress Controller into a shell variable: ``` $ IC_HTTPS_PORT= ``` diff --git a/examples/appprotect/README.md b/examples/appprotect/README.md index 3075910665..c08e30f72a 100644 --- a/examples/appprotect/README.md +++ b/examples/appprotect/README.md @@ -1,18 +1,18 @@ # NGINX App Protect Support -In this example we deploy the NGINX Plus Ingress controller with [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/), a simple web application and then configure load balancing and WAF protection for that application using the Ingress resource. +In this example we deploy the NGINX Plus Ingress Controller with [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/), a simple web application and then configure load balancing and WAF protection for that application using the Ingress resource. ## Running the Example ## 1. Deploy the Ingress Controller -1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress controller with NGINX App Protect. +1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress Controller with NGINX App Protect. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` -3. Save the HTTPS port of the Ingress controller into a shell variable: +3. Save the HTTPS port of the Ingress Controller into a shell variable: ``` $ IC_HTTPS_PORT= ``` diff --git a/examples/complete-example/README.md b/examples/complete-example/README.md index e58c251142..020412504b 100644 --- a/examples/complete-example/README.md +++ b/examples/complete-example/README.md @@ -1,18 +1,18 @@ # Example -In this example we deploy the NGINX or NGINX Plus Ingress controller, a simple web application and then configure load balancing for that application using the Ingress resource. +In this example we deploy the NGINX or NGINX Plus Ingress Controller, a simple web application and then configure load balancing for that application using the Ingress resource. ## Running the Example ## 1. Deploy the Ingress Controller -1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress controller. +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` -3. Save the HTTPS port of the Ingress controller into a shell variable: +3. Save the HTTPS port of the Ingress Controller into a shell variable: ``` $ IC_HTTPS_PORT= ``` @@ -40,7 +40,7 @@ $ kubectl create -f cafe.yaml 1. To access the application, curl the coffee and the tea services. We'll use ```curl```'s --insecure option to turn off certificate verification of our self-signed certificate and the --resolve option to set the Host header of a request with ```cafe.example.com``` - + To get coffee: ``` $ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure diff --git a/examples/custom-resources/certmanager/README.md b/examples/custom-resources/certmanager/README.md index 7563db66dc..52bdc1b753 100644 --- a/examples/custom-resources/certmanager/README.md +++ b/examples/custom-resources/certmanager/README.md @@ -1,7 +1,7 @@ # Example In this example, we deploy [cert-manager](https://cert-manager.io/docs/installation/#default-static-install) and a [self-signed certificate issuer](https://cert-manager.io/docs/configuration/selfsigned/#bootstrapping-ca-issuers). -Then, we deploy the NGINX or NGINX Plus Ingress controller, a simple web application and then configure load balancing for that application using the VirtualServer resource. +Then, we deploy the NGINX or NGINX Plus Ingress Controller, a simple web application and then configure load balancing for that application using the VirtualServer resource. ## Deploying the Certmanager and the self-signed authority @@ -20,14 +20,14 @@ Then, we deploy the NGINX or NGINX Plus Ingress controller, a simple web applica ## 1. Deploy the Ingress Controller -1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress controller. +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. * Set the [`-enable-custom-resources`](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-custom-resources) and [`-enable-cert-manager`](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/command-line-arguments/#cmdoption-enable-cert-manager) command-line arguments of the Ingress Controller to enable the cert-manager for Virtual Server resources feature. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` -3. Save the HTTPS port of the Ingress controller into a shell variable: +3. Save the HTTPS port of the Ingress Controller into a shell variable: ``` $ IC_HTTPS_PORT= ``` @@ -50,7 +50,7 @@ $ kubectl create -f cafe.yaml 1. To access the application, curl the coffee and the tea services. We'll use ```curl```'s --insecure option to turn off certificate verification of our self-signed certificate and the --resolve option to set the Host header of a request with ```cafe.example.com``` - + To get coffee: ``` $ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure diff --git a/examples/custom-resources/dos/README.md b/examples/custom-resources/dos/README.md index 41961b65d7..2373e5d058 100644 --- a/examples/custom-resources/dos/README.md +++ b/examples/custom-resources/dos/README.md @@ -1,10 +1,10 @@ # DOS -In this example we deploy the NGINX Plus Ingress controller with [NGINX App Protect DoS](https://www.nginx.com/products/nginx-app-protect-dos/), a simple web application and then configure load balancing and DOS protection for that application using the VirtualServer resource. +In this example we deploy the NGINX Plus Ingress Controller with [NGINX App Protect DoS](https://www.nginx.com/products/nginx-app-protect-dos/), a simple web application and then configure load balancing and DOS protection for that application using the VirtualServer resource. ## Prerequisites -1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress controller with NGINX App Protect DoS. +1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress Controller with NGINX App Protect DoS. 1. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III diff --git a/examples/custom-resources/waf/README.md b/examples/custom-resources/waf/README.md index 839fb44875..efc0be4828 100644 --- a/examples/custom-resources/waf/README.md +++ b/examples/custom-resources/waf/README.md @@ -1,10 +1,10 @@ # WAF -In this example we deploy the NGINX Plus Ingress controller with [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/), a simple web application and then configure load balancing and WAF protection for that application using the VirtualServer resource. +In this example we deploy the NGINX Plus Ingress Controller with [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/), a simple web application and then configure load balancing and WAF protection for that application using the VirtualServer resource. ## Prerequisites -1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress controller with NGINX App Protect. +1. Follow the installation [instructions](https://docs.nginx.com/nginx-ingress-controller/installation) to deploy the Ingress Controller with NGINX App Protect. 1. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III diff --git a/examples/custom-templates/README.md b/examples/custom-templates/README.md index 582340228a..6015ade0ff 100644 --- a/examples/custom-templates/README.md +++ b/examples/custom-templates/README.md @@ -1,6 +1,6 @@ # Custom Templates -The Ingress controller allows you to customize your templates through a [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#snippets-and-custom-templates) via the following keys: +The Ingress Controller allows you to customize your templates through a [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#snippets-and-custom-templates) via the following keys: * `main-template` - Sets the main NGINX configuration template. * `ingress-template` - Sets the Ingress NGINX configuration template for an Ingress resource. * `virtualserver-template` - Sets the NGINX configuration template for an VirtualServer resource. @@ -38,14 +38,14 @@ data: * The templates for NGINX (the main `nginx.tmpl` and the Ingress `nginx.ingress.tmpl`) and NGINX Plus (the main `nginx-plus.tmpl` and the Ingress `nginx-plus.ingress.tmpl`) are located at [internal/configs/version1](../../internal/configs/version1/). The VirtualServer templates for NGINX (`nginx.virtualserver.tmpl`) and NGINX Plus (`nginx-plus.virtualserver.tmpl`) are located at [internal/configs/version2](../../internal/configs/version2/). ## Troubleshooting -* If a custom template contained within the ConfigMap is invalid on startup, the Ingress controller will fail to start, the error will be reported in the Ingress controller logs. +* If a custom template contained within the ConfigMap is invalid on startup, the Ingress Controller will fail to start, the error will be reported in the Ingress Controller logs. An example of an error from the logs: ``` Error updating NGINX main template: template: nginxTemplate:98: unexpected EOF ``` -* If a custom template contained within the ConfigMap is invalid on update, the Ingress controller will not update the NGINX configuration, the error will be reported in the Ingress controller logs and an event with the error will be associated with the ConfigMap. +* If a custom template contained within the ConfigMap is invalid on update, the Ingress Controller will not update the NGINX configuration, the error will be reported in the Ingress Controller logs and an event with the error will be associated with the ConfigMap. An example of an error from the logs: ``` diff --git a/examples/grpc-services/README.md b/examples/grpc-services/README.md index a6d190399b..a57a00875e 100644 --- a/examples/grpc-services/README.md +++ b/examples/grpc-services/README.md @@ -1,6 +1,6 @@ # gRPC support -To support a gRPC application with NGINX Ingress controllers, you need to add the **nginx.org/grpc-services** annotation to your Ingress resource definition. +To support a gRPC application with NGINX Ingress Controllers, you need to add the **nginx.org/grpc-services** annotation to your Ingress resource definition. ## Prerequisites diff --git a/examples/health-checks/README.md b/examples/health-checks/README.md index 019eb89ce6..da9089da9a 100644 --- a/examples/health-checks/README.md +++ b/examples/health-checks/README.md @@ -1,11 +1,11 @@ # Support for Active Health Checks -NGINX Plus supports [active health checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To use active health checks in the Ingress controller: +NGINX Plus supports [active health checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To use active health checks in the Ingress Controller: 1. Define health checks ([HTTP Readiness Probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/#define-readiness-probes)) in the templates of your application pods. -2. Enable heath checks in the Ingress controller using the annotations. +2. Enable heath checks in the Ingress Controller using the annotations. -The Ingress controller provides the following annotations for configuring active health checks: +The Ingress Controller provides the following annotations for configuring active health checks: * Required: `nginx.com/health-checks: "true"` -- enables active health checks. The default is `false`. * Optional: `nginx.com/health-checks-mandatory: "true"` -- configures active health checks as mandatory. With the default active health checks, when an endpoint is added to NGINX Plus via the API or after a configuration reload, NGINX Plus considers the endpoint to be healthy. With mandatory health checks, when an endpoint is added to NGINX Plus or after a configuration reload, NGINX Plus considers the endpoint to be unhealthy until its health check passes. The default is `false`. diff --git a/examples/jwt/README.md b/examples/jwt/README.md index 484ff1ca26..614c603468 100644 --- a/examples/jwt/README.md +++ b/examples/jwt/README.md @@ -2,7 +2,7 @@ NGINX Plus supports validating JWTs with [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). -The Ingress controller provides the following 4 annotations for configuring JWT validation: +The Ingress Controller provides the following 4 annotations for configuring JWT validation: * Required: ```nginx.com/jwt-key: "secret"``` -- specifies a Secret resource with keys for validating JWTs. The keys must be stored in the `jwk` data field. The type of the secret must be `nginx.org/jwk`. * Optional: ```nginx.com/jwt-realm: "realm"``` -- specifies a realm. diff --git a/examples/mergeable-ingress-types/README.md b/examples/mergeable-ingress-types/README.md index ed21708b46..88677b3081 100644 --- a/examples/mergeable-ingress-types/README.md +++ b/examples/mergeable-ingress-types/README.md @@ -56,20 +56,20 @@ Note: Ingress Resources with more than one host cannot be used. ## Example -In this example we deploy the NGINX Ingress controller, a simple web application and then configure +In this example we deploy the NGINX Ingress Controller, a simple web application and then configure load balancing for that application using Ingress resources with the `nginx.org/mergeable-ingress-type` annotations. ## Running the Example ## 1. Deploy the Ingress Controller -1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress controller. +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` -3. Save the HTTPS port of the Ingress controller into a shell variable: +3. Save the HTTPS port of the Ingress Controller into a shell variable: ``` $ IC_HTTPS_PORT= ``` @@ -92,7 +92,7 @@ $ kubectl create -f cafe.yaml ``` $ kubectl create -f cafe-master.yaml ``` - + 3. Create the Minion Ingress resource for the Coffee Service: ``` $ kubectl create -f coffee-minion.yaml @@ -107,7 +107,7 @@ $ kubectl create -f cafe.yaml 1. To access the application, curl the coffee and the tea services. We'll use ```curl```'s --insecure option to turn off certificate verification of our self-signed certificate and the --resolve option to set the Host header of a request with ```cafe.example.com``` - + To get coffee: ``` $ curl --resolve cafe.example.com:$IC_HTTPS_PORT:$IC_IP https://cafe.example.com:$IC_HTTPS_PORT/coffee --insecure @@ -122,7 +122,7 @@ certificate and the --resolve option to set the Host header of a request with `` Server name: tea-7cd44fcb4d-xfw2x ... ``` - + ## 5. Examine the Configuration 1. Access the NGINX Pod. @@ -143,7 +143,7 @@ upstream default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc { upstream default-cafe-ingress-tea-minion-cafe.example.com-tea-svc { server 172.17.0.7:80; server 172.17.0.8:80; - server 172.17.0.9:80; + server 172.17.0.9:80; } # *Master*, configured in Ingress Resource: default-cafe-ingress-master server { @@ -169,7 +169,7 @@ server { proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering on; - proxy_pass http://default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc; + proxy_pass http://default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc; } # *Minion*, configured in Ingress Resource: default-cafe-ingress-tea-minion location /tea { diff --git a/examples/proxy-protocol/README.md b/examples/proxy-protocol/README.md index b1c5844968..b0599e4ef3 100644 --- a/examples/proxy-protocol/README.md +++ b/examples/proxy-protocol/README.md @@ -1,6 +1,6 @@ # PROXY Protocol -Proxies and load balancers, such as HAProxy or ELB, can pass the client's information (the IP address and the port) to the next proxy or load balancer via the PROXY Protocol. To enable NGINX Ingress controller to receive that information, use the `proxy-protocol` ConfigMaps configuration key as well as the `real-ip-header` and the `set-real-ip-from` keys. Once you enable the PROXY Protocol, it is enabled for every Ingress resource. +Proxies and load balancers, such as HAProxy or ELB, can pass the client's information (the IP address and the port) to the next proxy or load balancer via the PROXY Protocol. To enable NGINX Ingress Controller to receive that information, use the `proxy-protocol` ConfigMaps configuration key as well as the `real-ip-header` and the `set-real-ip-from` keys. Once you enable the PROXY Protocol, it is enabled for every Ingress resource. ## Syntax @@ -15,7 +15,7 @@ Additionally, you must configure the following keys: ## Example -In the example below we configure the PROXY Protocol via a ConfigMaps resource. The IP address of the proxy which is in front of the Ingress controller is `192.168.192.168`. +In the example below we configure the PROXY Protocol via a ConfigMaps resource. The IP address of the proxy which is in front of the Ingress Controller is `192.168.192.168`. ```yaml kind: ConfigMap @@ -27,4 +27,4 @@ data: real-ip-header: "proxy_protocol" set-real-ip-from: "192.168.192.168" ``` -After we create the ConfigMaps resource, in the NGINX configuration the client's IP address is available via the `$remote_addr` variable. By default, NGINX Ingress controller logs the value of this variable and also passes the value to the backend service in the `X-Real-IP` header. +After we create the ConfigMaps resource, in the NGINX configuration the client's IP address is available via the `$remote_addr` variable. By default, NGINX Ingress Controller logs the value of this variable and also passes the value to the backend service in the `X-Real-IP` header. diff --git a/examples/rbac/README.md b/examples/rbac/README.md index 053677becb..6386e92b54 100644 --- a/examples/rbac/README.md +++ b/examples/rbac/README.md @@ -1,3 +1,3 @@ # RBAC -It is possible to run the Ingress controller in a cluster with [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) enabled. Read the installation instructions [here](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/). \ No newline at end of file +It is possible to run the Ingress Controller in a cluster with [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) enabled. Read the installation instructions [here](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/). diff --git a/examples/session-persistence/README.md b/examples/session-persistence/README.md index 6299114efe..297b588a49 100644 --- a/examples/session-persistence/README.md +++ b/examples/session-persistence/README.md @@ -1,6 +1,6 @@ # Session Persistence -It is often required that the requests from a client are always passed to the same backend container. You can enable such behavior with [Session Persistence](https://www.nginx.com/products/session-persistence/), available in the NGINX Plus Ingress controller. +It is often required that the requests from a client are always passed to the same backend container. You can enable such behavior with [Session Persistence](https://www.nginx.com/products/session-persistence/), available in the NGINX Plus Ingress Controller. NGINX Plus supports *the sticky cookie* method. With this method, NGINX Plus adds a session cookie to the first response from the backend container, identifying the container that sent the response. When a client issues the next request, it will send the cookie value and NGINX Plus will route the request to the same container. @@ -50,8 +50,8 @@ For both services, the sticky cookie has the same *srv_id* name. However, we spe ## Notes -Session persistence **works** even in the case where you have more than one replicas of the NGINX Plus Ingress controller running. +Session persistence **works** even in the case where you have more than one replicas of the NGINX Plus Ingress Controller running. ## Advanced Session Persistence -The NGINX Plus Ingress controller supports only one of the three session persistence methods available in NGINX Plus. Visit [this page](https://www.nginx.com/products/session-persistence/) to learn about all of the methods. If your session persistence requirements are more complex than the ones in the example above, you will have to use a different approach to deploying and configuring NGINX Plus without the Ingress controller. You can read the [Load Balancing Kubernetes Services with NGINX Plus](https://www.nginx.com/blog/load-balancing-kubernetes-services-nginx-plus/) blog post to find out more. +The NGINX Plus Ingress Controller supports only one of the three session persistence methods available in NGINX Plus. Visit [this page](https://www.nginx.com/products/session-persistence/) to learn about all of the methods. If your session persistence requirements are more complex than the ones in the example above, you will have to use a different approach to deploying and configuring NGINX Plus without the Ingress Controller. You can read the [Load Balancing Kubernetes Services with NGINX Plus](https://www.nginx.com/blog/load-balancing-kubernetes-services-nginx-plus/) blog post to find out more. diff --git a/examples/tcp-udp/README.md b/examples/tcp-udp/README.md index 1ea8eba19c..8617a41004 100644 --- a/examples/tcp-udp/README.md +++ b/examples/tcp-udp/README.md @@ -1,8 +1,8 @@ # Support for TCP/UDP Load Balancing -In this example we deploy the NGINX or NGINX Plus Ingress controller, a DNS server and then configure both TCP and UDP load balancing for the DNS server using the `stream-snippets` [ConfigMap key](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/). +In this example we deploy the NGINX or NGINX Plus Ingress Controller, a DNS server and then configure both TCP and UDP load balancing for the DNS server using the `stream-snippets` [ConfigMap key](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/). -The standard Kubernetes Ingress resources assume that all traffic is HTTP-based; they do not cater for the case of basic TCP or UDP load balancing. In this example, we use the `stream-snippets` ConfigMap key to embed the required TCP and UDP load-balancing configuration directly into the `stream{}` block of the NGINX configuration file. +The standard Kubernetes Ingress resources assume that all traffic is HTTP-based; they do not cater for the case of basic TCP or UDP load balancing. In this example, we use the `stream-snippets` ConfigMap key to embed the required TCP and UDP load-balancing configuration directly into the `stream{}` block of the NGINX configuration file. With NGINX, we’ll use the DNS name or virtual IP address to identify the service, and rely on kube-proxy to perform the internal load-balancing across the pool of pods. With NGINX Plus, we can use a [headless](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services) service and its DNS name to obtain the real IP addresses of the pods behind the service, and load-balance across these. NGINX Plus re-resolves the DNS name frequently, so will update automatically when new pods are deployed or removed. @@ -15,15 +15,15 @@ With NGINX, we’ll use the DNS name or virtual IP address to identify the servi ### 1. Deploy the Ingress Controller -1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress controller. Make sure to expose port 5353 of the Ingress controller +1. Follow the [installation](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) instructions to deploy the Ingress Controller. Make sure to expose port 5353 of the Ingress Controller both for TCP and UDP traffic. -2. Save the public IP address of the Ingress controller into a shell variable: +2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III ``` - **Note**: If you'd like to expose the Ingress controller via a service with the type LoadBalancer, it is not allowed to create a type LoadBalancer service for both TCP and UDP protocols. To overcome this limitation, create two separate services, one for TCP and the other for UDP. In this case you will end up with two separate public IPs, one for TCP and the other for UDP. Use the former in Step 4.2 and the latter in Step 4.1. -3. Save port 5353 of the Ingress controller into a shell variable: + **Note**: If you'd like to expose the Ingress Controller via a service with the type LoadBalancer, it is not allowed to create a type LoadBalancer service for both TCP and UDP protocols. To overcome this limitation, create two separate services, one for TCP and the other for UDP. In this case you will end up with two separate public IPs, one for TCP and the other for UDP. Use the former in Step 4.2 and the latter in Step 4.1. +3. Save port 5353 of the Ingress Controller into a shell variable: ``` $ IC_5353_PORT= ``` @@ -69,7 +69,7 @@ We use `stream-snippets` ConfigMap key to configure TCP and UDP load balancing f ``` We define upstream servers using a DNS name. When NGINX is reloaded, the DNS name will be resolved into the virtual IP of the `coredns` service. - + **Note**: NGINX will fail to reload if the DNS name `coredns.default.svc.cluster.local` cannot be resolved. To avoid that, you can define the upstream servers using the virtual IP of the `coredns` service instead of the DNS name. * For NGINX Plus, we use a different configuration: @@ -101,10 +101,10 @@ We use `stream-snippets` ConfigMap key to configure TCP and UDP load balancing f status_zone coredns-tcp; } ``` - NGINX Plus supports re-resolving DNS names with the `resolve` parameter of the `upstream` directive, which we take an advantage of in our example. Additionally, when the `resolve` parameter is used, NGINX Plus will not fail to reload if the name of an upstream cannot be resolved, in contrast with NGINX. In addition to IP addresses, NGINX Plus will discover ports through DNS SRV records. - + NGINX Plus supports re-resolving DNS names with the `resolve` parameter of the `upstream` directive, which we take an advantage of in our example. Additionally, when the `resolve` parameter is used, NGINX Plus will not fail to reload if the name of an upstream cannot be resolved, in contrast with NGINX. In addition to IP addresses, NGINX Plus will discover ports through DNS SRV records. + To resolve IP addresses and ports, NGINX Plus uses the Kube-DNS, defined with the `resolver` directive. We also set the `valid` parameter to `5s` to make NGINX Plus re-resolve DNS names every 5s. - + Instead of `coredns` service, we use `coredns-headless` service. This service is created as a [headless service](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services), meaning that no virtual IP is allocated for that service and NGINX Plus will be able to resolve the IP addresses of all the CoreDNS pods. **Note**: NGINX Plus will fail to reload if the DNS name, specified in the `resolver` directive, cannot be resolved. To avoid that, you can define the resolver using the virtual IP of the `kube-dns` service instead of the DNS name. @@ -157,7 +157,7 @@ To test that the configured TCP/UDP load balancing works, we resolve the name `k ;; WHEN: Fri Aug 17 12:49:54 BST 2018 ;; MSG SIZE rcvd: 71 ``` - + 1. Resolve `kubernetes.io` through TCP: ``` $ dig @$IC_IP -p $IC_5353_PORT kubernetes.io +tcp @@ -189,4 +189,3 @@ To test that the configured TCP/UDP load balancing works, we resolve the name `k [17/Aug/2018:11:49:54 +0000] UDP 200 71 42 0.016 [17/Aug/2018:11:52:25 +0000] TCP 200 73 44 0.098 ``` - diff --git a/examples/websocket/README.md b/examples/websocket/README.md index 0bee5b9936..cfbe075d53 100644 --- a/examples/websocket/README.md +++ b/examples/websocket/README.md @@ -1,6 +1,6 @@ # WebSocket support -To load balance a WebSocket application with NGINX Ingress controllers, you need to add the **nginx.org/websocket-services** annotation to your Ingress resource definition. The annotation specifies which services are websocket services. The annotation syntax is as follows: +To load balance a WebSocket application with NGINX Ingress Controllers, you need to add the **nginx.org/websocket-services** annotation to your Ingress resource definition. The annotation specifies which services are websocket services. The annotation syntax is as follows: ``` nginx.org/websocket-services: "service1[,service2,...]" ``` From 34b6e6e98280a3257d2ac0af7d2b9cf3891c3eba Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Tue, 12 Apr 2022 10:56:32 -0700 Subject: [PATCH 10/10] update notes --- hack/operator-note.txt | 4 +++- hack/repo-changelog-template.txt | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/hack/operator-note.txt b/hack/operator-note.txt index f3483c9f98..554c44a5ac 100644 --- a/hack/operator-note.txt +++ b/hack/operator-note.txt @@ -1,2 +1,4 @@ -**Note: an NGINX Ingress Operator version compatible with the %%IC_VERSION%% NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version.** +{{< note >}} +An NGINX Ingress Operator version compatible with the %%IC_VERSION%% NGINX Ingress Controller release is not available yet. We will update this document and remove this note once we publish a compatible Operator version. +{{< /note >}} diff --git a/hack/repo-changelog-template.txt b/hack/repo-changelog-template.txt index 0293d2c3ca..06f8085075 100644 --- a/hack/repo-changelog-template.txt +++ b/hack/repo-changelog-template.txt @@ -3,4 +3,4 @@ An automatically generated list of changes can be found on Github at: [%%IC_VERSION%% Release](https://github.com/nginxinc/kubernetes-ingress/releases/tag/v%%IC_VERSION%%) -A curated list of changes can be found in the [Releases](http://docs.nginx.com/nginx-ingress-controller/releases/) page on NGINX Documentation website. +A curated list of changes can be found on the [Releases](http://docs.nginx.com/nginx-ingress-controller/releases/) page on the NGINX Documentation website.