From a8c2590e61c9e985c2f15e2860140829fb5e26ab Mon Sep 17 00:00:00 2001 From: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> Date: Thu, 25 Aug 2022 10:07:50 +0100 Subject: [PATCH] docs: Reorganise examples (#2871) * Initial attempt at reorganising examples * Rename waf and dos folders * Change App Protect to App Protect WAF * Apply suggestions from code review Co-authored-by: Jodie Putrino * Rename examples folders; rename docs folder and attempt alias Co-authored-by: Jodie Putrino --- README.md | 2 +- deployments/helm-chart/README.md | 2 +- deployments/helm-chart/values.yaml | 6 +- docs/content/app-protect-dos/configuration.md | 2 +- docs/content/app-protect-dos/dos-protected.md | 2 +- docs/content/app-protect-dos/installation.md | 4 +- .../_index.md | 1 + .../configuration.md | 62 +++++++++--------- .../installation.md | 21 +++--- .../configuration/configuration-examples.md | 4 +- .../configmap-resource.md | 14 ++-- .../global-configuration/custom-templates.md | 2 +- ...advanced-configuration-with-annotations.md | 40 +++++------ .../ingress-resources/basic-configuration.md | 2 +- .../cross-namespace-configuration.md | 2 +- .../ingress-resources/custom-annotations.md | 2 +- docs/content/configuration/policy-resource.md | 10 +-- ...server-and-virtualserverroute-resources.md | 2 +- .../building-ingress-controller-image.md | 12 ++-- .../installation/installation-with-helm.md | 2 +- .../installation-with-manifests.md | 2 +- .../intro/nginx-ingress-controllers.md | 4 +- docs/content/intro/nginx-plus.md | 10 +-- .../troubleshooting-with-app-protect.md | 12 ++-- .../{dos => app-protect-dos}/README.md | 0 .../app-protect-dos}/apdos-logconf.yaml | 0 .../app-protect-dos}/apdos-policy.yaml | 0 .../app-protect-dos}/apdos-protected.yaml | 0 .../app-protect-dos}/syslog.yaml | 0 .../app-protect-dos}/syslog2.yaml | 0 .../virtual-server.yaml | 0 .../{dos => app-protect-dos}/webapp.yaml | 0 .../{waf => app-protect-waf}/README.md | 0 .../app-protect-waf}/ap-apple-uds.yaml | 0 .../ap-dataguard-alarm-policy.yaml | 0 .../app-protect-waf}/ap-logconf.yaml | 0 .../app-protect-waf}/syslog.yaml | 0 .../virtual-server.yaml | 0 .../{waf => app-protect-waf}/waf.yaml | 0 .../{waf => app-protect-waf}/webapp.yaml | 0 .../custom-templates/README.md | 2 +- .../externalname-services/README.md | 60 +++++++++++++++++ .../custom-resources/health-checks/README.md | 45 +++++++++++++ .../session-persistence/README.md | 54 +++++++++++++++ .../app-protect-dos}/README.md | 0 .../app-protect-dos}/apdos-logconf.yaml | 0 .../app-protect-dos}/apdos-policy.yaml | 0 .../app-protect-dos}/apdos-protected.yaml | 0 .../app-protect-dos}/syslog.yaml | 0 .../app-protect-dos}/syslog2.yaml | 0 .../app-protect-dos}/webapp-ingress.yaml | 0 .../app-protect-dos}/webapp-secret.yaml | 0 .../app-protect-dos}/webapp.yaml | 0 .../app-protect-waf}/README.md | 0 .../app-protect-waf}/ap-apple-uds.yaml | 0 .../ap-dataguard-alarm-policy.yaml | 0 .../app-protect-waf}/ap-logconf.yaml | 0 .../app-protect-waf}/cafe-ingress.yaml | 0 .../app-protect-waf}/cafe-secret.yaml | 0 .../app-protect-waf}/cafe.yaml | 0 .../app-protect-waf}/syslog.yaml | 0 .../basic-auth/README.md | 0 .../basic-auth/cafe-ingress.yaml | 0 .../basic-auth/cafe-passwd.yaml | 0 .../basic-auth/cafe-secret.yaml | 0 .../basic-auth/cafe.yaml | 0 .../complete-example/README.md | 0 .../complete-example/cafe-ingress.yaml | 0 .../complete-example/cafe-secret.yaml | 0 .../complete-example/cafe.yaml | 0 .../complete-example/dashboard.png | Bin .../custom-annotations/README.md | 0 .../custom-templates/README.md | 3 + .../customization/README.md | 0 .../daemon-set/README.md | 0 .../externalname-services/README.md | 0 .../grpc-services/README.md | 0 .../health-checks/README.md | 0 .../{ => ingress-resources}/jwt/README.md | 0 .../mergeable-ingress-types/README.md | 0 .../mergeable-ingress-types/cafe-master.yaml | 0 .../mergeable-ingress-types/cafe-secret.yaml | 0 .../mergeable-ingress-types/cafe.yaml | 0 .../coffee-minion.yaml | 0 .../mergeable-ingress-types/tea-minion.yaml | 0 .../rewrites/README.md | 0 .../session-persistence/README.md | 0 ...cafe-ingress-with-session-persistence.yaml | 0 .../ssl-services/README.md | 0 .../{ => ingress-resources}/tcp-udp/README.md | 0 .../{ => ingress-resources}/tcp-udp/dns.yaml | 0 .../tcp-udp/nginx-config.yaml | 0 .../tcp-udp/nginx-plus-config.yaml | 0 .../websocket/README.md | 0 .../multiple-ingress-controllers/README.md | 3 - .../custom-log-format/README.md | 0 .../custom-templates/README.md | 0 .../proxy-protocol/README.md | 2 +- examples/{ => shared-examples}/rbac/README.md | 0 .../wildcard-tls-certificate/README.md | 0 100 files changed, 277 insertions(+), 114 deletions(-) rename docs/content/{app-protect => app-protect-waf}/_index.md (79%) rename docs/content/{app-protect => app-protect-waf}/configuration.md (80%) rename docs/content/{app-protect => app-protect-waf}/installation.md (71%) rename examples/custom-resources/{dos => app-protect-dos}/README.md (100%) rename examples/{appprotect-dos => custom-resources/app-protect-dos}/apdos-logconf.yaml (100%) rename examples/{appprotect-dos => custom-resources/app-protect-dos}/apdos-policy.yaml (100%) rename examples/{appprotect-dos => custom-resources/app-protect-dos}/apdos-protected.yaml (100%) rename examples/{appprotect-dos => custom-resources/app-protect-dos}/syslog.yaml (100%) rename examples/{appprotect-dos => custom-resources/app-protect-dos}/syslog2.yaml (100%) rename examples/custom-resources/{dos => app-protect-dos}/virtual-server.yaml (100%) rename examples/custom-resources/{dos => app-protect-dos}/webapp.yaml (100%) rename examples/custom-resources/{waf => app-protect-waf}/README.md (100%) rename examples/{appprotect => custom-resources/app-protect-waf}/ap-apple-uds.yaml (100%) rename examples/custom-resources/{waf => app-protect-waf}/ap-dataguard-alarm-policy.yaml (100%) rename examples/{appprotect => custom-resources/app-protect-waf}/ap-logconf.yaml (100%) rename examples/{appprotect => custom-resources/app-protect-waf}/syslog.yaml (100%) rename examples/custom-resources/{waf => app-protect-waf}/virtual-server.yaml (100%) rename examples/custom-resources/{waf => app-protect-waf}/waf.yaml (100%) rename examples/custom-resources/{waf => app-protect-waf}/webapp.yaml (100%) create mode 100644 examples/custom-resources/externalname-services/README.md create mode 100644 examples/custom-resources/health-checks/README.md create mode 100644 examples/custom-resources/session-persistence/README.md rename examples/{appprotect-dos => ingress-resources/app-protect-dos}/README.md (100%) rename examples/{custom-resources/dos => ingress-resources/app-protect-dos}/apdos-logconf.yaml (100%) rename examples/{custom-resources/dos => ingress-resources/app-protect-dos}/apdos-policy.yaml (100%) rename examples/{custom-resources/dos => ingress-resources/app-protect-dos}/apdos-protected.yaml (100%) rename examples/{custom-resources/dos => ingress-resources/app-protect-dos}/syslog.yaml (100%) rename examples/{custom-resources/dos => ingress-resources/app-protect-dos}/syslog2.yaml (100%) rename examples/{appprotect-dos => ingress-resources/app-protect-dos}/webapp-ingress.yaml (100%) rename examples/{appprotect-dos => ingress-resources/app-protect-dos}/webapp-secret.yaml (100%) rename examples/{appprotect-dos => ingress-resources/app-protect-dos}/webapp.yaml (100%) rename examples/{appprotect => ingress-resources/app-protect-waf}/README.md (100%) rename examples/{custom-resources/waf => ingress-resources/app-protect-waf}/ap-apple-uds.yaml (100%) rename examples/{appprotect => ingress-resources/app-protect-waf}/ap-dataguard-alarm-policy.yaml (100%) rename examples/{custom-resources/waf => ingress-resources/app-protect-waf}/ap-logconf.yaml (100%) rename examples/{appprotect => ingress-resources/app-protect-waf}/cafe-ingress.yaml (100%) rename examples/{appprotect => ingress-resources/app-protect-waf}/cafe-secret.yaml (100%) rename examples/{appprotect => ingress-resources/app-protect-waf}/cafe.yaml (100%) rename examples/{custom-resources/waf => ingress-resources/app-protect-waf}/syslog.yaml (100%) rename examples/{ => ingress-resources}/basic-auth/README.md (100%) rename examples/{ => ingress-resources}/basic-auth/cafe-ingress.yaml (100%) rename examples/{ => ingress-resources}/basic-auth/cafe-passwd.yaml (100%) rename examples/{ => ingress-resources}/basic-auth/cafe-secret.yaml (100%) rename examples/{ => ingress-resources}/basic-auth/cafe.yaml (100%) rename examples/{ => ingress-resources}/complete-example/README.md (100%) rename examples/{ => ingress-resources}/complete-example/cafe-ingress.yaml (100%) rename examples/{ => ingress-resources}/complete-example/cafe-secret.yaml (100%) rename examples/{ => ingress-resources}/complete-example/cafe.yaml (100%) rename examples/{ => ingress-resources}/complete-example/dashboard.png (100%) rename examples/{ => ingress-resources}/custom-annotations/README.md (100%) create mode 100644 examples/ingress-resources/custom-templates/README.md rename examples/{ => ingress-resources}/customization/README.md (100%) rename examples/{ => ingress-resources}/daemon-set/README.md (100%) rename examples/{ => ingress-resources}/externalname-services/README.md (100%) rename examples/{ => ingress-resources}/grpc-services/README.md (100%) rename examples/{ => ingress-resources}/health-checks/README.md (100%) rename examples/{ => ingress-resources}/jwt/README.md (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/README.md (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/cafe-master.yaml (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/cafe-secret.yaml (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/cafe.yaml (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/coffee-minion.yaml (100%) rename examples/{ => ingress-resources}/mergeable-ingress-types/tea-minion.yaml (100%) rename examples/{ => ingress-resources}/rewrites/README.md (100%) rename examples/{ => ingress-resources}/session-persistence/README.md (100%) rename examples/{ => ingress-resources}/session-persistence/cafe-ingress-with-session-persistence.yaml (100%) rename examples/{ => ingress-resources}/ssl-services/README.md (100%) rename examples/{ => ingress-resources}/tcp-udp/README.md (100%) rename examples/{ => ingress-resources}/tcp-udp/dns.yaml (100%) rename examples/{ => ingress-resources}/tcp-udp/nginx-config.yaml (100%) rename examples/{ => ingress-resources}/tcp-udp/nginx-plus-config.yaml (100%) rename examples/{ => ingress-resources}/websocket/README.md (100%) delete mode 100644 examples/multiple-ingress-controllers/README.md rename examples/{ => shared-examples}/custom-log-format/README.md (100%) rename examples/{ => shared-examples}/custom-templates/README.md (100%) rename examples/{ => shared-examples}/proxy-protocol/README.md (95%) rename examples/{ => shared-examples}/rbac/README.md (100%) rename examples/{ => shared-examples}/wildcard-tls-certificate/README.md (100%) diff --git a/README.md b/README.md index f50f0fd4e9..57db4dfb3a 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Read [this doc](https://docs.nginx.com/nginx-ingress-controller/intro/nginx-plus 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). + * Use the Ingress resource. See the [Cafe example](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/ingress-resources/complete-example). * Or the VirtualServer resource. See the [Basic configuration](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/basic-configuration) example. 1. See additional configuration [examples](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples). 1. Learn more about all available configuration and customization in the [docs](https://docs.nginx.com/nginx-ingress-controller/). diff --git a/deployments/helm-chart/README.md b/deployments/helm-chart/README.md index d05398b59d..3163177afe 100644 --- a/deployments/helm-chart/README.md +++ b/deployments/helm-chart/README.md @@ -230,7 +230,7 @@ Parameter | Description | Default `controller.reportIngressStatus.annotations` | The annotations of the leader election configmap. | {} `controller.pod.annotations` | The annotations of the Ingress Controller pod. | {} `controller.pod.extraLabels` | The additional extra labels of the Ingress Controller pod. | {} -`controller.appprotect.enable` | Enables the App Protect module in the Ingress Controller. | false +`controller.appprotect.enable` | Enables the App Protect WAF module in the Ingress Controller. | false `controller.appprotectdos.enable` | Enables the App Protect DoS module in the Ingress Controller. | false `controller.appprotectdos.debug` | Enable debugging for App Protect DoS. | false `controller.appprotectdos.maxDaemons` | Max number of ADMD instances. | 1 diff --git a/deployments/helm-chart/values.yaml b/deployments/helm-chart/values.yaml index f5735e41c9..91e7e98dfc 100644 --- a/deployments/helm-chart/values.yaml +++ b/deployments/helm-chart/values.yaml @@ -12,11 +12,11 @@ controller: # Timeout in milliseconds which the Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. nginxReloadTimeout: 60000 - ## Support for App Protect + ## Support for App Protect WAF appprotect: - ## Enable the App Protect module in the Ingress Controller. + ## Enable the App Protect WAF module in the Ingress Controller. enable: false - ## Sets log level for App Protect. Allowed values: fatal, error, warn, info, debug, trace + ## Sets log level for App Protect WAF. Allowed values: fatal, error, warn, info, debug, trace # logLevel: fatal ## Support for App Protect Dos diff --git a/docs/content/app-protect-dos/configuration.md b/docs/content/app-protect-dos/configuration.md index 7322a78304..b7125a7e26 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.3.0/examples/appprotect-dos). +> Check out the complete [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/app-protect-dos) and the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/app-protect-dos). ## App Protect DoS Configuration diff --git a/docs/content/app-protect-dos/dos-protected.md b/docs/content/app-protect-dos/dos-protected.md index 34aec59820..422a6bdc0f 100644 --- a/docs/content/app-protect-dos/dos-protected.md +++ b/docs/content/app-protect-dos/dos-protected.md @@ -71,7 +71,7 @@ If you try to create (or update) a resource that violates the structural schema * Example of `kubectl` validation: ``` $ kubectl apply -f apdos-protected.yaml - error: error validating "examples/appprotect-dos/apdos-protected.yaml": error validating data: ValidationError(DosProtectedResource.spec.enable): invalid type for com.f5.appprotectdos.v1beta1.DosProtectedResource.spec.enable: got "string", expected "boolean"; if you choose to ignore these errors, turn validation off with --validate=false + error: error validating "examples/app-protect-dos/apdos-protected.yaml": error validating data: ValidationError(DosProtectedResource.spec.enable): invalid type for com.f5.appprotectdos.v1beta1.DosProtectedResource.spec.enable: got "string", expected "boolean"; if you choose to ignore these errors, turn validation off with --validate=false ``` * Example of Kubernetes API server validation: ``` diff --git a/docs/content/app-protect-dos/installation.md b/docs/content/app-protect-dos/installation.md index c6f4221008..643e97264d 100644 --- a/docs/content/app-protect-dos/installation.md +++ b/docs/content/app-protect-dos/installation.md @@ -7,7 +7,7 @@ toc: true docs: "DOCS-583" --- -> **Note**: The NGINX Kubernetes Ingress Controller integration with NGINX App Protect requires the use of NGINX Plus. +> **Note**: The NGINX Kubernetes Ingress Controller integration with NGINX App Protect DoS requires the use of NGINX Plus. This document provides an overview of the steps required to use NGINX App Protect DoS with your NGINX Ingress Controller deployment. You can visit the linked documents to find additional information and instructions. @@ -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.3.0/examples/appprotect-dos) and the [NGINX Ingress Controller with App Protect DoS example for VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/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 VirtualServer](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/app-protect-dos) and the [NGINX Ingress Controller with App Protect DoS example for Ingress](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/app-protect-dos). diff --git a/docs/content/app-protect/_index.md b/docs/content/app-protect-waf/_index.md similarity index 79% rename from docs/content/app-protect/_index.md rename to docs/content/app-protect-waf/_index.md index 662709ca58..2f33c4e3e7 100644 --- a/docs/content/app-protect/_index.md +++ b/docs/content/app-protect-waf/_index.md @@ -2,6 +2,7 @@ title: Using with NGINX App Protect description: Learn how to use NGINX Ingress Controller for Kubernetes with NGINX App Protect. weight: 1600 +aliases: ["/nginx-ingress-controller/app-protect/"] menu: docs: parent: NGINX Ingress Controller diff --git a/docs/content/app-protect/configuration.md b/docs/content/app-protect-waf/configuration.md similarity index 80% rename from docs/content/app-protect/configuration.md rename to docs/content/app-protect-waf/configuration.md index 65b678e0fb..4659e37c92 100644 --- a/docs/content/app-protect/configuration.md +++ b/docs/content/app-protect-waf/configuration.md @@ -1,33 +1,32 @@ --- title: Configuration -description: "This document describes how to configure the NGINX App Protect module." +description: "This document describes how to configure the NGINX App Protect WAF module." weight: 1900 doctypes: [""] toc: true docs: "DOCS-578" +aliases: ["/app-protect/configuration/"] --- -> Check out the complete NGINX Ingress Controller with App Protect example resources on GitHub for [VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/waf) and for [Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/appprotect). +> Check out the complete NGINX Ingress Controller with App Protect WAF example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/app-protect-waf). ## 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.3.0/examples/appprotect). +The NGINX Ingress Controller has a set of global configuration parameters that align with those available in the NGINX App Protect WAF 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. ## Enabling App Protect -You can enable and configure NGINX App Protect on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis. +You can enable and configure NGINX App Protect WAF on the Custom Resources (VirtualServer, VirtualServerRoute) or on the Ingress-resource basis. -To configure NGINX App Protect on a VirtualServer resource, you would create a Policy Custom Resource referencing the APPolicy Custom Resource, and add this to the VirtualServer definition. See the documentation on the [App Protect WAF Policy](/nginx-ingress-controller/configuration/policy-resource/#waf). +To configure NGINX App Protect WAF on a VirtualServer resource, you would create a Policy Custom Resource referencing the APPolicy Custom Resource, and add this to the VirtualServer definition. See the documentation on the [App Protect WAF Policy](/nginx-ingress-controller/configuration/policy-resource/#waf). -To configure NGINX App Protect on an Ingress resource, you would apply the [App Protect annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) to each desired resource. +To configure NGINX App Protect WAF on an Ingress resource, you would apply the [App Protect annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) to each desired resource. -## App Protect Policies +## App Protect WAF Policies -You can define App Protect policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +You can define App Protect WAF policies for your VirtualServer, VirtualServerRoute, or Ingress resources by creating an `APPolicy` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). > **Note**: The fields `policy.signature-requirements[].minRevisionDatetime` and `policy.signature-requirements[].maxRevisionDatetime` are not currently supported. @@ -36,7 +35,7 @@ You can define App Protect policies for your VirtualServer, VirtualServerRoute, > **Note**: [External References](/nginx-app-protect/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases. -To add any [App Protect policy](/nginx-app-protect/declarative-policy/policy/) to an Ingress resource: +To add any [App Protect WAF policy](/nginx-app-protect/declarative-policy/policy/) to an Ingress resource: 1. Create an `APPolicy` Custom resource manifest. 2. Add the desired policy to the `spec` field in the `APPolicy` resource. @@ -101,21 +100,22 @@ To add any [App Protect policy](/nginx-app-protect/declarative-policy/policy/) t enforcementUrls: [] ``` - > Notice how the fields match exactly in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect policy config. + > Notice how the fields match exactly in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF policy config.
-## App Protect Logs +## App Protect WAF Logs -You can set the [App Protect log configurations](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +You can set the [App Protect WAF log configurations](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) by creating an `APLogConf` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -To add the [App Protect log configurations](/nginx-app-protect/configuration/#security-logs) to an Ingress resource: +To add the [App Protect WAF log configurations](/nginx-app-protect/configuration/#security-logs) to a VirtualServer or an Ingress resource: 1. Create an `APLogConf` Custom Resource manifest. 2. Add the desired log configuration to the `spec` field in the `APLogConf` resource. +3. Add the `APLogConf` reference to the [VirtualServer Policy resource](/nginx-ingress-controller/configuration/policy-resource/#waf) or the [Ingress resource](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#app-protect) as per the documentation. - > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect log config. + > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF log config. -For example, say you want to [log state changing requests](/nginx-app-protect/configuration/#security-log-configuration-file) for your Ingress resources using App Protect. The App Protect log configuration looks like this: +For example, say you want to [log state changing requests](/nginx-app-protect/configuration/#security-log-configuration-file) for your VirtualServer or Ingress resources using App Protect WAF. The App Protect WAF log configuration looks like this: ```json { @@ -145,20 +145,20 @@ spec: max_request_size: any max_message_size: 5k ``` -## App Protect User Defined Signatures +## App Protect WAF User Defined Signatures -You can define App Protect [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) for your Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +You can define App Protect WAF [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) for your VirtualServer or Ingress resources by creating an `APUserSig` [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). > **Note**: The field `revisionDatetime` is not currently supported. > **Note**: `APUserSig` resources increase the reload time of NGINX Plus compared with `APPolicy` and `APLogConf` resources. Refer to [NGINX Fails to Start or Reload](/nginx-ingress-controller/app-protect/troubleshooting/#nginx-fails-to-start-or-reload) for more information. -To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) to an Ingress resource: +To add the [User Defined Signatures](https://docs.nginx.com/nginx-app-protect/configuration/#user-defined-signature-definitions) to a VirtualServer or Ingress resource: 1. Create an `APUserSig` Custom resource manifest. 2. Add the desired User defined signature to the `spec` field in the `APUserSig` resource. - > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect User Defined signature. There is no need to reference the user defined signature resource in the ingress resource. + > **Note**: The fields from the JSON must be presented in the YAML *exactly* the same, in name and level. The Ingress Controller will transform the YAML into a valid JSON App Protect WAF User Defined signature. There is no need to reference the user defined signature resource in the Policy or Ingress resources. For example, say you want to create the following user defined signature: @@ -246,8 +246,8 @@ These are the typical steps to deploy an OpenAPI protection Policy in NGINX Ingr 3. Make other custom changes if needed (e.g. enable Data Guard protection). 4. Use a tool to convert the result to YAML. There are many, for example: [`yq` utility](https://github.com/mikefarah/yq). 5. Add the YAML properties to create an `APPolicy` Custom Resource putting the policy itself (as in step 4) within the `spec` property of the Custom Resource. Refer to [App Protect Policies](#app-protect-policies) section above. -6. Create a `Policy` object which references the `APPolicy` Custom Resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/custom-resources/waf/waf.yaml). -7. Finally, attach the `Policy` object to a `VirtualServer` resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/main/examples/custom-resources/waf/virtual-server.yaml). +6. Create a `Policy` object which references the `APPolicy` Custom Resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.3.0/examples/custom-resources/waf/waf.yaml). +7. Finally, attach the `Policy` object to a `VirtualServer` resource as in [this example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.3.0/examples/custom-resources/waf/virtual-server.yaml). **Note**: You need to make sure that the server where the resource files are located is always available when you are compiling your policy. @@ -375,21 +375,19 @@ http://localhost/query?query_int=abc The request will be blocked. -The `link` option is also available in the `openApiFileReference` property and is synonymous with the `open-api-files` property as seen in the App Protect policy example above. +The `link` option is also available in the `openApiFileReference` property and is synonymous with the `open-api-files` property as seen in the App Protect WAF policy example above. **Note**: `openApiFileReference` is not an array. ## Configuration in NGINX Plus Ingress Controller using Virtual Server Resource -In this example we deploy the NGINX Plus Ingress Controller with NGINX App Protect, a simple web application and then configure load balancing and WAF protection for that application using the VirtualServer resource. - -**Note:** This example, and the files referenced, can be found [here](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples/custom-resources/waf). +In this example we deploy the NGINX Plus Ingress Controller with NGINX App Protect WAF, a simple web application and then configure load balancing and WAF protection for that application using the VirtualServer resource. -You can find the [Virtual Server example](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/webapp.yaml) here. +**Note:** You can find the example, and the files referenced, on [GitHub](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/waf). ## 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 WAF. 2. Save the public IP address of the Ingress Controller into a shell variable: ``` $ IC_IP=XXX.YYY.ZZZ.III @@ -414,12 +412,12 @@ Create the application deployment and service: $ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/syslog.yaml ``` -2. Create the User Defined Signature, App Protect policy and log configuration: +2. Create the User Defined Signature, App Protect WAF policy, and log configuration: ``` $ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/ap-apple-uds.yaml $ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/ap-dataguard-alarm-policy.yaml - $ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/ap-logconf.yaml + $ kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/ap-logconf.yaml ``` ### Step 3 - Deploy the WAF Policy @@ -467,7 +465,7 @@ To access the application, curl the coffee and the tea services. We'll use the - $ kubectl exec -it -- cat /var/log/messages ``` -### Configuration Example of Virtual Server: +### Configuration Example of Virtual Server Refer to github repo for [Virtual Server example](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.3.0/examples/custom-resources/waf/webapp.yaml). diff --git a/docs/content/app-protect/installation.md b/docs/content/app-protect-waf/installation.md similarity index 71% rename from docs/content/app-protect/installation.md rename to docs/content/app-protect-waf/installation.md index b720e1ada2..bea88cc437 100644 --- a/docs/content/app-protect/installation.md +++ b/docs/content/app-protect-waf/installation.md @@ -1,17 +1,18 @@ --- -title: Installation with NGINX App Protect -description: "This document provides an overview of the steps required to use NGINX App Protect with your NGINX Ingress Controller deployment." +title: Installation with NGINX App Protect WAF +description: "This document provides an overview of the steps required to use NGINX App Protect WAF with your NGINX Ingress Controller deployment." weight: 1800 doctypes: [""] toc: true docs: "DOCS-579" +aliases: ["/app-protect/installation/"] --- -> **Note**: The NGINX Kubernetes Ingress Controller integration with NGINX App Protect requires the use of NGINX Plus. +> **Note**: The NGINX Kubernetes Ingress Controller integration with NGINX App Protect WAF requires the use of NGINX Plus. -This document provides an overview of the steps required to use NGINX App Protect with your NGINX Ingress Controller deployment. You can visit the linked documents to find additional information and instructions. +This document provides an overview of the steps required to use NGINX App Protect WAF with your NGINX Ingress Controller deployment. You can visit the linked documents to find additional information and instructions. -You can also [install the Ingress Controller with App Protect by using Helm](/nginx-ingress-controller/installation/installation-with-helm/). Use the `controller.appprotect.*` parameters of the chart. +You can also [install the Ingress Controller with App Protect WAF by using Helm](/nginx-ingress-controller/installation/installation-with-helm/). Use the `controller.appprotect.*` parameters of the chart. ## Using the Docker Images from the F5 Container registry @@ -54,24 +55,26 @@ Take the steps below to create the Docker image that you'll use to deploy NGINX ``` Alternatively, if you want to run on an [OpenShift](https://www.openshift.com/) cluster, you can use the `ubi-image-nap-plus` target. - If you intend to use [external references](https://docs.nginx.com/nginx-app-protect/configuration/#external-references) in NGINX App Protect policies, you may want to provide a custom CA certificate to authenticate with the hosting server. + If you intend to use [external references](https://docs.nginx.com/nginx-app-protect/configuration/#external-references) in NGINX App Protect WAF policies, you may want to provide a custom CA certificate to authenticate with the hosting server. In order to do so, place the `*.crt` file in the build folder and uncomment the lines that follow this comment: `#Uncomment the lines below if you want to install a custom CA certificate` + > **Note**: [External References](/nginx-app-protect/configuration-guide/configuration/#external-references) in the Ingress Controller are deprecated and will not be supported in future releases. + **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. The Dockerfile will use the latest available version of the [Attack Signatures](/nginx-app-protect/configuration/#attack-signatures) and [Threat Campaigns](/nginx-app-protect/configuration/#threat-campaigns) packages at the time of build. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--no-cache"` to the `make` command. - [Push the image to your local Docker registry](/nginx-ingress-controller/installation/building-ingress-controller-image/#building-the-image-and-pushing-it-to-the-private-registry). ## Install the Ingress Controller -Take the steps below to set up and deploy the NGINX Ingress Controller and App Protect module in your Kubernetes cluster. +Take the steps below to set up and deploy the NGINX Ingress Controller and App Protect WAF module in your Kubernetes cluster. 1. [Configure role-based access control (RBAC)](/nginx-ingress-controller/installation/installation-with-manifests/#1-configure-rbac). > **Important**: You must have an admin role to configure RBAC in your Kubernetes cluster. 2. [Create the common Kubernetes resources](/nginx-ingress-controller/installation/installation-with-manifests/#2-create-common-resources). -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. +3. Enable the App Protect WAF 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.3.0/examples/appprotect). +For more information, see the [Configuration guide](/nginx-ingress-controller/app-protect/configuration) and the NGINX Ingress Controller with App Protect example resources on GitHub [for VirtualServer resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/app-protect-waf) and [for Ingress resources](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/app-protect-waf). diff --git a/docs/content/configuration/configuration-examples.md b/docs/content/configuration/configuration-examples.md index e3992fdda3..e97be46edc 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.3.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.3.0/examples/custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases. +* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources) show how to advanced NGINX features by using VirtualServer, VirtualServerRoute, TransportServer and Policy Custom Resources. +* [*Examples of Ingress Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources) show how to use advanced NGINX features in Ingress resources with annotations. diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index 879671bf55..3042167287 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 (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.3.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.3.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.3.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.3.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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/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,7 +104,7 @@ 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.3.0/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/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.3.0/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/shared-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.3.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`` | | @@ -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.3.0/examples/proxy-protocol). | +|``proxy-protocol`` | Enables PROXY Protocol for incoming connections. | ``False`` | [Proxy Protocol](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/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.3.0/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.3.0/examples/ingress-resources/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 ed72cb893b..205bc86561 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.3.0/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.3.0/examples/shared-examples/custom-templates). 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 65aeeb703d..55edb54706 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -122,7 +122,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 using [proxy_pass](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive. | N/A | [Rewrites Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/rewrites). | +|``nginx.org/rewrites`` | N/A | Configures URI rewriting using [proxy_pass](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive. | N/A | [Rewrites Support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/rewrites). | {{% /table %}} ### Auth and SSL/TLS @@ -138,10 +138,10 @@ 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.org/basic-auth-secret`` | N/A | Specifies a Secret resource with a user list for HTTP Basic authentication. | N/A | | |``nginx.org/basic-auth-realm`` | N/A | Specifies a realm. | N/A | | -|``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.3.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.3.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.3.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.3.0/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/jwt). | {{% /table %}} ### Listeners @@ -159,19 +159,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.3.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.3.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.3.0/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/grpc-services). | +|``nginx.org/websocket-services`` | N/A | Enables WebSocket for services. | N/A | [WebSocket support](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/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.3.0/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.3.0/examples/ingress-resources/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.3.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.3.0/examples/health-checks). | -|``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.3.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.3.0/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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/health-checks). | +|``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.3.0/examples/ingress-resources/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.3.0/examples/ingress-resources/health-checks). | ``"0s"`` | | {{% /table %}} ### Snippets and Custom Templates @@ -185,16 +185,16 @@ The table below summarizes the available annotations. ### App Protect -**Note**: The App Protect annotations only work if App Protect module is [installed](/nginx-ingress-controller/app-protect/installation/). +**Note**: The App Protect annotations only work if App Protect WAF module is [installed](/nginx-ingress-controller/app-protect/installation/). {{% 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.3.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.3.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.3.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.3.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.3.0/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.3.0/examples/ingress-resources/app-protect-waf). | +|``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.3.0/examples/ingress-resources/app-protect-waf). | +|``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.3.0/examples/ingress-resources/app-protect-waf). | +|``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.3.0/examples/ingress-resources/app-protect-waf). | +|``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.3.0/examples/ingress-resources/app-protect-waf). | {{% /table %}} ### App Protect DoS @@ -204,5 +204,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.3.0/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.3.0/examples/ingress-resources/app-protect-dos). | {{% /table %}} diff --git a/docs/content/configuration/ingress-resources/basic-configuration.md b/docs/content/configuration/ingress-resources/basic-configuration.md index 963b8020f8..654ed76e6e 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.3.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.3.0/examples/ingress-resources/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 f327b76e01..ccf24bea88 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.3.0/examples/mergeable-ingress-types) example in our GitHub repo. +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.3.0/examples/ingress-resources/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.3.0/examples/custom-resources/cross-namespace-configuration) example in our GitHub repo. diff --git a/docs/content/configuration/ingress-resources/custom-annotations.md b/docs/content/configuration/ingress-resources/custom-annotations.md index 39154467f8..b2f0bf5cc2 100644 --- a/docs/content/configuration/ingress-resources/custom-annotations.md +++ b/docs/content/configuration/ingress-resources/custom-annotations.md @@ -132,4 +132,4 @@ deny all; ## Example -See the [custom annotations example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.3.0/examples/custom-annotations). +See the [custom annotations example](https://github.com/nginxinc/kubernetes-ingress/blob/v2.3.0/examples/ingress-resources/custom-annotations). diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index f243578605..a7ef34f0d8 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -385,7 +385,7 @@ For `kubectl get` and similar commands, you can also use the short name `pol` in > Note: This feature is only available in NGINX Plus with AppProtect. -The WAF policy configures NGINX Plus to secure client requests using App Protect policies. +The WAF policy configures NGINX Plus to secure client requests using App Protect WAF policies. For example, the following policy will enable the referenced APPolicy. You can configure multiple APLogConfs with log destinations: ```yaml @@ -401,15 +401,15 @@ waf: logDest: "syslog:server=syslog-svc-secondary.default:514" ``` > Note: The field `waf.securityLog` is deprecated and will be removed in future releases.It will be ignored if `waf.securityLogs` is populated. -> Note: The feature is implemented using the NGINX Plus [NGINX App Protect Module](https://docs.nginx.com/nginx-app-protect/configuration/). +> Note: The feature is implemented using the NGINX Plus [NGINX App Protect WAF Module](https://docs.nginx.com/nginx-app-protect/configuration/). {{% table %}} |Field | Description | Type | Required | | ---| ---| ---| --- | -|``enable`` | Enables NGINX App Protect. | ``bool`` | Yes | -|``apPolicy`` | The [App Protect policy](/nginx-ingress-controller/app-protect/configuration/#app-protect-policies) of the WAF. Accepts an optional namespace. | ``string`` | No | +|``enable`` | Enables NGINX App Protect WAF. | ``bool`` | Yes | +|``apPolicy`` | The [App Protect WAF policy](/nginx-ingress-controller/app-protect/configuration/#app-protect-policies) of the WAF. Accepts an optional namespace. | ``string`` | No | |``securityLog.enable`` | Enables security log. | ``bool`` | No | -|``securityLog.apLogConf`` | The [App Protect log conf](/nginx-ingress-controller/app-protect/configuration/#app-protect-logs) resource. Accepts an optional namespace. | ``string`` | No | +|``securityLog.apLogConf`` | The [App Protect WAF log conf](/nginx-ingress-controller/app-protect/configuration/#app-protect-logs) resource. Accepts an optional namespace. | ``string`` | No | |``securityLog.logDest`` | The log destination for the security log. Accepted variables are ``syslog:server=:``, ``stderr``, ````. Default is ``"syslog:server=127.0.0.1:514"``. | ``string`` | No | {{% /table %}} diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index 3fa0462a5d..d703caaeb6 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -312,7 +312,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.3.0/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.3.0/examples/ingress-resources/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 | diff --git a/docs/content/installation/building-ingress-controller-image.md b/docs/content/installation/building-ingress-controller-image.md index 39ee9b4d43..fef1ce657d 100644 --- a/docs/content/installation/building-ingress-controller-image.md +++ b/docs/content/installation/building-ingress-controller-image.md @@ -82,14 +82,14 @@ Below you can find some of the most useful targets in the **Makefile**: * **alpine-image-plus**: for building an alpine-based image with NGINX Plus. * **debian-image**: for building a debian-based image with NGINX. * **debian-image-plus**: for building a debian-based image with NGINX Plus. -* **debian-image-nap-plus**: for building a debian-based image with NGINX Plus and the [appprotect](/nginx-app-protect/) module. -* **debian-image-dos-plus**: for building a debian-based image with NGINX Plus and the [appprotect-dos](/nginx-app-protect-dos/) module. -* **debian-image-nap-dos-plus**: for building a debian-based image with NGINX Plus appprotect and appprotect-dos modules. +* **debian-image-nap-plus**: for building a debian-based image with NGINX Plus and the [app-protect-waf](/nginx-app-protect/) module. +* **debian-image-dos-plus**: for building a debian-based image with NGINX Plus and the [app-protect-dos](/nginx-app-protect-dos/) module. +* **debian-image-nap-dos-plus**: for building a debian-based image with NGINX Plus app-protect-waf and app-protect-dos modules. * **ubi-image**: for building an ubi-based image with NGINX for [Openshift](https://www.openshift.com/) clusters. * **ubi-image-plus**: for building an ubi-based image with NGINX Plus for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-nap-plus**: for building an ubi-based image with NGINX Plus and the [appprotect](/nginx-app-protect/) module for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-dos-plus**: for building an ubi-based image with NGINX Plus and the [appprotect_dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. -* **ubi-image-nap-dos-plus**: for building an ubi-based image with NGINX Plus, [appprotect](/nginx-app-protect/) and the [appprotect_dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-nap-plus**: for building an ubi-based image with NGINX Plus and the [app-protect-waf](/nginx-app-protect/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-dos-plus**: for building an ubi-based image with NGINX Plus and the [app-protect-dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. +* **ubi-image-nap-dos-plus**: for building an ubi-based image with NGINX Plus, [app-protect-waf](/nginx-app-protect/) and the [app-protect-dos](/nginx-app-protect-dos/) module for [Openshift](https://www.openshift.com/) clusters. Note: You need to store your RHEL organization and activation keys in a file named `rhel_license` in the project root. Example: ```bash RHEL_ORGANIZATION=1111111 diff --git a/docs/content/installation/installation-with-helm.md b/docs/content/installation/installation-with-helm.md index ef5802c39c..6a139b8dd3 100644 --- a/docs/content/installation/installation-with-helm.md +++ b/docs/content/installation/installation-with-helm.md @@ -150,7 +150,7 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont |``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.appprotect.enable`` | Enables the App Protect module in the Ingress Controller. | false | +|``controller.appprotect.enable`` | Enables the App Protect WAF module in the Ingress Controller. | false | |``controller.appprotectdos.enable`` | Enables the App Protect DoS module in the Ingress Controller. | false | |``controller.appprotectdos.debug`` | Enables App Protect DoS debug logs. | false | |``controller.appprotectdos.maxWorkers`` | Max number of nginx processes to support. | Number of CPU cores in the machine diff --git a/docs/content/installation/installation-with-manifests.md b/docs/content/installation/installation-with-manifests.md index 741eb58251..c776c1ca2e 100644 --- a/docs/content/installation/installation-with-manifests.md +++ b/docs/content/installation/installation-with-manifests.md @@ -92,7 +92,7 @@ If you would like to use the TCP and UDP load balancing features of the Ingress ### Resources for NGINX App Protect -If you would like to use the App Protect module, create the following additional resources: +If you would like to use the App Protect WAF module, create the following additional resources: 1. Create a custom resource definition for `APPolicy`, `APLogConf` and `APUserSig`: diff --git a/docs/content/intro/nginx-ingress-controllers.md b/docs/content/intro/nginx-ingress-controllers.md index 10d8e6e51d..57913d08fa 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.3.0/examples/mergeable-ingress-types) | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/mergeable-ingress-types) | +| Merging Ingress rules with the same host | Supported | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/mergeable-ingress-types) | Supported via [Mergeable Ingresses](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/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.3.0/examples/websocket) | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/websocket) | +| Websocket | Supported | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/websocket) | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/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 0a78986371..3926c2ae7b 100644 --- a/docs/content/intro/nginx-plus.md +++ b/docs/content/intro/nginx-plus.md @@ -18,11 +18,13 @@ 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.3.0/examples/session-persistence) example. -* *Active health checks*. See the [Support for Active Health Checks](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/health-checks) example. -* *JWT validation*. See the [Support for JSON Web Tokens (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/jwt) example. +* *Session persistence* The *sticky cookie* method is available. See the [Session Persistence for VirtualServer Resources example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/session-persistence) and the [Session Persistence for Ingress Resources example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/session-persistence). +* *Active health checks*. See the [Support for Active Health Checks for VirtualServer Resources example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/health-checks) and the [Support for Active Health Checks for Ingress Resources example](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/health-checks). +* *JWT validation*. See the [Support for JSON Web Tokens for VirtualServer Resources example (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/custom-resources/jwt) and the [Support for JSON Web Tokens for Ingress Resources example (JWTs)](https://github.com/nginxinc/kubernetes-ingress/tree/v2.3.0/examples/ingress-resources/jwt). -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`. +See the [VirtualServer](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources.md), [Policy](https://docs.nginx.com/nginx-ingress-controller/configuration/policy-resource.md) and [TransportServer](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources.md) docs for a comprehensive guide of the NGINX Plus features available by using our custom resources + +For the complete list of available NGINX Plus features available for Ingress resources, see the [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. Note that such features are configured through annotations that start with `nginx.com`, for example, `nginx.com/health-checks`. ## Dynamic reconfiguration diff --git a/docs/content/troubleshooting/troubleshooting-with-app-protect.md b/docs/content/troubleshooting/troubleshooting-with-app-protect.md index 758a8ed36d..3cd57261cf 100644 --- a/docs/content/troubleshooting/troubleshooting-with-app-protect.md +++ b/docs/content/troubleshooting/troubleshooting-with-app-protect.md @@ -1,6 +1,6 @@ --- title: Troubleshooting with NGINX App Protect -description: "This document describes how to troubleshoot problems with the Ingress Controller with the App Protect module enabled." +description: "This document describes how to troubleshoot problems when using NGINX Ingress Controller with the NGINX App Protect WAF module enabled." weight: 2000 doctypes: [""] aliases: @@ -13,11 +13,11 @@ This document describes how to troubleshoot problems with the Ingress Controller For general troubleshooting of the Ingress Controller, check the general [troubleshooting]({{< relref "troubleshooting/troubleshoot-ingress-controller.md" >}}) documentation. -For additional troubleshooting of the App Protect module itself, check the [troubleshooting](/nginx-app-protect/troubleshooting/) guide in the App Protect module documentation. +{{< see-also >}}You can find more troubleshooting tips in the NGINX App Protect WAF [troubleshooting guide](/nginx-app-protect/troubleshooting/) {{< /see-also >}}. ## Potential Problems -The table below categorizes some potential problems with the Ingress Controller when App Protect module is enabled. It suggests how to troubleshoot those problems, using one or more methods from the next section. +The table below categorizes some potential problems with the Ingress Controller when App Protect WAF module is enabled. It suggests how to troubleshoot those problems, using one or more methods from the next section. {{% table %}} |Problem area | Symptom | Troubleshooting method | Common cause | @@ -100,13 +100,13 @@ curl -w '%{time_total}' http://192.168.100.100/resources/headersettings.txt ## Run App Protect in Debug Mode -When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#running-nginx-in-the-debug-mode" >}}) for instructions. +When you set the Ingress Controller to use debug mode, the setting also applies to the App Protect WAF module. See [Running NGINX in the Debug Mode]({{< relref "troubleshooting/troubleshoot-ingress-controller.md#running-nginx-in-the-debug-mode" >}}) for instructions. ## Known Issues -When using the Ingress Controller with the App Protect module, the following issues have been reported. The occurrence of these issues is commonly related to a higher number of Ingress Resources with App Protect being enabled in a cluster. +When using the Ingress Controller with the App Protect WAF module, the following issues have been reported. The occurrence of these issues is commonly related to a higher number of Ingress Resources with App Protect being enabled in a cluster. -When you make a change that requires NGINX to apply a new configuration, the Ingress Controller reloads NGINX automatically. Without the App Protect module enabled, usual reload times are around 150ms. If App Protect module is enabled and is being used by any number of Ingress Resources, these reloads might take a few seconds instead. +When you make a change that requires NGINX to apply a new configuration, the Ingress Controller reloads NGINX automatically. Without the App Protect WAF module enabled, usual reload times are around 150ms. If App Protect WAF module is enabled and is being used by any number of Ingress Resources, these reloads might take a few seconds instead. ### NGINX Configuration Skew diff --git a/examples/custom-resources/dos/README.md b/examples/custom-resources/app-protect-dos/README.md similarity index 100% rename from examples/custom-resources/dos/README.md rename to examples/custom-resources/app-protect-dos/README.md diff --git a/examples/appprotect-dos/apdos-logconf.yaml b/examples/custom-resources/app-protect-dos/apdos-logconf.yaml similarity index 100% rename from examples/appprotect-dos/apdos-logconf.yaml rename to examples/custom-resources/app-protect-dos/apdos-logconf.yaml diff --git a/examples/appprotect-dos/apdos-policy.yaml b/examples/custom-resources/app-protect-dos/apdos-policy.yaml similarity index 100% rename from examples/appprotect-dos/apdos-policy.yaml rename to examples/custom-resources/app-protect-dos/apdos-policy.yaml diff --git a/examples/appprotect-dos/apdos-protected.yaml b/examples/custom-resources/app-protect-dos/apdos-protected.yaml similarity index 100% rename from examples/appprotect-dos/apdos-protected.yaml rename to examples/custom-resources/app-protect-dos/apdos-protected.yaml diff --git a/examples/appprotect-dos/syslog.yaml b/examples/custom-resources/app-protect-dos/syslog.yaml similarity index 100% rename from examples/appprotect-dos/syslog.yaml rename to examples/custom-resources/app-protect-dos/syslog.yaml diff --git a/examples/appprotect-dos/syslog2.yaml b/examples/custom-resources/app-protect-dos/syslog2.yaml similarity index 100% rename from examples/appprotect-dos/syslog2.yaml rename to examples/custom-resources/app-protect-dos/syslog2.yaml diff --git a/examples/custom-resources/dos/virtual-server.yaml b/examples/custom-resources/app-protect-dos/virtual-server.yaml similarity index 100% rename from examples/custom-resources/dos/virtual-server.yaml rename to examples/custom-resources/app-protect-dos/virtual-server.yaml diff --git a/examples/custom-resources/dos/webapp.yaml b/examples/custom-resources/app-protect-dos/webapp.yaml similarity index 100% rename from examples/custom-resources/dos/webapp.yaml rename to examples/custom-resources/app-protect-dos/webapp.yaml diff --git a/examples/custom-resources/waf/README.md b/examples/custom-resources/app-protect-waf/README.md similarity index 100% rename from examples/custom-resources/waf/README.md rename to examples/custom-resources/app-protect-waf/README.md diff --git a/examples/appprotect/ap-apple-uds.yaml b/examples/custom-resources/app-protect-waf/ap-apple-uds.yaml similarity index 100% rename from examples/appprotect/ap-apple-uds.yaml rename to examples/custom-resources/app-protect-waf/ap-apple-uds.yaml diff --git a/examples/custom-resources/waf/ap-dataguard-alarm-policy.yaml b/examples/custom-resources/app-protect-waf/ap-dataguard-alarm-policy.yaml similarity index 100% rename from examples/custom-resources/waf/ap-dataguard-alarm-policy.yaml rename to examples/custom-resources/app-protect-waf/ap-dataguard-alarm-policy.yaml diff --git a/examples/appprotect/ap-logconf.yaml b/examples/custom-resources/app-protect-waf/ap-logconf.yaml similarity index 100% rename from examples/appprotect/ap-logconf.yaml rename to examples/custom-resources/app-protect-waf/ap-logconf.yaml diff --git a/examples/appprotect/syslog.yaml b/examples/custom-resources/app-protect-waf/syslog.yaml similarity index 100% rename from examples/appprotect/syslog.yaml rename to examples/custom-resources/app-protect-waf/syslog.yaml diff --git a/examples/custom-resources/waf/virtual-server.yaml b/examples/custom-resources/app-protect-waf/virtual-server.yaml similarity index 100% rename from examples/custom-resources/waf/virtual-server.yaml rename to examples/custom-resources/app-protect-waf/virtual-server.yaml diff --git a/examples/custom-resources/waf/waf.yaml b/examples/custom-resources/app-protect-waf/waf.yaml similarity index 100% rename from examples/custom-resources/waf/waf.yaml rename to examples/custom-resources/app-protect-waf/waf.yaml diff --git a/examples/custom-resources/waf/webapp.yaml b/examples/custom-resources/app-protect-waf/webapp.yaml similarity index 100% rename from examples/custom-resources/waf/webapp.yaml rename to examples/custom-resources/app-protect-waf/webapp.yaml diff --git a/examples/custom-resources/custom-templates/README.md b/examples/custom-resources/custom-templates/README.md index 38f83d6e6b..47daef5f5a 100644 --- a/examples/custom-resources/custom-templates/README.md +++ b/examples/custom-resources/custom-templates/README.md @@ -1,3 +1,3 @@ # Custom Templates -The Ingress Controller uses a template to generate NGINX configuration for VirtualServer resources. You can customize the template and apply it via the ConfigMap. See the [combined custom templates](../../examples/custom-templates/README.md) example, which shows how to customize the template for the VirtualServer resource as well as the other templates used by the Ingress Controller. +The Ingress Controller uses a template to generate NGINX configuration for VirtualServer resources. You can customize the template and apply it via the ConfigMap. See the [combined custom templates](../../examples/shared-examples/custom-templates/README.md) example, which shows how to customize the template for the VirtualServer resource as well as the other templates used by the Ingress Controller. diff --git a/examples/custom-resources/externalname-services/README.md b/examples/custom-resources/externalname-services/README.md new file mode 100644 index 0000000000..0bc6cc9ee6 --- /dev/null +++ b/examples/custom-resources/externalname-services/README.md @@ -0,0 +1,60 @@ +# Support for Type ExternalName Services +The Ingress Controller supports routing requests to services of the type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). + +An ExternalName service is defined by an external DNS name that is resolved into the IP addresses, typically external to the cluster. This enables to use the Ingress Controller to route requests to the destinations outside of the cluster. + +**Note:** This feature is only available in NGINX Plus. + + +## Prerequisites +To use ExternalName services, first you need to configure one or more resolvers using the ConfigMap. NGINX Plus will use those resolvers to resolve DNS names of the services. + +For example, the following ConfigMap configures one resolver: + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: nginx-config + namespace: nginx-ingress +data: + resolver-addresses: "10.0.0.10" +``` + +Additional resolver parameters, including the caching of DNS records, are available. Check the corresponding [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) section. + + +## Example +In the following yaml file we define an ExternalName service with the name my-service: + +```yaml +kind: Service +apiVersion: v1 +metadata: + name: my-service +spec: + type: ExternalName + externalName: my.service.example.com +``` + +In the following Ingress resource we use my-service: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: example-vs +spec: + host: example.com + upstreams: + - name: my-service + service: my-service + port: 80 + routes: + - path: / + action: + pass: my-service + +``` + +As a result, NGINX Plus will route requests for “example.com” to the IP addresses behind the DNS name my.service.example.com. diff --git a/examples/custom-resources/health-checks/README.md b/examples/custom-resources/health-checks/README.md new file mode 100644 index 0000000000..fd7178bc05 --- /dev/null +++ b/examples/custom-resources/health-checks/README.md @@ -0,0 +1,45 @@ +# 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: + +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 VirtualServer resource for your application. For the full list of configurable parameters, see the [docs](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#upstreamhealthcheck). + +# Example + +In the following example we enable active health checks in the cafe VirtualServer for the tea-svc service: +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: cafe +spec: + host: cafe.example.com + tls: + secret: cafe-secret + upstreams: + - name: tea + service: tea-svc + port: 80 + healthCheck: + enable: true + path: /healthz + interval: 20s + jitter: 3s + fails: 5 + passes: 5 + port: 8080 + tls: + enable: true + connect-timeout: 10s + read-timeout: 10s + send-timeout: 10s + headers: + - name: Host + value: my.service + statusMatch: "! 500" + routes: + - path: /tea + action: + pass: tea +``` diff --git a/examples/custom-resources/session-persistence/README.md b/examples/custom-resources/session-persistence/README.md new file mode 100644 index 0000000000..642cd1d1f2 --- /dev/null +++ b/examples/custom-resources/session-persistence/README.md @@ -0,0 +1,54 @@ +# 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. + +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. + +## Syntax + +To enable session persistence for one or multiple services, configure the sessionCookie block of the upstream definition for the particular service. The annotation specifies services that should have session persistence enabled as well as various attributes of the cookie. The annotation syntax is as follows: + +See the [sticky directive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky) in the NGINX Plus configuration. + +## Example + +In the following example we enable session persistence for two services -- the *tea-svc* service and the *coffee-svc* service: +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: cafe +spec: + host: cafe.example.com + tls: + secret: cafe-secret + upstreams: + - name: tea + service: tea-svc + port: 80 + sessionCookie: + enable: true + name: srv_id + path: /tea + expires: 2h + - name: coffee + service: coffee-svc + port: 80 + sessionCookie: + enable: true + name: srv_id + path: /coffee + expires: 1h + routes: + - path: /tea + action: + pass: tea + - path: /coffee + action: + pass: coffee +``` +For both services, the sticky cookie has the same *srv_id* name. However, we specify the different values of expiration time and path. + +## Notes + +Session persistence **works** even in the case where you have more than one replicas of the NGINX Plus Ingress Controller running. diff --git a/examples/appprotect-dos/README.md b/examples/ingress-resources/app-protect-dos/README.md similarity index 100% rename from examples/appprotect-dos/README.md rename to examples/ingress-resources/app-protect-dos/README.md diff --git a/examples/custom-resources/dos/apdos-logconf.yaml b/examples/ingress-resources/app-protect-dos/apdos-logconf.yaml similarity index 100% rename from examples/custom-resources/dos/apdos-logconf.yaml rename to examples/ingress-resources/app-protect-dos/apdos-logconf.yaml diff --git a/examples/custom-resources/dos/apdos-policy.yaml b/examples/ingress-resources/app-protect-dos/apdos-policy.yaml similarity index 100% rename from examples/custom-resources/dos/apdos-policy.yaml rename to examples/ingress-resources/app-protect-dos/apdos-policy.yaml diff --git a/examples/custom-resources/dos/apdos-protected.yaml b/examples/ingress-resources/app-protect-dos/apdos-protected.yaml similarity index 100% rename from examples/custom-resources/dos/apdos-protected.yaml rename to examples/ingress-resources/app-protect-dos/apdos-protected.yaml diff --git a/examples/custom-resources/dos/syslog.yaml b/examples/ingress-resources/app-protect-dos/syslog.yaml similarity index 100% rename from examples/custom-resources/dos/syslog.yaml rename to examples/ingress-resources/app-protect-dos/syslog.yaml diff --git a/examples/custom-resources/dos/syslog2.yaml b/examples/ingress-resources/app-protect-dos/syslog2.yaml similarity index 100% rename from examples/custom-resources/dos/syslog2.yaml rename to examples/ingress-resources/app-protect-dos/syslog2.yaml diff --git a/examples/appprotect-dos/webapp-ingress.yaml b/examples/ingress-resources/app-protect-dos/webapp-ingress.yaml similarity index 100% rename from examples/appprotect-dos/webapp-ingress.yaml rename to examples/ingress-resources/app-protect-dos/webapp-ingress.yaml diff --git a/examples/appprotect-dos/webapp-secret.yaml b/examples/ingress-resources/app-protect-dos/webapp-secret.yaml similarity index 100% rename from examples/appprotect-dos/webapp-secret.yaml rename to examples/ingress-resources/app-protect-dos/webapp-secret.yaml diff --git a/examples/appprotect-dos/webapp.yaml b/examples/ingress-resources/app-protect-dos/webapp.yaml similarity index 100% rename from examples/appprotect-dos/webapp.yaml rename to examples/ingress-resources/app-protect-dos/webapp.yaml diff --git a/examples/appprotect/README.md b/examples/ingress-resources/app-protect-waf/README.md similarity index 100% rename from examples/appprotect/README.md rename to examples/ingress-resources/app-protect-waf/README.md diff --git a/examples/custom-resources/waf/ap-apple-uds.yaml b/examples/ingress-resources/app-protect-waf/ap-apple-uds.yaml similarity index 100% rename from examples/custom-resources/waf/ap-apple-uds.yaml rename to examples/ingress-resources/app-protect-waf/ap-apple-uds.yaml diff --git a/examples/appprotect/ap-dataguard-alarm-policy.yaml b/examples/ingress-resources/app-protect-waf/ap-dataguard-alarm-policy.yaml similarity index 100% rename from examples/appprotect/ap-dataguard-alarm-policy.yaml rename to examples/ingress-resources/app-protect-waf/ap-dataguard-alarm-policy.yaml diff --git a/examples/custom-resources/waf/ap-logconf.yaml b/examples/ingress-resources/app-protect-waf/ap-logconf.yaml similarity index 100% rename from examples/custom-resources/waf/ap-logconf.yaml rename to examples/ingress-resources/app-protect-waf/ap-logconf.yaml diff --git a/examples/appprotect/cafe-ingress.yaml b/examples/ingress-resources/app-protect-waf/cafe-ingress.yaml similarity index 100% rename from examples/appprotect/cafe-ingress.yaml rename to examples/ingress-resources/app-protect-waf/cafe-ingress.yaml diff --git a/examples/appprotect/cafe-secret.yaml b/examples/ingress-resources/app-protect-waf/cafe-secret.yaml similarity index 100% rename from examples/appprotect/cafe-secret.yaml rename to examples/ingress-resources/app-protect-waf/cafe-secret.yaml diff --git a/examples/appprotect/cafe.yaml b/examples/ingress-resources/app-protect-waf/cafe.yaml similarity index 100% rename from examples/appprotect/cafe.yaml rename to examples/ingress-resources/app-protect-waf/cafe.yaml diff --git a/examples/custom-resources/waf/syslog.yaml b/examples/ingress-resources/app-protect-waf/syslog.yaml similarity index 100% rename from examples/custom-resources/waf/syslog.yaml rename to examples/ingress-resources/app-protect-waf/syslog.yaml diff --git a/examples/basic-auth/README.md b/examples/ingress-resources/basic-auth/README.md similarity index 100% rename from examples/basic-auth/README.md rename to examples/ingress-resources/basic-auth/README.md diff --git a/examples/basic-auth/cafe-ingress.yaml b/examples/ingress-resources/basic-auth/cafe-ingress.yaml similarity index 100% rename from examples/basic-auth/cafe-ingress.yaml rename to examples/ingress-resources/basic-auth/cafe-ingress.yaml diff --git a/examples/basic-auth/cafe-passwd.yaml b/examples/ingress-resources/basic-auth/cafe-passwd.yaml similarity index 100% rename from examples/basic-auth/cafe-passwd.yaml rename to examples/ingress-resources/basic-auth/cafe-passwd.yaml diff --git a/examples/basic-auth/cafe-secret.yaml b/examples/ingress-resources/basic-auth/cafe-secret.yaml similarity index 100% rename from examples/basic-auth/cafe-secret.yaml rename to examples/ingress-resources/basic-auth/cafe-secret.yaml diff --git a/examples/basic-auth/cafe.yaml b/examples/ingress-resources/basic-auth/cafe.yaml similarity index 100% rename from examples/basic-auth/cafe.yaml rename to examples/ingress-resources/basic-auth/cafe.yaml diff --git a/examples/complete-example/README.md b/examples/ingress-resources/complete-example/README.md similarity index 100% rename from examples/complete-example/README.md rename to examples/ingress-resources/complete-example/README.md diff --git a/examples/complete-example/cafe-ingress.yaml b/examples/ingress-resources/complete-example/cafe-ingress.yaml similarity index 100% rename from examples/complete-example/cafe-ingress.yaml rename to examples/ingress-resources/complete-example/cafe-ingress.yaml diff --git a/examples/complete-example/cafe-secret.yaml b/examples/ingress-resources/complete-example/cafe-secret.yaml similarity index 100% rename from examples/complete-example/cafe-secret.yaml rename to examples/ingress-resources/complete-example/cafe-secret.yaml diff --git a/examples/complete-example/cafe.yaml b/examples/ingress-resources/complete-example/cafe.yaml similarity index 100% rename from examples/complete-example/cafe.yaml rename to examples/ingress-resources/complete-example/cafe.yaml diff --git a/examples/complete-example/dashboard.png b/examples/ingress-resources/complete-example/dashboard.png similarity index 100% rename from examples/complete-example/dashboard.png rename to examples/ingress-resources/complete-example/dashboard.png diff --git a/examples/custom-annotations/README.md b/examples/ingress-resources/custom-annotations/README.md similarity index 100% rename from examples/custom-annotations/README.md rename to examples/ingress-resources/custom-annotations/README.md diff --git a/examples/ingress-resources/custom-templates/README.md b/examples/ingress-resources/custom-templates/README.md new file mode 100644 index 0000000000..edb8264d8d --- /dev/null +++ b/examples/ingress-resources/custom-templates/README.md @@ -0,0 +1,3 @@ +# Custom Templates + +The Ingress Controller uses a template to generate NGINX configuration for Ingress resources. You can customize the template and apply it via the ConfigMap. See the [combined custom templates](../../examples/shared-examples/custom-templates/README.md) example, which shows how to customize the template for the Ingress resource as well as the other templates used by the Ingress Controller. diff --git a/examples/customization/README.md b/examples/ingress-resources/customization/README.md similarity index 100% rename from examples/customization/README.md rename to examples/ingress-resources/customization/README.md diff --git a/examples/daemon-set/README.md b/examples/ingress-resources/daemon-set/README.md similarity index 100% rename from examples/daemon-set/README.md rename to examples/ingress-resources/daemon-set/README.md diff --git a/examples/externalname-services/README.md b/examples/ingress-resources/externalname-services/README.md similarity index 100% rename from examples/externalname-services/README.md rename to examples/ingress-resources/externalname-services/README.md diff --git a/examples/grpc-services/README.md b/examples/ingress-resources/grpc-services/README.md similarity index 100% rename from examples/grpc-services/README.md rename to examples/ingress-resources/grpc-services/README.md diff --git a/examples/health-checks/README.md b/examples/ingress-resources/health-checks/README.md similarity index 100% rename from examples/health-checks/README.md rename to examples/ingress-resources/health-checks/README.md diff --git a/examples/jwt/README.md b/examples/ingress-resources/jwt/README.md similarity index 100% rename from examples/jwt/README.md rename to examples/ingress-resources/jwt/README.md diff --git a/examples/mergeable-ingress-types/README.md b/examples/ingress-resources/mergeable-ingress-types/README.md similarity index 100% rename from examples/mergeable-ingress-types/README.md rename to examples/ingress-resources/mergeable-ingress-types/README.md diff --git a/examples/mergeable-ingress-types/cafe-master.yaml b/examples/ingress-resources/mergeable-ingress-types/cafe-master.yaml similarity index 100% rename from examples/mergeable-ingress-types/cafe-master.yaml rename to examples/ingress-resources/mergeable-ingress-types/cafe-master.yaml diff --git a/examples/mergeable-ingress-types/cafe-secret.yaml b/examples/ingress-resources/mergeable-ingress-types/cafe-secret.yaml similarity index 100% rename from examples/mergeable-ingress-types/cafe-secret.yaml rename to examples/ingress-resources/mergeable-ingress-types/cafe-secret.yaml diff --git a/examples/mergeable-ingress-types/cafe.yaml b/examples/ingress-resources/mergeable-ingress-types/cafe.yaml similarity index 100% rename from examples/mergeable-ingress-types/cafe.yaml rename to examples/ingress-resources/mergeable-ingress-types/cafe.yaml diff --git a/examples/mergeable-ingress-types/coffee-minion.yaml b/examples/ingress-resources/mergeable-ingress-types/coffee-minion.yaml similarity index 100% rename from examples/mergeable-ingress-types/coffee-minion.yaml rename to examples/ingress-resources/mergeable-ingress-types/coffee-minion.yaml diff --git a/examples/mergeable-ingress-types/tea-minion.yaml b/examples/ingress-resources/mergeable-ingress-types/tea-minion.yaml similarity index 100% rename from examples/mergeable-ingress-types/tea-minion.yaml rename to examples/ingress-resources/mergeable-ingress-types/tea-minion.yaml diff --git a/examples/rewrites/README.md b/examples/ingress-resources/rewrites/README.md similarity index 100% rename from examples/rewrites/README.md rename to examples/ingress-resources/rewrites/README.md diff --git a/examples/session-persistence/README.md b/examples/ingress-resources/session-persistence/README.md similarity index 100% rename from examples/session-persistence/README.md rename to examples/ingress-resources/session-persistence/README.md diff --git a/examples/session-persistence/cafe-ingress-with-session-persistence.yaml b/examples/ingress-resources/session-persistence/cafe-ingress-with-session-persistence.yaml similarity index 100% rename from examples/session-persistence/cafe-ingress-with-session-persistence.yaml rename to examples/ingress-resources/session-persistence/cafe-ingress-with-session-persistence.yaml diff --git a/examples/ssl-services/README.md b/examples/ingress-resources/ssl-services/README.md similarity index 100% rename from examples/ssl-services/README.md rename to examples/ingress-resources/ssl-services/README.md diff --git a/examples/tcp-udp/README.md b/examples/ingress-resources/tcp-udp/README.md similarity index 100% rename from examples/tcp-udp/README.md rename to examples/ingress-resources/tcp-udp/README.md diff --git a/examples/tcp-udp/dns.yaml b/examples/ingress-resources/tcp-udp/dns.yaml similarity index 100% rename from examples/tcp-udp/dns.yaml rename to examples/ingress-resources/tcp-udp/dns.yaml diff --git a/examples/tcp-udp/nginx-config.yaml b/examples/ingress-resources/tcp-udp/nginx-config.yaml similarity index 100% rename from examples/tcp-udp/nginx-config.yaml rename to examples/ingress-resources/tcp-udp/nginx-config.yaml diff --git a/examples/tcp-udp/nginx-plus-config.yaml b/examples/ingress-resources/tcp-udp/nginx-plus-config.yaml similarity index 100% rename from examples/tcp-udp/nginx-plus-config.yaml rename to examples/ingress-resources/tcp-udp/nginx-plus-config.yaml diff --git a/examples/websocket/README.md b/examples/ingress-resources/websocket/README.md similarity index 100% rename from examples/websocket/README.md rename to examples/ingress-resources/websocket/README.md diff --git a/examples/multiple-ingress-controllers/README.md b/examples/multiple-ingress-controllers/README.md deleted file mode 100644 index 910b3c5b01..0000000000 --- a/examples/multiple-ingress-controllers/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Using Multiple Ingress Controllers - -This example has been transformed into the [Multiple Ingress Controllers doc](https://docs.nginx.com/nginx-ingress-controller/installation/running-multiple-ingress-controllers/). diff --git a/examples/custom-log-format/README.md b/examples/shared-examples/custom-log-format/README.md similarity index 100% rename from examples/custom-log-format/README.md rename to examples/shared-examples/custom-log-format/README.md diff --git a/examples/custom-templates/README.md b/examples/shared-examples/custom-templates/README.md similarity index 100% rename from examples/custom-templates/README.md rename to examples/shared-examples/custom-templates/README.md diff --git a/examples/proxy-protocol/README.md b/examples/shared-examples/proxy-protocol/README.md similarity index 95% rename from examples/proxy-protocol/README.md rename to examples/shared-examples/proxy-protocol/README.md index b0599e4ef3..636af955ce 100644 --- a/examples/proxy-protocol/README.md +++ b/examples/shared-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 and VirtualServer resource. ## Syntax diff --git a/examples/rbac/README.md b/examples/shared-examples/rbac/README.md similarity index 100% rename from examples/rbac/README.md rename to examples/shared-examples/rbac/README.md diff --git a/examples/wildcard-tls-certificate/README.md b/examples/shared-examples/wildcard-tls-certificate/README.md similarity index 100% rename from examples/wildcard-tls-certificate/README.md rename to examples/shared-examples/wildcard-tls-certificate/README.md