diff --git a/docs/content/configuration/configuration-examples.md b/docs/content/configuration/configuration-examples.md index 3b74c7d85a..aa65bacad6 100644 --- a/docs/content/configuration/configuration-examples.md +++ b/docs/content/configuration/configuration-examples.md @@ -2,9 +2,9 @@ docs: DOCS-584 doctypes: - '' -title: Configuration Examples +title: Configuration examples toc: true -weight: 2000 +weight: 400 --- Our [GitHub repo](https://github.com/nginxinc/kubernetes-ingress) includes a number of configuration examples: diff --git a/docs/content/configuration/global-configuration/_index.md b/docs/content/configuration/global-configuration/_index.md index f2b919eb4c..4f71e2f5f4 100644 --- a/docs/content/configuration/global-configuration/_index.md +++ b/docs/content/configuration/global-configuration/_index.md @@ -1,7 +1,7 @@ --- -title: Global Configuration +title: Global configuration description: -weight: 1400 +weight: 100 menu: docs: parent: NGINX Ingress Controller diff --git a/docs/content/configuration/global-configuration/command-line-arguments.md b/docs/content/configuration/global-configuration/command-line-arguments.md index 973a80e73c..377ea9ea6b 100644 --- a/docs/content/configuration/global-configuration/command-line-arguments.md +++ b/docs/content/configuration/global-configuration/command-line-arguments.md @@ -2,15 +2,15 @@ docs: DOCS-585 doctypes: - '' -title: Command-line Arguments +title: Command-line arguments toc: true -weight: 1700 +weight: 100 --- -NGINX Ingress Controller supports several command-line arguments, which are passed to it based on your installation method: +F5 NGINX Ingress Controller supports several command-line arguments, which are set based on installation method: -- If you're using *Kubernetes Manifests* (Deployment or DaemonSet) to install NGINX Ingress Controller, modify the Manifests to set the command-line arguments. Read [Installation with Manifests]({{}}) for more information. -- If you're using *Helm* to install NGINX Ingress Controller, modify the parameters of the Helm chart to set the command-line arguments. Read [Installation with Helm]({{}}) documentation for more information. +- If you're using *Kubernetes Manifests* to install NGINX Ingress Controller, modify the Manifests to set the command-line arguments. View the [Installation with Manifests]({{}}) topic for more information. +- If you're using *Helm* to install NGINX Ingress Controller, modify the parameters of the Helm chart to set the command-line arguments. View the [Installation with Helm]({{}}) topic for more information. @@ -22,6 +22,8 @@ Default `false`. +--- + ### -default-server-tls-secret `` Secret with a TLS certificate and key for TLS termination of the default server. @@ -34,18 +36,21 @@ Format: `/` +--- + ### -wildcard-tls-secret `` A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified. -- If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection. - +- If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection - If the argument is set, but NGINX Ingress Controller is not able to fetch the Secret from Kubernetes API, NGINX Ingress Controller will fail to start. Format: `/` +--- + ### -enable-custom-resources Enables custom resources. @@ -54,6 +59,8 @@ Default `true`. +--- + ### -enable-preview-policies Enables preview policies. This flag is deprecated. To enable OIDC Policies please use [-enable-oidc](#cmdoption-enable-oidc) instead. @@ -62,6 +69,8 @@ Default `false`. +--- + ### -enable-oidc Enables OIDC policies. @@ -70,13 +79,17 @@ Default `false`. -### -inlcude-year +--- + +### -include-year Adds year to log headers. Default `false`. -**NOTE**: This flag will be removed in release 2.7 and the year will be included by default. +{{< note >}} This flag will be removed in release 3.7 and the year will be included by default. {{< /note >}} + +--- ### -enable-leader-election @@ -87,6 +100,8 @@ See [-report-ingress-status](#cmdoption-report-ingress-status) flag. +--- + ### -enable-tls-passthrough Enable TLS Passthrough on port 443. @@ -95,6 +110,8 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). +--- + ### -tls-passthrough-port `` Set the port for TLS Passthrough. @@ -104,6 +121,8 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). +--- + ### -enable-cert-manager Enable x509 automated certificate management for VirtualServer resources using cert-manager (cert-manager.io). @@ -112,6 +131,8 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). +--- + ### -enable-external-dns Enable integration with ExternalDNS for configuring public DNS entries for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). @@ -119,6 +140,8 @@ Enable integration with ExternalDNS for configuring public DNS entries for Virtu Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). +--- + ### -external-service `` Specifies the name of the service with the type LoadBalancer through which the NGINX Ingress Controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. @@ -127,6 +150,8 @@ For Ingress resources only: Requires [-report-ingress-status](#cmdoption-report- +--- + ### -ingresslink `` Specifies the name of the IngressLink resource, which exposes the NGINX Ingress Controller pods via a BIG-IP system. The IP of the BIG-IP system is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. @@ -135,6 +160,8 @@ For Ingress resources only: Requires [-report-ingress-status](#cmdoption-report- +--- + ### -global-configuration `` A GlobalConfiguration resource for global configuration of NGINX Ingress Controller. @@ -145,6 +172,8 @@ Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). +--- + ### -health-status Adds a location "/nginx-health" to the default server. The location responds with the 200 status code for any request. @@ -153,12 +182,16 @@ Useful for external health-checking of NGINX Ingress Controller. +--- + ### -health-status-uri `` Sets the URI of health status location in the default server. Requires [-health-status](#cmdoption-health-status). (default `/nginx-health`) +--- + ### -ingress-class `` The `-ingress-class` argument refers to the name of the resource `kind: IngressClass`. An IngressClass resource with a name equal to the class must be deployed. Otherwise, NGINX Ingress Controller will fail to start. @@ -168,12 +201,16 @@ Default `nginx`. +--- + ### -ingress-template-path `` Path to the ingress NGINX configuration template for an ingress resource. Default for NGINX is `nginx.ingress.tmpl`; default for NGINX Plus is `nginx-plus.ingress.tmpl`. +--- + ### -leader-election-lock-name `` Specifies the name of the ConfigMap, within the same namespace as the controller, used as the lock for leader election. @@ -182,12 +219,16 @@ Requires [-enable-leader-election](#cmdoption-enable-leader-election). +--- + ### -log_backtrace_at `` When logging hits line `file:N`, emit a stack trace. +--- + ### -main-template-path `` Path to the main NGINX configuration template. @@ -197,6 +238,8 @@ Path to the main NGINX configuration template. +--- + ### -nginx-configmaps `` A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, but NGINX Ingress Controller is not able to fetch it from Kubernetes API, NGINX Ingress Controller will fail to start. @@ -205,18 +248,24 @@ Format: `/` +--- + ### -nginx-debug Enable debugging for NGINX. Uses the nginx-debug binary. Requires 'error-log-level: debug' in the ConfigMap. +--- + ### -nginx-plus Enable support for NGINX Plus. +--- + ### -nginx-reload-timeout `` Timeout in milliseconds which NGINX Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. @@ -225,6 +274,8 @@ Default is 60000. +--- + ### -nginx-status Enable the NGINX stub_status, or the NGINX Plus API. @@ -233,6 +284,8 @@ Default `true`. +--- + ### -nginx-status-allow-cidrs `` Add IP/CIDR blocks to the allow list for NGINX stub_status or the NGINX Plus API. @@ -241,6 +294,8 @@ Separate multiple IP/CIDR by commas. (default `127.0.0.1,::1`) +--- + ### -nginx-status-port `` Set the port where the NGINX stub_status or the NGINX Plus API is exposed. @@ -249,14 +304,20 @@ Format: `[1024 - 65535]` (default `8080`) +--- + ### -proxy `` -Use a proxy server to connect to Kubernetes API started by "kubectl proxy" command. **For testing purposes only**. +{{< warning >}} This argument is intended for testing purposes only. {{< /warning >}} + +Use a proxy server to connect to Kubernetes API started with `kubectl proxy`. NGINX Ingress Controller does not start NGINX and does not write any generated NGINX configuration files to disk. +--- + ### -report-ingress-status Updates the address field in the status of Ingress resources. @@ -265,6 +326,8 @@ Requires the [-external-service](#cmdoption-external-service) or [-ingresslink]( +--- + ### -transportserver-template-path `` Path to the TransportServer NGINX configuration template for a TransportServer resource. @@ -272,21 +335,26 @@ Path to the TransportServer NGINX configuration template for a TransportServer r - Default for NGINX is `nginx.transportserver.tmpl`. - Default for NGINX Plus is `nginx-plus.transportserver.tmpl`. - +--- + ### -v `` Log level for V logs. +--- + ### -version Print the version, git-commit hash and build date and exit. +--- + ### -virtualserver-template-path `` Path to the VirtualServer NGINX configuration template for a VirtualServer resource. @@ -297,36 +365,48 @@ Path to the VirtualServer NGINX configuration template for a VirtualServer resou +--- + ### -vmodule `` A comma-separated list of pattern=N settings for file-filtered logging. +--- + ### -watch-namespace `` Comma separated list of namespaces NGINX Ingress Controller should watch for resources. By default NGINX Ingress Controller watches all namespaces. Mutually exclusive with "watch-namespace-label". +--- + ### -watch-namespace-label `` Configures NGINX Ingress Controller to watch only those namespaces with label foo=bar. By default NGINX Ingress Controller watches all namespaces. Mutually exclusive with "watch-namespace". +--- + ### -watch-secret-namespace `` Comma separated list of namespaces NGINX Ingress Controller should watch for secrets. If this arg is not configured, NGINX Ingress Controller watches the same namespaces for all resources. See "watch-namespace" and "watch-namespace-label". +--- + ### -enable-prometheus-metrics Enables exposing NGINX or NGINX Plus metrics in the Prometheus format. +--- + ### -prometheus-metrics-listen-port `` Sets the port where the Prometheus metrics are exposed. @@ -335,6 +415,8 @@ Format: `[1024 - 65535]` (default `9113`) +--- + ### -prometheus-tls-secret `` A Secret with a TLS certificate and key for TLS termination of the Prometheus metrics endpoint. @@ -344,12 +426,16 @@ A Secret with a TLS certificate and key for TLS termination of the Prometheus me +--- + ### -enable-service-insight Exposes the Service Insight endpoint for Ingress Controller. +--- + ### -service-insight-listen-port `` Sets the port where the Service Insight is exposed. @@ -358,6 +444,8 @@ Format: `[1024 - 65535]` (default `9114`) +--- + ### -service-insight-tls-secret `` A Secret with a TLS certificate and key for TLS termination of the Service Insight endpoint. @@ -369,6 +457,8 @@ Format: `/` +--- + ### -spire-agent-address `` Specifies the address of a running Spire agent. **For use with NGINX Service Mesh only**. @@ -378,6 +468,8 @@ Specifies the address of a running Spire agent. **For use with NGINX Service Mes +--- + ### -enable-internal-routes Enable support for internal routes with NGINX Service Mesh. **For use with NGINX Service Mesh only**. @@ -386,9 +478,10 @@ Requires [-spire-agent-address](#cmdoption-spire-agent-address). - If the argument is set, but `spire-agent-address` is not provided, NGINX Ingress Controller will fail to start. - +--- + ### -enable-latency-metrics Enable collection of latency metrics for upstreams. @@ -396,6 +489,8 @@ Requires [-enable-prometheus-metrics](#cmdoption-enable-prometheus-metrics). +--- + ### -enable-app-protect Enables support for App Protect. @@ -404,9 +499,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus). - If the argument is set, but `nginx-plus` is set to false, NGINX Ingress Controller will fail to start. - +--- + ### -app-protect-log-level `` Sets log level for App Protect. Allowed values: fatal, error, warn, info, debug, trace. @@ -415,9 +511,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect](#cmdopti - If the argument is set, but `nginx-plus` and `enable-app-protect` are set to false, NGINX Ingress Controller will fail to start. - +--- + ### -enable-app-protect-dos Enables support for App Protect DoS. @@ -426,9 +523,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus). - If the argument is set, but `nginx-plus` is set to false, NGINX Ingress Controller will fail to start. - +--- + ### -app-protect-dos-debug Enable debugging for App Protect DoS. @@ -437,9 +535,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmd - If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. - +--- + ### -app-protect-dos-max-daemons Max number of ADMD instances. @@ -450,9 +549,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmd - If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. - +--- + ### -app-protect-dos-max-workers Max number of nginx processes to support. @@ -463,9 +563,10 @@ Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmd - If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. - +--- + ### -app-protect-dos-memory RAM memory size to consume in MB @@ -478,6 +579,8 @@ Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmd +--- + ### -ready-status Enables the readiness endpoint `/nginx-ready`. The endpoint returns a success code when NGINX has loaded all the config after the startup. @@ -486,12 +589,15 @@ Default `true`. +--- + ### -ready-status-port The HTTP port for the readiness endpoint. Format: `[1024 - 65535]` (default `8081`) +--- ### -disable-ipv6 @@ -501,6 +607,8 @@ Default `false`. +--- + ### -default-http-listener-port Sets the port for the HTTP `default_server` listener. @@ -509,6 +617,8 @@ Default `80`. +--- + ### -default-https-listener-port Sets the port for the HTTPS `default_server` listener. @@ -517,6 +627,8 @@ Default `443`. +--- + ### -ssl-dynamic-reload Used to activate or deactivate lazy loading for SSL Certificates. @@ -525,6 +637,8 @@ The default value is `true`. +--- + ### -weight-changes-dynamic-reload Enables the ability to change the weight distribution of two-way split clients without reloading NGINX. @@ -539,6 +653,8 @@ The default value is `false`. +--- + ### -enable-telemetry-reporting Enable gathering and reporting of software telemetry. @@ -547,6 +663,8 @@ The default value is `true`. +--- + ### -agent Enable NGINX Agent which can used with `-enable-app-protect` to send events to Security Monitoring. @@ -555,6 +673,8 @@ The default value is `false`. +--- + ### -agent-instance-group Specify the instance group name to use for the NGINX Ingress Controller deployment when using `-agent`. diff --git a/docs/content/configuration/global-configuration/configmap-resource.md b/docs/content/configuration/global-configuration/configmap-resource.md index bf306083c7..8eedab536e 100644 --- a/docs/content/configuration/global-configuration/configmap-resource.md +++ b/docs/content/configuration/global-configuration/configmap-resource.md @@ -2,16 +2,16 @@ docs: DOCS-586 doctypes: - '' -title: ConfigMap Resources +title: ConfigMap resources toc: true -weight: 1600 +weight: 300 --- -The ConfigMap Resources allows you to customize or fine tune NGINX behavior. Examples include setting the number of worker processes or customizing the access log format. +When using F5 NGINX Ingress Controller, you can customize or fine tune NGINX behavior using ConfigMap resources. Examples include setting the number of worker processes or customizing the access log format. ## Using ConfigMap -1. The [Installation with Manifests]({{< relref "/installation/installing-nic/installation-with-manifests.md" >}}) documentation deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress Controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use the [command-line arguments]({{< relref "/configuration/global-configuration/command-line-arguments" >}}) of NGINX Ingress Controller. +1. The [Installation with Manifests]({{< relref "installation/installing-nic/installation-with-manifests.md" >}}) documentation deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress Controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use the [command-line arguments]({{< relref "configuration/global-configuration/command-line-arguments" >}}) of NGINX Ingress Controller. 1. Create a ConfigMap file with the name *nginx-config.yaml* and set the values that make sense for your setup: @@ -32,164 +32,184 @@ that make sense for your setup: 1. Create a new (or update the existing) ConfigMap resource: - ``` + ```shell kubectl apply -f nginx-config.yaml ``` The NGINX configuration will be updated. -## ConfigMap and Ingress Annotations +--- + +## ConfigMap and Ingress annotations -Annotations allow you to configure advanced NGINX features and customize or fine tune NGINX behavior. +ConfigMap applies globally, meaning that it affects every Ingress resource. In contrast, annotations always apply to their Ingress resource. Annotations can override some ConfigMap keys: an example is that the `nginx.org/proxy-connect-timeout` annotations overrides the `proxy-connect-timeout` ConfigMap key. -The ConfigMap applies globally, meaning that it affects every Ingress resource. In contrast, annotations always apply to their Ingress resource. Annotations allow overriding some ConfigMap keys. For example, the `nginx.org/proxy-connect-timeout` annotations overrides the `proxy-connect-timeout` ConfigMap key. +For more information, view the [Advanced configuration with annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations" >}}) topic. -See the doc about [annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations). +--- -## ConfigMap and VirtualServer/VirtualServerRoute Resource +## ConfigMap and VirtualServer/VirtualServerRoute resources The ConfigMap affects every VirtualServer and VirtualServerRoute resources. However, the fields of those resources allow overriding some ConfigMap keys. For example, the `connect-timeout` field of the `upstream` overrides the `proxy-connect-timeout` ConfigMap key. -See the doc about [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources). +For more information, view the [VirtualServer and VirtualServerRoute resources]({{< relref "configuration/virtualserver-and-virtualserverroute-resources" >}}) topic. -## Summary of ConfigMap Keys +--- + +## ConfigMap keys -### Ingress Controller (Not Related to NGINX Configuration) +### Ingress Controller (Unrelated to NGINX Configuration) -{{% table %}} +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``external-status-address`` | Sets the address to be reported in the status of Ingress resources. Requires the ``-report-status`` command-line argument. Overrides the ``-external-service`` argument. | N/A | [Report Ingress Status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status). | -{{% /table %}} +|*external-status-address* | Sets the address to be reported in the status of Ingress resources. Requires the *-report-status* command-line argument. Overrides the *-external-service* argument. | N/A | [Reporting resource status]({{< relref "configuration/global-configuration/reporting-resources-status" >}}) | +{{}} -### General Customization +--- -{{% table %}} +### General customization + +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``proxy-connect-timeout`` | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | ``60s`` | | -|``proxy-read-timeout`` | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | ``60s`` | | -|``proxy-send-timeout`` | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | ``60s`` | | -|``client-max-body-size`` | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | ``1m`` | | -|``proxy-buffering`` | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | ``True`` | | -|``proxy-buffers`` | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | -|``proxy-buffer-size`` | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | -|``proxy-max-temp-file-size`` | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | ``1024m`` | | -|``set-real-ip-from`` | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | -|``real-ip-header`` | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | ``X-Real-IP`` | | -|``real-ip-recursive`` | Enables or disables the [real_ip_recursive](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | ``False`` | | -|``default-server-return`` | Configures the [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, ``default-server-return: 302 https://nginx.org`` will redirect a client to ``https://nginx.org``. | ``404`` | | -|``server-tokens`` | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | ``True`` | | -|``worker-processes`` | Sets the value of the [worker_processes](https://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | ``auto`` | | -|``worker-rlimit-nofile`` | Sets the value of the [worker_rlimit_nofile](https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | -|``worker-connections`` | Sets the value of the [worker_connections](https://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive. | ``1024`` | | -|``worker-cpu-affinity`` | Sets the value of the [worker_cpu_affinity](https://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity) directive. | N/A | | -|``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`` | | -|``map-hash-bucket-size`` | Sets the value of the [map_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size) directive.| ``256`` | | -|``map-hash-max-size`` | Sets the value of the [map_hash_max_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_max_size) directive. | ``2048`` | | -|``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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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. | ``75s`` | | -|``keepalive-requests`` | Sets the value of the [keepalive_requests](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests) directive. | ``1000`` | | -|``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`` | | -|``variables-hash-max-size`` | Sets the value of the [variables-hash-max-size](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_max_size) directive. | ``1024`` | | -{{% /table %}} +|*proxy-connect-timeout* | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | *60s* | | +|*proxy-read-timeout* | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | *60s* | | +|*proxy-send-timeout* | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | *60s* | | +|*client-max-body-size* | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | *1m* | | +|*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | +|*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | +|*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | +|*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | +|*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | +|*real-ip-recursive* | Enables or disables the [real_ip_recursive](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | *False* | | +|*default-server-return* | Configures the [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, *default-server-return: 302 https://nginx.org* will redirect a client to *https://nginx.org*. | *404* | | +|*server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | *True* | | +|*worker-processes* | Sets the value of the [worker_processes](https://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | *auto* | | +|*worker-rlimit-nofile* | Sets the value of the [worker_rlimit_nofile](https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | +|*worker-connections* | Sets the value of the [worker_connections](https://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive. | *1024* | | +|*worker-cpu-affinity* | Sets the value of the [worker_cpu_affinity](https://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity) directive. | N/A | | +|*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* | | +|*map-hash-bucket-size* | Sets the value of the [map_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size) directive.| *256* | | +|*map-hash-max-size* | Sets the value of the [map_hash_max_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_max_size) directive. | *2048* | | +|*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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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. | *75s* | | +|*keepalive-requests* | Sets the value of the [keepalive_requests](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests) directive. | *1000* | | +|*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* | | +|*variables-hash-max-size* | Sets the value of the [variables-hash-max-size](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_max_size) directive. | *1024* | | +{{}} + +--- ### Logging -{{% table %}} +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``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/v3.5.2/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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/v3.5.2/internal/configs/version1/nginx.tmpl). | | -|``stream-log-format-escaping`` | Sets the characters escaping for the variables of the stream log format. Supported values: ``json`` (JSON escaping), ``default`` (the default escaping) ``none`` (disables escaping). | ``default`` | | -{{% /table %}} - -### Request URI/Header Manipulation - -{{% table %}} +|*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/v3.5.2/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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/v3.5.2/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* | | +{{}} + +--- + +### Request URI/Header manipulation + +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``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 | | -|``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 | | -{{% /table %}} +|*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 | | +|*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 | | +{{}} + +--- ### Auth and SSL/TLS -{{% table %}} +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | -|``ssl-redirect`` | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | ``True`` | | -|``hsts`` | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) : the HSTS header is added to the responses from backends. The ``preload`` directive is included in the header. | ``False`` | | -|``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | | -|``hsts-include-subdomains`` | Adds the ``includeSubDomains`` directive to the HSTS header. | ``False`` | | -|``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`` | | -|``ssl-protocols`` | Sets the value of the [ssl_protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | ``TLSv1 TLSv1.1 TLSv1.2`` | | -|``ssl-prefer-server-ciphers`` | Enables or disables the [ssl_prefer_server_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | ``False`` | | -|``ssl-ciphers`` | Sets the value of the [ssl_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | ``HIGH:!aNULL:!MD5`` | | -|``ssl-dhparam-file`` | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file. | N/A | | -{{% /table %}} +|*redirect-to-https* | Sets the 301 redirect rule based on the value of the *http_x_forwarded_proto* header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | *False* | | +|*ssl-redirect* | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | *True* | | +|*hsts* | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) : the HSTS header is added to the responses from backends. The *preload* directive is included in the header. | *False* | | +|*hsts-max-age* | Sets the value of the *max-age* directive of the HSTS header. | *2592000* (1 month) | | +|*hsts-include-subdomains* | Adds the *includeSubDomains* directive to the HSTS header. | *False* | | +|*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* | | +|*ssl-protocols* | Sets the value of the [ssl_protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | *TLSv1 TLSv1.1 TLSv1.2* | | +|*ssl-prefer-server-ciphers* | Enables or disables the [ssl_prefer_server_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | *False* | | +|*ssl-ciphers* | Sets the value of the [ssl_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | *HIGH:!aNULL:!MD5* | | +|*ssl-dhparam-file* | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file. | N/A | | +{{}} + +--- ### Listeners -{{% table %}} +{{}} |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/v3.5.2/examples/shared-examples/proxy-protocol). | -{{% /table %}} +|*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/v3.5.2/examples/shared-examples/proxy-protocol). | +{{}} + +--- -### Backend Services (Upstreams) +### Backend services (Upstreams) -{{% table %}} +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``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"`` | | -|``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`` | | -|``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`` for NGINX, ``512k`` for NGINX Plus | | -|``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`` | | -|``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`` | | -{{% /table %}} +|*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"* | | +|*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* | | +|*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* for NGINX, *512k* for NGINX Plus | | +|*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* | | +|*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* | | +{{}} -### Snippets and Custom Templates +--- + +### Snippets and custom templates -{{% table %}} +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``main-snippets`` | Sets a custom snippet in main context. | N/A | | -|``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/v3.5.2/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). | -{{% /table %}} - -### Modules {#modules} - -{{% table %}} +|*main-snippets* | Sets a custom snippet in main context. | N/A | | +|*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/v3.5.2/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). | +{{}} + +--- + +### Modules + +{{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|``opentracing`` | Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs](/nginx-ingress-controller/third-party-modules/opentracing) for more information. | ``False`` | | -|``opentracing-tracer`` | Sets the path to the vendor tracer binary plugin. | N/A | | -|``opentracing-tracer-config`` | Sets the tracer configuration in JSON format. | N/A | | -|``app-protect-compressed-requests-action`` | Sets the ``app_protect_compressed_requests_action`` [global directive](/nginx-app-protect/configuration/#global-directives). | ``drop`` | | -|``app-protect-cookie-seed`` | Sets the ``app_protect_cookie_seed`` [global directive](/nginx-app-protect/configuration/#global-directives). | Random automatically generated string | | -|``app-protect-failure-mode-action`` | Sets the ``app_protect_failure_mode_action`` [global directive](/nginx-app-protect/configuration/#global-directives). | ``pass`` | | -|``app-protect-cpu-thresholds`` | Sets the ``app_protect_cpu_thresholds`` [global directive](/nginx-app-protect/configuration/#global-directives). | ``high=100 low=100`` | | -|``app-protect-physical-memory-util-thresholds`` | Sets the ``app_protect_physical_memory_util_thresholds`` [global directive](/nginx-app-protect/configuration/#global-directives). | ``high=100 low=100`` | | +|*opentracing* | Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs](/nginx-ingress-controller/third-party-modules/opentracing) for more information. | *False* | | +|*opentracing-tracer* | Sets the path to the vendor tracer binary plugin. | N/A | | +|*opentracing-tracer-config* | Sets the tracer configuration in JSON format. | N/A | | +|*app-protect-compressed-requests-action* | Sets the *app_protect_compressed_requests_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *drop* | | +|*app-protect-cookie-seed* | Sets the *app_protect_cookie_seed* [global directive](/nginx-app-protect/configuration/#global-directives). | Random automatically generated string | | +|*app-protect-failure-mode-action* | Sets the *app_protect_failure_mode_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *pass* | | +|*app-protect-cpu-thresholds* | Sets the *app_protect_cpu_thresholds* [global directive](/nginx-app-protect/configuration/#global-directives). | *high=100 low=100* | | +|*app-protect-physical-memory-util-thresholds* | Sets the *app_protect_physical_memory_util_thresholds* [global directive](/nginx-app-protect/configuration/#global-directives). | *high=100 low=100* | | |`app-protect-reconnect-period-seconds` | Sets the `app_protect_reconnect_period_seconds` [global directive](/nginx-app-protect/configuration/#global-directives). | `5` | | -|``app-protect-dos-log-format`` | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for Dos Access log 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. | `, vs_name_al=$app_protect_dos_vs_name, ip=$remote_addr, tls_fp=$app_protect_dos_tls_fp, outcome=$app_protect_dos_outcome, reason=$app_protect_dos_outcome_reason, policy_name=$app_protect_dos_policy_name, dos_version=$app_protect_dos_version, ip_tls=$remote_addr:$app_protect_dos_tls_fp,` | | -|``app-protect-dos-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`` | | -|``app-protect-dos-arb-fqdn`` | Sets the ``app-protect-dos-arb-fqdn`` [directive](/nginx-app-protect-dos/directives-and-policy/learn-about-directives-and-policy/#arbitrator-fqdn-directive-app_protect_dos_arb_fqdn). | ``svc-appprotect-dos-arb`` | | -{{% /table %}} +|*app-protect-dos-log-format* | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for Dos Access log 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. | `, vs_name_al=$app_protect_dos_vs_name, ip=$remote_addr, tls_fp=$app_protect_dos_tls_fp, outcome=$app_protect_dos_outcome, reason=$app_protect_dos_outcome_reason, policy_name=$app_protect_dos_policy_name, dos_version=$app_protect_dos_version, ip_tls=$remote_addr:$app_protect_dos_tls_fp,` | | +|*app-protect-dos-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* | | +|*app-protect-dos-arb-fqdn* | Sets the *app-protect-dos-arb-fqdn* [directive](/nginx-app-protect-dos/directives-and-policy/learn-about-directives-and-policy/#arbitrator-fqdn-directive-app_protect_dos_arb_fqdn). | *svc-appprotect-dos-arb* | | +{{}} diff --git a/docs/content/configuration/global-configuration/custom-templates.md b/docs/content/configuration/global-configuration/custom-templates.md index 0503b25ea1..60c391c578 100644 --- a/docs/content/configuration/global-configuration/custom-templates.md +++ b/docs/content/configuration/global-configuration/custom-templates.md @@ -2,10 +2,10 @@ docs: DOCS-587 doctypes: - '' -title: Custom Templates +title: Custom templates toc: true -weight: 1800 +weight: 500 --- -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/v3.5.2/examples/shared-examples/custom-templates). +F5 NGINX 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/v3.5.2/examples/shared-examples/custom-templates). diff --git a/docs/content/configuration/global-configuration/globalconfiguration-resource.md b/docs/content/configuration/global-configuration/globalconfiguration-resource.md index 33830af896..b91c7ee1c4 100644 --- a/docs/content/configuration/global-configuration/globalconfiguration-resource.md +++ b/docs/content/configuration/global-configuration/globalconfiguration-resource.md @@ -2,21 +2,26 @@ docs: DOCS-588 doctypes: - '' -title: GlobalConfiguration Resource +title: GlobalConfiguration resource toc: true -weight: 2000 +weight: 200 --- -The GlobalConfiguration resource allows you to define the global configuration parameters of NGINX Ingress Controller. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +This page explains how to use the GlobalConfiguration resource to define the global configuration parameters of F5 NGINX Ingress Controller. -The resource supports configuring listeners for TCP and UDP load balancing. Listeners are required by [TransportServer resources]({{< relref "/configuration/transportserver-resource.md" >}}) and -can be used to [configure custom listeners for VirtualServers]({{< relref "tutorials/virtual-server-with-custom-listener-ports" >}}). +The resource supports configuring listeners for TCP and UDP load balancing, and is implemented as a [Custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +Listeners are required by [TransportServer resources]({{< relref "/configuration/transportserver-resource.md" >}}) and can be used to [configure custom listeners for VirtualServers]({{< relref "tutorials/virtual-server-with-custom-listener-ports.md" >}}). + +--- ## Prerequisites When [installing NGINX Ingress Controller using Manifests]({{< relref "/installation/installing-nic/installation-with-manifests.md" >}}), you need to reference a GlobalConfiguration resource in the [`-global-configuration`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-global-configuration) command-line argument. NGINX Ingress Controller only needs one GlobalConfiguration resource. -## GlobalConfiguration Specification +--- + +## GlobalConfiguration specification The GlobalConfiguration resource defines the global configuration parameters of the Ingress Controller. Below is an example: @@ -43,11 +48,11 @@ spec: ssl: true ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | -|``listeners`` | A list of listeners. | [[]listener](#listener) | No | -{{% /table %}} +| *listeners* | A list of listeners. | [listener](#listener) | No | +{{}} ### Listener @@ -62,14 +67,16 @@ The `listeners:` key defines a listener (a combination of a protocol and a port) protocol: HTTP ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | -|``name`` | The name of the listener. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``listener-123`` are valid. The name must be unique among all listeners. The name ``tls-passthrough`` is reserved for the built-in TLS Passthrough listener and cannot be used. | ``string`` | Yes | -|``port`` | The port of the listener. The port must fall into the range ``1..65535`` with the following exceptions: ``80``, ``443``, the [status port](/nginx-ingress-controller/logging-and-monitoring/status-page), the [Prometheus metrics port](/nginx-ingress-controller/logging-and-monitoring/prometheus). Among all listeners, only a single combination of a port-protocol is allowed. | ``int`` | Yes | -|``protocol`` | The protocol of the listener. Supported values: ``TCP``, ``UDP`` and ``HTTP``. | ``string`` | Yes | -|``ssl`` | Configures the listener with SSL. This is currently only supported for ``HTTP`` listeners. Default value is ``false`` | ``bool`` | No | -{{% /table %}} +| *name* | The name of the listener. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``listener-123`` are valid. The name must be unique among all listeners. The name ``tls-passthrough`` is reserved for the built-in TLS Passthrough listener and cannot be used. | *string* | Yes | +| *port* | The port of the listener. The port must fall into the range ``1..65535`` with the following exceptions: ``80``, ``443``, the [status port](/nginx-ingress-controller/logging-and-monitoring/status-page), the [Prometheus metrics port](/nginx-ingress-controller/logging-and-monitoring/prometheus). Among all listeners, only a single combination of a port-protocol is allowed. | *int* | Yes | +| *protocol* | The protocol of the listener. Supported values: ``TCP``, ``UDP`` and ``HTTP``. | *string* | Yes | +| *ssl* | Configures the listener with SSL. This is currently only supported for ``HTTP`` listeners. Default value is ``false`` | *bool* | No | +{{}} + +--- ## Using GlobalConfiguration @@ -79,6 +86,8 @@ For example, the following command creates a GlobalConfiguration resource define ```shell kubectl apply -f global-configuration.yaml +``` +```shell globalconfiguration.k8s.nginx.org/nginx-configuration created ``` @@ -86,20 +95,25 @@ Assuming the namespace of the resource is `nginx-ingress`, you can get the resou ```shell kubectl get globalconfiguration nginx-configuration -n nginx-ingress +``` +```shell NAME AGE nginx-configuration 13s ``` -In the kubectl get and similar commands, you can also use the short name `gc` instead of `globalconfiguration`. +With `kubectl get` and similar commands, you can use the short name `gc` instead of `globalconfiguration`. + +--- ### Validation Two types of validation are available for the GlobalConfiguration resource: -- *Structural validation* by the `kubectl` and Kubernetes API server. -- *Comprehensive validation* by the Ingress Controller. +- *Structural validation* by `kubectl` and Kubernetes API server. +- *Comprehensive validation* by NGINX Ingress Controller. + -#### Structural Validation +#### Structural validation The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type of every field of the resource. @@ -107,43 +121,50 @@ If you try to create (or update) a resource that violates the structural schema - Example of `kubectl` validation: + ```shell + kubectl apply -f global-configuration.yaml ``` - $ kubectl apply -f global-configuration.yaml + ```text error: error validating "global-configuration.yaml": error validating data: ValidationError(GlobalConfiguration.spec.listeners[0].port): invalid type for org.nginx.k8s.v1.GlobalConfiguration.spec.listeners.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false ``` - Example of Kubernetes API server validation: + ```shell + kubectl apply -f global-configuration.yaml --validate=false ``` - $ kubectl apply -f global-configuration.yaml --validate=false - The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: - spec.listeners.port in body must be of type integer: "string" + ```text + The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.listeners.port in body must be of type integer: "string" ``` -If a resource is not rejected (it doesn't violate the structural schema), the Ingress Controller will validate it further. +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. -#### Comprehensive Validation +#### Comprehensive validation -The Ingress Controller validates the fields of a GlobalConfiguration resource. If a GlobalConfiguration resource is partially invalid, the Ingress Controller use the valid listeners and emit events about invalid listeners. +NGINX Ingress Controller validates the fields of a GlobalConfiguration resource. If a GlobalConfiguration resource is partially invalid, NGINX Ingress Controller use the valid listeners and emit events about invalid listeners. You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration. For our `nginx-configuration` GlobalConfiguration, we can run: ```shell kubectl describe gc nginx-configuration -n nginx-ingress -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Updated 11s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration was updated ``` -Note how the events section includes a Normal event with the Updated reason that informs us that the configuration was successfully applied. +The events section includes a Normal event with the Updated reason that informs us that the configuration was successfully applied. If you create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53, you will get: ```shell kubectl describe gc nginx-configuration -n nginx-ingress -. . . +``` +```text Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -151,4 +172,4 @@ Events: Warning AddedOrUpdatedWithError 6s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration is invalid and was rejected: spec.listeners: Duplicate value: "Duplicated port/protocol combination 53/UDP" ``` -Note how the events section includes a Warning event with the AddedOrUpdatedWithError reason. +The events section includes a Warning event with the AddedOrUpdatedWithError reason. diff --git a/docs/content/configuration/global-configuration/reporting-resources-status.md b/docs/content/configuration/global-configuration/reporting-resources-status.md index 4c75281d60..8e36733ebf 100644 --- a/docs/content/configuration/global-configuration/reporting-resources-status.md +++ b/docs/content/configuration/global-configuration/reporting-resources-status.md @@ -2,40 +2,48 @@ docs: DOCS-589 doctypes: - '' -title: Reporting Resources Status +title: Reporting resource status toc: true -weight: 1900 +weight: 600 --- -## Ingress Resources +This page describes how to view the status of resources managed by F5 NGINX Ingress Controller. + +## Ingress resources + +An Ingress resource status includes the address (an IP address or a DNS name), through which the hosts of that Ingress resource are publicly accessible. -An Ingress resource can have a status that includes the address (an IP address or a DNS name), through which the hosts of that Ingress resource are publicly accessible. You can see the address in the output of the `kubectl get ingress` command, in the ADDRESS column, as shown below: ```shell -$ kubectl get ingresses +kubectl get ingresses +``` +```text NAME HOSTS ADDRESS PORTS AGE cafe-ingress cafe.example.com 12.13.23.123 80, 443 2m ``` -The Ingress Controller must be configured to report an Ingress status: +NGINX Ingress Controller must be configured to report an Ingress status: 1. Use the command-line flag `-report-ingress-status`. -2. Define a source for an external address. This can be either of: +1. Define a source for an external address. This can be either of: 1. A user defined address, specified in the `external-status-address` ConfigMap key. - 2. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. + 1. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. -See the docs about [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). +View the [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) topics for more information. -Notes: NGINX Ingress Controller does not clear the status of Ingress resources when it is being shut down. +{{< note >}} NGINX Ingress Controller does not clear the status of Ingress resources when it is being shut down. {{< /note >}} -## VirtualServer and VirtualServerRoute Resources +## VirtualServer and VirtualServerRoute resources A VirtualServer or VirtualServerRoute resource includes the status field with information about the state of the resource and the IP address, through which the hosts of that resource are publicly accessible. + You can see the status in the output of the `kubectl get virtualservers` or `kubectl get virtualserverroutes` commands as shown below: ```shell kubectl get virtualservers +``` +```text NAME STATE HOST IP PORTS AGE cafe Valid cafe.example.com 12.13.23.123 [80,443] 34s ``` @@ -44,17 +52,21 @@ To see an external hostname address associated with a VirtualServer resource, us ```shell kubectl get virtualservers -o wide +``` +```text NAME STATE HOST IP EXTERNALHOSTNAME PORTS AGE cafe Valid cafe.example.com ae430f41a1a0042908655abcdefghijkl-12345678.eu-west-2.elb.amazonaws.com [80,443] 106s ``` -> Note: If there are multiple addresses, only the first one is shown. +{{< note >}} If there are multiple addresses, only the first one is shown. {{< /note >}} In order to see additional addresses or extra information about the `Status` of the resource, use the following command: ```shell kubectl describe virtualserver -. . . +``` +```text +... Status: External Endpoints: Ip: 12.13.23.123 @@ -64,54 +76,57 @@ Status: State: Valid ``` -### Status Specification +### Status specification The following fields are reported in both VirtualServer and VirtualServerRoute status: -{{% table %}} +{{}} |Field | Description | Type | | ---| ---| --- | -|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` an ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | -|``Reason`` | The reason of the last update. | ``string`` | -|``Message`` | Additional information about the state. | ``string`` | -|``ExternalEndpoints`` | A list of external endpoints for which the hosts of the resource are publicly accessible. | [[]externalEndpoint](#externalendpoint) | -{{% /table %}} +|*State* | Current state of the resource. Can be ``Valid``, ``Warning`` an ``Invalid``. For more information, refer to the ``message`` field. | *string* | +|*Reason* | The reason of the last update. | *string* | +|*Message* | Additional information about the state. | *string* | +|*ExternalEndpoints* | A list of external endpoints for which the hosts of the resource are publicly accessible. | *[externalEndpoint](#externalendpoint)* | +{{}} -The following field is reported in the VirtualServerRoute status only: +The *ReferencedBy* field is reported for the VirtualServerRoute status only: -{{% table %}} +{{}} |Field | Description | Type | | ---| ---| --- | -|``ReferencedBy`` | The VirtualServer that references this VirtualServerRoute. Format is ``namespace/name`` | ``string`` | -{{% /table %}} +| *ReferencedBy* | The VirtualServer that references this VirtualServerRoute. Format as ``namespace/name`` | *string* | +{{}} -### ExternalEndpoint +### externalEndpoint -{{% table %}} +{{}} |Field | Description | Type | | ---| ---| --- | |``IP`` | The external IP address. | ``string`` | |``Hostname`` | The external LoadBalancer Hostname address. | ``string`` | |``Ports`` | A list of external ports. | ``string`` | -{{% /table %}} +{{}} -The Ingress Controller must be configured to report a VirtualServer or VirtualServerRoute status: +NGINX Ingress Controller must be configured to report a VirtualServer or VirtualServerRoute status: -1. If you want the Ingress Controller to report the `externalEndpoints`, define a source for an external address (Note: the rest of the fields will be reported without the external address configured). This can be either of: +1. If you want NGINX Ingress Controller to report the `externalEndpoints`, define a source for an external address (The rest of the fields will be reported without the external address configured). This can be: 1. A user defined address, specified in the `external-status-address` ConfigMap key. - 2. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. + 1. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. -See the docs about [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments). +View the [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) topics for more information. -Notes: The Ingress Controller does not clear the status of VirtualServer and VirtualServerRoute resources when it is being shut down. +{{< note >}} NGINX Ingress Controller does not clear the status of VirtualServer and VirtualServerRoute resources when it is being shut down. {{< /note >}} -## Policy Resources +## Policy resources A Policy resource includes the status field with information about the state of the resource. + You can see the status in the output of the `kubectl get policy` command as shown below: ```shell kubectl get policy +``` +```text NAME STATE AGE webapp-policy Valid 30s ``` @@ -120,55 +135,61 @@ In order to see additional addresses or extra information about the `Status` of ```shell kubectl describe policy -. . . +``` +```text +... Status: Message: Configuration for default/webapp-policy was added or updated Reason: AddedOrUpdated State: Valid ``` -### Status Specification +### Status specification The following fields are reported in Policy status: -{{% table %}} +{{}} |Field | Description | Type | | ---| ---| --- | |``State`` | Current state of the resource. Can be ``Valid`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | |``Reason`` | The reason of the last update. | ``string`` | |``Message`` | Additional information about the state. | ``string`` | -{{% /table %}} +{{}} -## TransportServer Resources +## TransportServer resources A TransportServer resource includes the status field with information about the state of the resource. + You can see the status in the output of the `kubectl get transportserver` command as shown below: ```shell kubectl get transportserver +``` +```text NAME STATE REASON AGE dns-tcp Valid AddedOrUpdated 47m ``` -In order to see additional addresses or extra information about the `Status` of the resource, use the following command: +To see additional addresses or extra information about the `Status` of the resource, use the following command: ```shell kubectl describe transportserver -. . . +``` +```text Status: Message: Configuration for default/dns-tcp was added or updated Reason: AddedOrUpdated State: Valid ``` -### Status Specification +### Status specification The following fields are reported in TransportServer status: -{{% table %}} +{{}} |Field | Description | Type | | ---| ---| --- | -|``State`` | Current state of the resource. Can be ``Valid``, ``Warning`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | -|``Reason`` | The reason of the last update. | ``string`` | -|``Message`` | Additional information about the state. | ``string`` | -{{% /table %}} +| *State* | Current state of the resource. Can be ``Valid``, ``Warning`` or ``Invalid``. For more information, refer to the ``message`` field. | *string* | +| *Reason* | The reason of the last update. | *string* | +| *Message* | Additional information about the state. | *string* | +{{}} diff --git a/docs/content/configuration/handling-host-and-listener-collisions.md b/docs/content/configuration/host-and-listener-collisions.md similarity index 53% rename from docs/content/configuration/handling-host-and-listener-collisions.md rename to docs/content/configuration/host-and-listener-collisions.md index a7f2a9d767..052d60291f 100644 --- a/docs/content/configuration/handling-host-and-listener-collisions.md +++ b/docs/content/configuration/host-and-listener-collisions.md @@ -2,27 +2,33 @@ docs: DOCS-590 doctypes: - '' -title: Handling Host and Listener Collisions +title: Host and Listener collisions toc: true weight: 1700 --- -This document explains how NGINX Ingress Controller handles host and listener collisions among resources. +This document explains how F5 NGINX Ingress Controller handles host and listener collisions between resources. + +--- ## Winner Selection Algorithm -If multiple resources contend for the same host/listener, the Ingress Controller will pick the winner based on the `creationTimestamp` of the resources: the oldest resource will win. In case there are more than one oldest resource (their `creationTimestamp` is the same), the Ingress Controller will choose the resource with the lexicographically smallest `uid`. +If multiple resources contend for the same host or listener, NGINX Ingress Controller will pick the winner based on the `creationTimestamp` of the resources: the oldest resource will win. In case there are more than one oldest resource (their `creationTimestamp` is the same), NGINX Ingress Controller will choose the resource with the lexicographically smallest `uid`. + +{{< note >}} The `creationTimestamp` and `uid` fields are part of the [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta) resource. {{< /note >}} -Note: the `creationTimestamp` and `uid` fields are part of the resource [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta). +--- + +## Host collisions -## Host Collisions +A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. NGINX Ingress Controller has two strategies for handling host collisions: -A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. The Ingress Controller supports two options for handling host collisions: +- Choosing a single "winner" resource to handle the host. +- Merging the configuration of the conflicting resources. -- Choosing the winner so that only one resource handles the host. -- Merging configuration of the conflicting resources. +--- -### Choosing the Winner +### Choosing the winner Consider the following two resources: @@ -52,16 +58,17 @@ Consider the following two resources: . . . ``` -If a user creates both resources in the cluster, a host collision will occur. As a result, the Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). +If a user creates both resources in the cluster, a host collision will occur. NGINX Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). -In our example, if `cafe-virtual-server` was created first, it will win the host `cafe.example.com` and the Ingress Controller will reject `cafe-ingress`. This will be reflected in the events and in the resource's status field: +If `cafe-virtual-server` was created first, it will win the host `cafe.example.com` and NGINX Ingress Controller will reject `cafe-ingress`. This will be reflected in the events and in the resource's status field: ```shell kubectl describe vs cafe-virtual-server - -. . . +``` +```text +... Status: - . . . + ... Message: Configuration for default/cafe-virtual-server was added or updated Reason: AddedOrUpdated State: Valid @@ -69,32 +76,47 @@ Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 9s nginx-ingress-controller Configuration for default/cafe-virtual-server was added or updated +``` -$ kubectl describe ingress cafe-ingress -. . . +```shell +kubectl describe ingress cafe-ingress +``` +```text Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Rejected 66s nginx-ingress-controller All hosts are taken by other resources ``` -> Note: You can configure multiple hosts for Ingress resources. As a result, it's possible that an Ingress resource can be the winner for some of its hosts and a loser for the others. For example, if `cafe-ingress` had an additional rule host rule -- `pub.example.com` -- the Ingress Controller would not reject the Ingress. Rather, it would allow `cafe-ingress` to handle `pub.example.com`. +Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` and NGINX Ingress Controller will reject `cafe-virtual-server`. -Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` and the Ingress Controller will reject `cafe-virtual-server`. +{{< note >}} You can configure multiple hosts for Ingress resources, and its possible that an Ingress resource can be the winner for some of its hosts and a loser for the others. -### Merging Configuration for the Same Host +For example, if `cafe-ingress` had an additional rule host rule for `pub.example.com`, NGINX Ingress Controller would not reject the Ingress. Instead, it would allow `cafe-ingress` to handle `pub.example.com`. {{< /note >}} -It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. See the [Cross-namespace Configuration](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/) doc for more information. +--- + +### Merging configuration for the same host + +It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. + +The [Cross-namespace configuration]({{< relref "configuration/ingress-resources/cross-namespace-configuration.md">}}) topic has more information. It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources/cross-namespace-configuration) on GitHub. It is *not* possible to merge configuration for multiple TransportServer resources. -## Listener Collisions +--- + +## Listener collisions -Listener collisions occur when multiple TransportServer resources (configured for TCP/UDP load balancing) configure the same `listener`. The Ingress Controller will choose the winner, which will own the listener. +Listener collisions occur when multiple TransportServer resources (Configured for TCP/UDP load balancing) target the same `listener`. -### Choosing the Winner +NGINX Ingress Controller will choose the winner, which will own the listener. + +--- + +### Choosing the winner Consider the following two resources: @@ -126,18 +148,19 @@ Consider the following two resources: . . . ``` -If a user creates both resources in the cluster, a listener collision will occur. As a result, the Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). +If a user creates both resources in the cluster, a listener collision will occur. As a result, NGINX Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). -In our example, if `tcp-1` was created first, it will win the listener `dns-tcp` and the Ingress Controller will reject `tcp-2`. This will be reflected in the events and in the resource's status field: +In our example, if `tcp-1` was created first, it will win the listener `dns-tcp` and NGINX Ingress Controller will reject `tcp-2`. This will be reflected in the events and in the resource's status field: ```shell kubectl describe ts tcp-2 - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning Rejected 10s nginx-ingress-controller Listener dns-tcp is taken by another resource ``` -Similarly, if `tcp-2` was created first, it will win `dns-tcp` and the Ingress Controller will reject `tcp-1`. +Similarly, if `tcp-2` was created first, it will win `dns-tcp` and NGINX Ingress Controller will reject `tcp-1`. diff --git a/docs/content/configuration/ingress-resources/_index.md b/docs/content/configuration/ingress-resources/_index.md index 32bdae29ad..8a2b5b282f 100644 --- a/docs/content/configuration/ingress-resources/_index.md +++ b/docs/content/configuration/ingress-resources/_index.md @@ -1,7 +1,7 @@ --- -title: Ingress Resources +title: Ingress resources description: -weight: 1500 +weight: 200 menu: docs: parent: NGINX Ingress Controller 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 c5a6f21ad7..778f8105e9 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -2,16 +2,18 @@ docs: DOCS-591 doctypes: - '' -title: Advanced Configuration with Annotations +title: Advanced configuration with Annotations toc: true -weight: 1700 +weight: 200 --- -This document explains how to enable advanced features with Annotations. +This topic explains how to enable advanced features in F5 NGINX Ingress Controller with Annotations. -The Ingress resource can only use basic NGINX features such as host or path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers can be enabled with Annotations. Outside of advanced features, Annotations are necessary for customizing NGINX behavior such as setting the value of connection timeouts. +The Ingress resource can use basic NGINX features such as host or path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers can be enabled with Annotations. -Customization is also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md" >}}): Annotations take priority over the ConfigMap. +Outside of advanced features, Annotations are necessary for customizing NGINX behavior such as setting the value of connection timeouts. + +Customization is also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md" >}}) resources: Annotations take priority. ## Using Annotations @@ -53,28 +55,29 @@ spec: ## Validation -NGINX Ingress Controller validates the annotations of Ingress resources. If an Ingress is invalid, NGINX Ingress Controller will reject it: the Ingress will continue to exist in the cluster, but the Ingress Controller will ignore it. +NGINX Ingress Controller validates the annotations of Ingress resources. If an Ingress is invalid, NGINX Ingress Controller will reject it: the Ingress will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. -You can check if the Ingress Controller successfully applied the configuration for an Ingress. For our example `cafe-ingress-with-annotations` Ingress, we can run: +You can check if NGINX Ingress Controller successfully applied the configuration for an Ingress resource. For the example `cafe-ingress-with-annotations` Ingress, you can run: ```shell kubectl describe ing cafe-ingress-with-annotations - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal AddedOrUpdated 3s nginx-ingress-controller Configuration for default/cafe-ingress-with-annotations was added or updated ``` -Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. +The events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. -If you create an invalid Ingress, the Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress `cafe-ingress-with-annotations`, with an annotation `nginx.org/redirect-to-https` set to `yes please` instead of `true`, you will get: +If you create an invalid Ingress, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress `cafe-ingress-with-annotations`, with an annotation `nginx.org/redirect-to-https` set to `yes please` instead of `true`, you will get: ```shell kubectl describe ing cafe-ingress-with-annotations - -. . . +``` +```text Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -83,141 +86,139 @@ Events: Note how the events section includes a Warning event with the Rejected reason. -**Note**: If you make an existing Ingress invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX. - -The following Ingress annotation currently has limited validation: +{{< note >}} If you make an existing Ingress invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. {{< /note >}} -- `nginx.com/jwt-token`. +The `nginx.com/jwt-token` Ingress annotation has limited validation. ## Summary of Annotations The table below summarizes the available annotations. -**Note**: The annotations that start with `nginx.com` are only supported with NGINX Plus. +{{< note >}} Annotations that start with `nginx.com` are only supported with NGINX Plus. {{< /note >}} -### General Customization +### General customization -{{% table %}} +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/proxy-connect-timeout`` | ``proxy-connect-timeout`` | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | ``60s`` | | -|``nginx.org/proxy-read-timeout`` | ``proxy-read-timeout`` | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | ``60s`` | | -|``nginx.org/proxy-send-timeout`` | ``proxy-send-timeout`` | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | ``60s`` | | -|``nginx.org/client-max-body-size`` | ``client-max-body-size`` | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | ``1m`` | | -|``nginx.org/proxy-buffering`` | ``proxy-buffering`` | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | ``True`` | | -|``nginx.org/proxy-buffers`` | ``proxy-buffers`` | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | -|``nginx.org/proxy-buffer-size`` | ``proxy-buffer-size`` | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | -|``nginx.org/proxy-max-temp-file-size`` | ``proxy-max-temp-file-size`` | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | ``1024m`` | | -|``nginx.org/server-tokens`` | ``server-tokens`` | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | ``True`` | | -|``nginx.org/path-regex`` | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [Path Regex](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/path-regex). | -{{% /table %}} +| *nginx.org/proxy-connect-timeout* | *proxy-connect-timeout* | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | *60s* | | +| *nginx.org/proxy-read-timeout* | *proxy-read-timeout* | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | *60s* | | +| *nginx.org/proxy-send-timeout* | *proxy-send-timeout* | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | *60s* | | +| *nginx.org/client-max-body-size* | *client-max-body-size* | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | *1m* | | +| *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | +| *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | +| *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | +| *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. | *True* | | +| *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/path-regex) | +{{}} ### Request URI/Header Manipulation -{{% table %}} +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``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/v3.5.2/examples/ingress-resources/rewrites). | -{{% /table %}} +| *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](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/rewrites) | +{{}} ### Auth and SSL/TLS -{{% table %}} +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/redirect-to-https`` | ``redirect-to-https`` | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto`` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | ``False`` | | -|``ingress.kubernetes.io/ssl-redirect`` | ``ssl-redirect`` | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | ``True`` | | -|``nginx.org/hsts`` | ``hsts`` | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/)\ : the HSTS header is added to the responses from backends. The ``preload`` directive is included in the header. | ``False`` | | -|``nginx.org/hsts-max-age`` | ``hsts-max-age`` | Sets the value of the ``max-age`` directive of the HSTS header. | ``2592000`` (1 month) | | -|``nginx.org/hsts-include-subdomains`` | ``hsts-include-subdomains`` | Adds the ``includeSubDomains`` directive to the HSTS header. | ``False`` | | -|``nginx.org/hsts-behind-proxy`` | ``hsts-behind-proxy`` | Enables HSTS based on the value of the ``http_x_forwarded_proto`` request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https`` annotation. | ``False`` | | -|``nginx.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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/examples/ingress-resources/jwt). | -{{% /table %}} +| *nginx.org/redirect-to-https* | *redirect-to-https* | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto* header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of NGINX Ingress Controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | *False* | | +| *ingress.kubernetes.io/ssl-redirect* | *ssl-redirect* | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | *True* | | +| *nginx.org/hsts* | *hsts* | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/)\ : the HSTS header is added to the responses from backends. The ``preload* directive is included in the header. | *False* | | +| *nginx.org/hsts-max-age* | *hsts-max-age* | Sets the value of the ``max-age* directive of the HSTS header. | *2592000* (1 month) | | +| *nginx.org/hsts-include-subdomains* | *hsts-include-subdomains* | Adds the ``includeSubDomains* directive to the HSTS header. | *False* | | +| *nginx.org/hsts-behind-proxy* | *hsts-behind-proxy* | Enables HSTS based on the value of the ``http_x_forwarded_proto* request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of NGINX 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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/examples/ingress-resources/jwt). | +{{}} ### Listeners -{{% table %}} +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/listen-ports`` | N/A | Configures HTTP ports that NGINX will listen on. | ``[80]`` | | -|``nginx.org/listen-ports-ssl`` | N/A | Configures HTTPS ports that NGINX will listen on. | ``[443]`` | | -{{% /table %}} +| *nginx.org/listen-ports* | N/A | Configures HTTP ports that NGINX will listen on. | *[80]* | | +| *nginx.org/listen-ports-ssl* | N/A | Configures HTTPS ports that NGINX will listen on. | *[443]* | | +{{}} -### Backend Services (Upstreams) +### Backend services (Upstreams) -{{% table %}} +{{}} |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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/examples/ingress-resources/health-checks). | ``"0s"`` | | -|``nginx.org/use-cluster-ip`` | N/A | 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 NGINX Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | ``False`` | | -{{% /table %}} +| *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](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/grpc-services) | +| *nginx.org/websocket-services* | N/A | Enables WebSocket for services. | N/A | [websocket](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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/v3.5.2/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* | [health-checks](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/health-checks) | +| *nginx.com/health-checks-mandatory* | N/A | Configures active health checks as mandatory. | *False* | [health-checks](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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* | [health-checks](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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/v3.5.2/examples/ingress-resources/health-checks). | *"0s"* | | +| *nginx.org/use-cluster-ip* | N/A | 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 NGINX Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | *False* | | +{{}} ### Rate limiting -{{% table %}} +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/limit-req-rate`` | N/A | Enables request-rate-limiting for this ingress by creating a [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) and matching [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) for each location. All servers/locations of one ingress share the same zone. Must have unit r/s or r/m. | N/A | 200r/s | -|``nginx.org/limit-req-key`` | N/A | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ${}. | ${binary_remote_addr} | ${binary_remote_addr} | -|``nginx.org/limit-req-zone-size`` | N/A | Configures the size of the created [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). | 10m | 20m | -|``nginx.org/limit-req-delay`` | N/A | Configures the delay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | 0 | 100 | -|``nginx.org/limit-req-no-delay`` | N/A | Configures the nodelay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | false | true | -|``nginx.org/limit-req-burst`` | N/A | Configures the burst-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | N/A | 100 | -|``nginx.org/limit-req-dry-run`` | N/A | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the number of excessive requests is accounted as usual in the shared memory zone. | false | true | -|``nginx.org/limit-req-log-level`` | N/A | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are info, notice, warn or error. | error | info | -|``nginx.org/limit-req-reject-code`` | N/A | Sets the status code to return in response to rejected requests. Must fall into the range 400..599. | 429 | 503 | -|``nginx.org/limit-req-scale`` | N/A | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. Note: This will not work properly if requests from a client are not evenly distributed accross all ingress pods (sticky sessions, long lived TCP-Connections with many requests etc.). In such cases using NGINX+'s zone-sync feature instead would give better results. | false | true | -{{% /table %}} - -### Snippets and Custom Templates - -{{% table %}} +| *nginx.org/limit-req-rate* | N/A | Enables request-rate-limiting for this ingress by creating a [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) and matching [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) for each location. All servers/locations of one ingress share the same zone. Must have unit r/s or r/m. | N/A | 200r/s | +| *nginx.org/limit-req-key* | N/A | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ${}. | ${binary_remote_addr} | ${binary_remote_addr} | +| *nginx.org/limit-req-zone-size* | N/A | Configures the size of the created [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). | 10m | 20m | +| *nginx.org/limit-req-delay* | N/A | Configures the delay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | 0 | 100 | +| *nginx.org/limit-req-no-delay* | N/A | Configures the nodelay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | false | true | +| *nginx.org/limit-req-burst* | N/A | Configures the burst-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | N/A | 100 | +| *nginx.org/limit-req-dry-run* | N/A | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the number of excessive requests is accounted as usual in the shared memory zone. | false | true | +| *nginx.org/limit-req-log-level* | N/A | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are info, notice, warn or error. | error | info | +| *nginx.org/limit-req-reject-code* | N/A | Sets the status code to return in response to rejected requests. Must fall into the range 400..599. | 429 | 503 | +| *nginx.org/limit-req-scale* | N/A | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. Note: This will not work properly if requests from a client are not evenly distributed accross all ingress pods (sticky sessions, long lived TCP-Connections with many requests etc.). In such cases using NGINX+'s zone-sync feature instead would give better results. | false | true | +{{}} + +### Snippets and custom templates + +{{}} |Annotation | ConfigMap Key | Description | Default | Example | | ---| ---| ---| ---| --- | -|``nginx.org/location-snippets`` | ``location-snippets`` | Sets a custom snippet in location context. | N/A | | -|``nginx.org/server-snippets`` | ``server-snippets`` | Sets a custom snippet in server context. | N/A | | -{{% /table %}} +| *nginx.org/location-snippets* | *location-snippets* | Sets a custom snippet in location context. | N/A | | +| *nginx.org/server-snippets* | *server-snippets* | Sets a custom snippet in server context. | N/A | | +{{}} -### App Protect {#app-protect} +### App Protect WAF {#app-protect} -**Note**: The App Protect annotations only work if App Protect WAF module is [installed](/nginx-ingress-controller/app-protect/installation/). +{{< note >}} The App Protect annotations only work if the App Protect WAF module is [installed]({{< relref "installation/integrations/app-protect-waf/installation.md" >}}). {{< /note >}} -{{% 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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/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/v3.5.2/examples/ingress-resources/app-protect-waf). | -{{% /table %}} +| *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 | [app-protect-waf](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/app-protect-waf) | +| *appprotect.f5.com/app-protect-enable* | N/A | Enable App Protect for the Ingress Resource. | *False* | [app-protect-waf](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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* | [app-protect-waf](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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 | [app-protect-waf](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/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* | [app-protect-waf](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/app-protect-waf) | +{{}} ### App Protect DoS -**Note**: The App Protect DoS annotations only work if App Protect DoS module is [installed](/nginx-ingress-controller/app-protect-dos/installation/). +{{< note >}} The App Protect DoS annotations only work if the App Protect DoS module is [installed]({{< relref "installation/integrations/app-protect-dos/installation.md" >}}). {{< /note >}} -{{% 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/v3.5.2/examples/ingress-resources/app-protect-dos). | -{{% /table %}} +| *appprotectdos.f5.com/app-protect-dos-resource* | N/A | Enable App Protect DoS for the Ingress Resource by specifying a [DosProtectedResource]({{< relref "installation/integrations/app-protect-dos/dos-protected.md" >}}). | N/A | [app-protect-dos](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/app-protect-dos) | +{{}} diff --git a/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md b/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md index 6001d18e4f..8b7006acbe 100644 --- a/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md +++ b/docs/content/configuration/ingress-resources/advanced-configuration-with-snippets.md @@ -2,16 +2,34 @@ docs: DOCS-592 doctypes: - '' -title: Advanced Configuration with Snippets +title: Advanced configuration with Snippets toc: true -weight: 1800 +weight: 400 --- -Snippets allow you to insert raw NGINX config into different contexts of the NGINX configurations that NGINX Ingress Controller generates. Snippets are intended for advanced NGINX users who need more control over the generated NGINX configuration, and can be used in cases where Annotations and ConfigMap entries would not apply. +Snippets allow you to insert raw NGINX config into different contexts of the NGINX configurations that F5 NGINX Ingress Controller generates. -Snippets are also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md" >}}) +Snippets are intended for advanced NGINX users who need more control over the generated NGINX configuration, and can be used in cases where Annotations and ConfigMap entries would not apply. -## Using Snippets + + +## Disadvantages of snippets + +Snippets are configured [using Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md#snippets-and-custom-templates" >}}), but are disabled by default due to their complexity. They are also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) resource. + +To use snippets, set the [`enable-snippets`]({{< relref "configuration/global-configuration/command-line-arguments.md#cmdoption-enable-snippets" >}}) command-line argument. + +Snippets have the following disadvantages: + +- *Complexity*. Snippets require you to: + - Understand NGINX configuration primitives and implement a correct NGINX configuration. + - Understand how NGINX Ingress Controller generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration. +- *Decreased robustness*. An incorrect snippet can invalidate NGINX configuration, causing reload failures. Until the snippet is fixed, it will prevent any new configuration updates, including updates for the other Ingress resources. +- *Security implications*. Snippets give access to NGINX configuration primitives, which are not validated by NGINX Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress resources. + +{{< note >}} If the NGINX configuration includes an invalid snippet, NGINX will continue to operate with the last valid configuration. {{< /note >}} + +## Using snippets The example below shows how to use snippets to customize the NGINX configuration template using annotations. @@ -48,7 +66,9 @@ spec: number: 80 ``` -Generated NGINX configuration: +These snippets generate the following NGINX configuration: + +{{< note >}} The example is shortened for conciseness. {{< /note >}} ```nginx server { @@ -79,32 +99,13 @@ server { } ``` -**Note**: The generated configs are truncated for the clarity of the example. - -## Summary of Snippets - -See the [snippets annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/#snippets-and-custom-templates) documentation for more information. -However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the [`enable-snippets`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets) command-line argument. - -## Disadvantages of Using Snippets - -Snippets have the following disadvantages: - -- *Complexity*. To use snippets, you will need to: - - Understand NGINX configuration primitives and implement a correct NGINX configuration. - - Understand how the IC generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration. -- *Decreased robustness*. An incorrect snippet makes the NGINX config invalid, which causes reload failures. This will prevent any new configuration updates, including updates for the other Ingress resources, until the snippet is fixed. -- *Security implications*. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress resources. - -> **Note**: If the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration. - ## Troubleshooting -If a snippet includes an invalid NGINX configuration, the Ingress Controller will fail to reload NGINX. The error will be reported in the Ingress Controller logs and an event with the error will be associated with the Ingress resource: +If a snippet includes an invalid NGINX configuration, NGINX Ingress Controller will fail to reload NGINX. The error will be reported in NGINX Ingress Controller logs and an event with the error will be associated with the Ingress resource: An example of an error from the logs: -```shell +```text [emerg] 31#31: unknown directive "badd_header" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54 Event(v1.ObjectReference{Kind:"Ingress", Namespace:"default", Name:"cafe-ingress-with-snippets", UID:"f9656dc9-63a6-41dd-a499-525b0e0309bb", APIVersion:"extensions/v1beta1", ResourceVersion:"2322030", FieldPath:""}): type: 'Warning' reason: 'AddedOrUpdatedWithError' Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: "" stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n" @@ -113,7 +114,7 @@ finished with error: exit status 1 An example of an event with an error (you can view events associated with the Ingress by running `kubectl describe -n nginx-ingress ingress nginx-ingress`): -```shell +```text Events: Type Reason Age From Message ---- ------ ---- ---- ------- diff --git a/docs/content/configuration/ingress-resources/basic-configuration.md b/docs/content/configuration/ingress-resources/basic-configuration.md index 8a04087311..c22fa376c4 100644 --- a/docs/content/configuration/ingress-resources/basic-configuration.md +++ b/docs/content/configuration/ingress-resources/basic-configuration.md @@ -1,14 +1,13 @@ --- -description: The example in this document shows a basic Ingress resource definition. docs: DOCS-593 doctypes: - '' -title: Basic Configuration +title: Basic configuration toc: true -weight: 1600 +weight: 100 --- -This document shows a basic Ingress resource definition which load balances requests for two services as part of a single application. +This document shows a basic Ingress resource definition for F5 NGINX Ingress Controller. It load balances requests for two services as part of a single application. ```yaml apiVersion: networking.k8s.io/v1 @@ -43,20 +42,21 @@ spec: Here is a breakdown of what this Ingress resource definition means: - The `metadata.name` field defines the name of the resource `cafe‑ingress`. -- In the `spec.tls` field we set up SSL/TLS termination: - - In the `secretName`, we reference a secret resource by its name, `cafe‑secret`. The secret must belong to the same namespace as the Ingress, it must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that hold the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls>). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the hosts to which the secret is applied. - - In the `hosts` field, we apply the certificate and key to our `cafe.example.com` host. -- In the `spec.rules` field, we define a host with domain name `cafe.example.com`. -- In the `paths` field, we define two path‑based rules: +- The `spec.tls` field sets up SSL/TLS termination: + - The `hosts` field applies the certificate and key to the `cafe.example.com` host. + - The `secretName` references a secret resource by its name, `cafe‑secret`. The secret must belong to the same namespace as the Ingress, of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that hold the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls>). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the hosts to which the secret is applied. +- The `spec.rules` field defines a host with the domain name `cafe.example.com`. +- The `paths` field defines two path‑based rules: - The rule with the path `/tea` instructs NGINX to distribute the requests with the `/tea` URI among the pods of the *tea* service, which is deployed with the name `tea‑svc` in the cluster. - 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/v3.5.2/examples/ingress-resources/complete-example) in our GitHub repository. +To learn more about the Ingress resource, view [the official Kubernetes documentation for Ingress resources](https://kubernetes.io/docs/concepts/services-networking/ingress/). -> To learn more about the Ingress resource, see the [Ingress resource documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the Kubernetes docs. +{{< note >}} For complete instructions on deploying Ingress and Secret resources in the cluster, see the [complete example](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/ingress-resources/complete-example) in the GitHub repository. {{< /note >}} -## New Features Available in Kubernetes 1.18 and Above + +## New features available in Kubernetes 1.18 Starting from Kubernetes 1.18, you can use the following new features: @@ -103,19 +103,23 @@ Starting from Kubernetes 1.18, you can use the following new features: . . . ``` - When using this filed you need to create the `IngressClass` resource with the corresponding `name`. See Step 3 *Create an IngressClass resource* of the [Create Common Resources](/nginx-ingress-controller/installation/installation-with-manifests/#2-create-common-resources) section. + When using this field you need to create the `IngressClass` resource with the corresponding `name`. View the [Create common resources]({{< relref "installation/installing-nic/installation-with-manifests.md#create-common-resources" >}}) section of the Installation with Manifests topic for more information. ## Restrictions NGINX Ingress Controller imposes the following restrictions on Ingress resources: - When defining an Ingress resource, the `host` field is required. -- The `host` value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a [mergeable minion](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/). See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/handling-host-and-listener-collisions). +- The `host` value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a [mergeable minion]({{< relref "configuration/ingress-resources/cross-namespace-configuration.md" >}}). View the [Host and Listener collisions]({{< relref "configuration/host-and-listener-collisions.md" >}}) topic for more information. - The `path` field in `spec.rules[].http.paths[]` is required for `Exact` and `Prefix` `pathTypes`. - The ImplementationSpecific `pathType` is treated as equivalent to `Prefix` `pathType`, with the exception that when this `pathType` is configured, the `path` field in `spec.rules[].http.paths[]` is not mandatory. `path` defaults to `/` if not set but the `pathType` is set to ImplementationSpecific. -## Advanced Configuration +## Advanced configuration + +NGINX Ingress Controller generates NGINX configuration by executing a template file that contains the configuration options. These options are set with the Ingress resource and NGINX Ingress Controller's ConfigMap. The Ingress resource only allows you to use basic NGINX features: host and path-based routing and TLS termination. + +Advanced features like rewriting the request URI or inserting additional response headers are available through annotations. View the [Advanced configuration with Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations.md" >}}) topic for more information. -The Ingress resource only allows you to use basic NGINX features -- host and path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers are available through annotations. See the [Advanced Configuration with Annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations) doc. +Advanced NGINX users who require more control over the generated NGINX configurations can use snippets to insert raw NGINX config. View the [Advanced configuration with Snippets]({{< relref "configuration/ingress-resources/advanced-configuration-with-snippets" >}}) topic for more information. -The Ingress Controller generates NGINX configuration by executing a template file that contains configuration options. These options are set via the Ingress resource and the Ingress Controller's ConfigMap. Advanced NGINX users who require more control over the generated NGINX configurations can use snippets to insert raw NGINX config. See [Advanced Configuration with Snippets](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-snippets) for more information. Additionally, it is possible to customize the template. See [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates/) for instructions. +Additionally, it is possible to customize the template, described in the [Custom templates]({{< relref "/configuration/global-configuration/custom-templates.md" >}}) topic. diff --git a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md index 982b802bff..49a62416c3 100644 --- a/docs/content/configuration/ingress-resources/cross-namespace-configuration.md +++ b/docs/content/configuration/ingress-resources/cross-namespace-configuration.md @@ -2,12 +2,12 @@ docs: DOCS-594 doctypes: - '' -title: Cross-namespace Configuration +title: Cross-namespace configuration toc: true -weight: 2000 +weight: 500 --- -This document explains how to spread Ingress configuration across different namespaces. +This topic explains how to spread Ingress configuration across different namespaces in F5 NGINX Ingress Controller. 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/v3.5.2/examples/ingress-resources/mergeable-ingress-types) 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 7afccfd3d4..bed0785cf8 100644 --- a/docs/content/configuration/ingress-resources/custom-annotations.md +++ b/docs/content/configuration/ingress-resources/custom-annotations.md @@ -2,14 +2,16 @@ docs: DOCS-595 doctypes: - '' -title: Custom Annotations +title: Custom annotations toc: true -weight: 1900 +weight: 300 --- +This topic explains how you can use custom annotations with F5 NGINX Ingress Controller. + Custom annotations enable you to quickly extend the Ingress resource to support many advanced features of NGINX, such as rate limiting, caching, etc. -## What are Custom Annotations +## Overview NGINX Ingress Controller supports a number of annotations for the Ingress resource that fine tune NGINX configuration (for example, connection timeouts) or enable additional features (for example, JWT validation). The complete list of annotations is available [here](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations). diff --git a/docs/content/configuration/policy-resource.md b/docs/content/configuration/policy-resource.md index 1983f0c1ce..6aa2c787c4 100644 --- a/docs/content/configuration/policy-resource.md +++ b/docs/content/configuration/policy-resource.md @@ -2,9 +2,9 @@ docs: DOCS-596 doctypes: - '' -title: Policy Resource +title: Policy resources toc: true -weight: 1800 +weight: 600 --- The Policy resource allows you to configure features like access control and rate-limiting, which you can add to your [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/). diff --git a/docs/content/configuration/security.md b/docs/content/configuration/security.md index fdc7d12424..5a869a1840 100644 --- a/docs/content/configuration/security.md +++ b/docs/content/configuration/security.md @@ -4,10 +4,10 @@ doctypes: - '' title: Security recommendations toc: true -weight: 1500 +weight: 300 --- -NGINX Ingress Controller follows Kubernetes best practices: this page outlines configuration specific to NGINX Ingress Controller you may require, including links to examples in the [GitHub repository](https://github.com/nginxinc/kubernetes-ingress/tree/release-3.5). +F5 NGINX Ingress Controller follows Kubernetes best practices: this page outlines configuration specific to NGINX Ingress Controller you may require, including links to examples in the [GitHub repository](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples). For general guidance, we recommend the official Kubernetes documentation for [Securing a Cluster](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/). @@ -17,13 +17,10 @@ For general guidance, we recommend the official Kubernetes documentation for [Se Kubernetes uses [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control the resources and operations available to different types of users. -The Ingress Controller is deployed within a Kubernetes environment, this environment must be secured. -Kubernetes uses [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control the resources and operations available to different types of users. -The Ingress Controller requires a service account which is configured using RBAC. -We strongly recommend using the [RBAC configuration](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.2/deployments/rbac/rbac.yaml) provided in our standard deployment configuration. It is configured with the least amount of privilege required for the Ingress Controller to work. +NGINX Ingress Controller requires RBAC to configure a [ServiceUser](https://kubernetes.io/docs/concepts/security/service-accounts/#default-service-accounts), and provides least privilege access in its standard deployment configurations: -We strongly recommend inspecting the RBAC configuration for [Manifests](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.2/deployments/rbac/rbac.yaml) -or for [Helm](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.2/charts/nginx-ingress/templates/clusterrole.yaml) to understand what access the Ingress Controller service account has and to which resources. For example, by default the service account has access to all Secret resources in the cluster. +- [Helm](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.2/deployments/rbac/rbac.yaml) +- [Manifests](https://github.com/nginxinc/kubernetes-ingress/blob/v3.5.2/deployments/rbac/rbac.yaml) By default, the ServiceAccount has access to all Secret resources in the cluster. @@ -96,7 +93,7 @@ Snippets are disabled by default. To use snippets, set the [**enable-snippets**] For more information, read the following: -- [Advanced Configuration using Snippets]({{< relref "/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) +- [Advanced configuration using Snippets]({{< relref "/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) - [Using Snippets with VirtualServer/VirtualServerRoute]({{< relref "configuration/virtualserver-and-virtualserverroute-resources.md#using-snippets" >}}) - [Using Snippets with TransportServer]({{< relref "/configuration/transportserver-resource.md#using-snippets" >}}) -- [ConfigMap Snippets and Custom Templates]({{< relref "configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) +- [ConfigMap snippets and custom templates]({{< relref "configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) diff --git a/docs/content/configuration/transportserver-resource.md b/docs/content/configuration/transportserver-resource.md index 06bcf0227e..8257f87f93 100644 --- a/docs/content/configuration/transportserver-resource.md +++ b/docs/content/configuration/transportserver-resource.md @@ -2,19 +2,21 @@ docs: DOCS-598 doctypes: - '' -title: TransportServer Resource +title: TransportServer resources toc: true -weight: 1900 +weight: 700 --- +This document is reference material for the TransportServer resource used by F5 NGINX Ingress Controller. + The TransportServer resource allows you to configure TCP, UDP, and TLS Passthrough load balancing. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the TransportServer resource. To see additional examples of using the resource for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources) folder in our GitHub repo. +The GitHub repository has [examples of the resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources) for specific use cases. ## Prerequisites -- For TCP and UDP, the TransportServer resource must be used in conjunction with the [GlobalConfiguration resource](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource), which must be created separately. -- For TLS Passthrough, make sure to enable the [`-enable-tls-passthrough`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-tls-passthrough) command-line argument of the Ingress Controller. +- For TCP and UDP, the TransportServer resource must be used in conjunction with the [GlobalConfiguration resource]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}), which must be created separately. +- For TLS Passthrough, make sure to enable the [`-enable-tls-passthrough`]({{< relref "configuration/global-configuration/command-line-arguments#cmdoption-enable-tls-passthrough.md" >}}) command-line argument of NGINX Ingress Controller. ## TransportServer Specification @@ -83,7 +85,7 @@ The TransportServer resource defines load balancing configuration for TCP, UDP, pass: secure-app ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``listener`` | The listener on NGINX that will accept incoming connections/datagrams. | [listener](#listener) | Yes | @@ -95,13 +97,13 @@ The TransportServer resource defines load balancing configuration for TCP, UDP, |``ingressClassName`` | Specifies which Ingress Controller must handle the TransportServer resource. | ``string`` | No | |``streamSnippets`` | Sets a custom snippet in the ``stream`` context. | ``string`` | No | |``serverSnippets`` | Sets a custom snippet in the ``server`` context. | ``string`` | No | -{{% /table %}} +{{}} \* -- Required for TLS Passthrough load balancing. ### Listener -The listener field references a listener that NGINX will use to accept incoming traffic for the TransportServer. For TCP and UDP, the listener must be defined in the [GlobalConfiguration resource](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource). When referencing a listener, both the name and the protocol must match. For TLS Passthrough, use the built-in listener with the name `tls-passthrough` and the protocol `TLS_PASSTHROUGH`. +The listener field references a listener that NGINX will use to accept incoming traffic for the TransportServer. For TCP and UDP, the listener must be defined in the [GlobalConfiguration resource]({{< relref "configuration/global-configuration/globalconfiguration-resource.md" >}}). When referencing a listener, both the name and the protocol must match. For TLS Passthrough, use the built-in listener with the name `tls-passthrough` and the protocol `TLS_PASSTHROUGH`. An example: @@ -111,26 +113,26 @@ listener: protocol: UDP ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the listener. | ``string`` | Yes | |``protocol`` | The protocol of the listener. | ``string`` | Yes | -{{% /table %}} +{{}} ### TLS -The tls field defines TLS configuration for a TransportServer. Please note the current implementation supports TLS termination on multiple ports, where each application owns a dedicated port - the Ingress Controller terminates TLS connections on each port, where each application uses its own cert/key, and routes connections to appropriate application (service) based on that incoming port (any TLS connection regardless of the SNI on a port will be routed to the application that corresponds to that port). An example configuration is shown below: +The tls field defines TLS configuration for a TransportServer. Please note the current implementation supports TLS termination on multiple ports, where each application owns a dedicated port - NGINX Ingress Controller terminates TLS connections on each port, where each application uses its own cert/key, and routes connections to appropriate application (service) based on that incoming port (any TLS connection regardless of the SNI on a port will be routed to the application that corresponds to that port). An example configuration is shown below: ```yaml secret: cafe-secret ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the TransportServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). | ``string`` | No | -{{% /table %}} +{{}} ### Upstream @@ -146,7 +148,7 @@ failTimeout: 30s loadBalancingMethod: least_conn ``` -{{% table %}} +{{}} |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 | @@ -159,7 +161,7 @@ loadBalancingMethod: least_conn |``loadBalancingMethod`` | The method used to load balance the upstream servers. By default, connections are distributed between the servers using a weighted round-robin balancing method. See the [upstream](http://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#upstream) section for available methods and their details. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | |``backupPort`` | The port of the backup service. The backup port is required if the backup service name is provided. The port must fall into the range ``1..65535``. | ``uint16`` | No | -{{% /table %}} +{{}} ### Upstream.Healthcheck @@ -179,9 +181,9 @@ healthCheck: port: 8080 ``` -Note: This feature is supported only in NGINX Plus. +{{< note >}} This feature is only supported with NGINX Plus. {{< /note >}} -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | @@ -192,7 +194,7 @@ Note: This feature is supported only in NGINX Plus. |``passes`` | The number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is ``1``. | ``integer`` | No | |``port`` | The port used for health check requests. By default, the [server port is used](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check_port). Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod. | ``integer`` | No | |``match`` | Controls the data to send and the response to expect for the healthcheck. | [match](#upstreamhealthcheckmatch) | No | -{{% /table %}} +{{}} ### Upstream.Healthcheck.Match @@ -208,12 +210,12 @@ Both `send` and `expect` fields can contain hexadecimal literals with the prefix See the [match](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) directive for details. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``send`` | A string to send to an upstream server. | ``string`` | No | -|``expect`` | A literal string or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding ``~*`` modifier (for case-insensitive matching), or the ``~`` modifier (for case-sensitive matching). The Ingress Controller validates a regular expression using the RE2 syntax. | ``string`` | No | -{{% /table %}} +|``expect`` | A literal string or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding ``~*`` modifier (for case-insensitive matching), or the ``~`` modifier (for case-sensitive matching). NGINX Ingress Controller validates a regular expression using the RE2 syntax. | ``string`` | No | +{{}} ### UpstreamParameters @@ -229,7 +231,7 @@ upstreamParameters: nextUpstreamTries: 1 ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``udpRequests`` | The number of datagrams, after receiving which, the next datagram from the same client starts a new session. See the [proxy_requests](https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_requests) directive. The default is ``0``. | ``int`` | No | @@ -238,7 +240,7 @@ upstreamParameters: |``nextUpstream`` | If a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server. See the [proxy_next_upstream](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream) directive. The default is ``true``. | bool | No | |``nextUpstreamTries`` | The number of tries for passing a connection to the next server. See the [proxy_next_upstream_tries](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries) directive. The default is ``0``. | ``int`` | No | |``nextUpstreamTimeout`` | The time allowed to pass a connection to the next server. See the [proxy_next_upstream_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout) directive. The default us ``0``. | ``string`` | No | -{{% /table %}} +{{}} ### SessionParameters @@ -249,11 +251,11 @@ sessionParameters: timeout: 50s ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``timeout`` | The timeout between two successive read or write operations on client or proxied server connections. See [proxy_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout) directive. The default is ``10m``. | ``string`` | No | -{{% /table %}} +{{}} ### Action @@ -266,11 +268,11 @@ action: pass: dns-app ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``pass`` | Passes connections/datagrams to an upstream. The upstream with that name must be defined in the resource. | ``string`` | Yes | -{{% /table %}} +{{}} ## Using TransportServer @@ -280,7 +282,8 @@ For example, the following command creates a TransportServer resource defined in ```shell kubectl apply -f transport-server-passthrough.yaml - +``` +```text transportserver.k8s.nginx.org/secure-app created ``` @@ -288,7 +291,8 @@ You can get the resource by running: ```shell kubectl get transportserver secure-app - +``` +```text NAME AGE secure-app 46sm ``` @@ -332,28 +336,16 @@ spec: port: 80 ``` -Snippets are intended to be used by advanced NGINX users who need more control over the generated NGINX configuration. - -However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the [`enable-snippets`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets) command-line argument. - -Disadvantages of using snippets: - -- *Complexity*. To use snippets, you will need to: - - Understand NGINX configuration primitives and implement a correct NGINX configuration. - - Understand how the IC generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration. -- *Decreased robustness*. An incorrect snippet makes the NGINX config invalid which will lead to a failed reload. This will prevent any new configuration updates, including updates for the other TransportServer resource until the snippet is fixed. -- *Security implications*. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller. - -> Note: during a period when the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration. +{{< note >}} To configure snippets in the `stream` context, use `stream-snippets` ConfigMap key. {{< /note >}} -> Note: to configure snippets in the `stream` context, use `stream-snippets` ConfigMap key. +For additional information, view the [Advanced configuration with Snippets]({{< relref "configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) topic. ### Validation Two types of validation are available for the TransportServer resource: - *Structural validation* by the `kubectl` and Kubernetes API server. -- *Comprehensive validation* by the Ingress Controller. +- *Comprehensive validation* by NGINX Ingress Controller. #### Structural Validation @@ -365,31 +357,34 @@ If you try to create (or update) a resource that violates the structural schema ```shell kubectl apply -f transport-server-passthrough.yaml - - error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.TransportServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + ```text + error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.TransportServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false ``` - Example of Kubernetes API server validation: ```shell kubectl apply -f transport-server-passthrough.yaml --validate=false - - The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: - spec.upstreams.port in body must be of type integer: "string" + ``` + ```text + The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.upstreams.port in body must be of type integer: "string" ``` -If a resource is not rejected (it doesn't violate the structural schema), the Ingress Controller will validate it further. +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. #### Comprehensive Validation -The Ingress Controller validates the fields of a TransportServer resource. If a resource is invalid, the Ingress Controller will reject it: the resource will continue to exist in the cluster, but the Ingress Controller will ignore it. +NGINX Ingress Controller validates the fields of a TransportServer resource. If a resource is invalid, NGINX Ingress Controller will reject it: the resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. -You can check if the Ingress Controller successfully applied the configuration for a TransportServer. For our example `secure-app` TransportServer, we can run: +You can check if NGINX Ingress Controller successfully applied the configuration for a TransportServer. For our example `secure-app` TransportServer, we can run: ```shell kubectl describe ts secure-app - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -398,12 +393,13 @@ Events: Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. -If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a TransportServer `secure-app` with a pass action that references a non-existing upstream, you will get : +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a TransportServer `secure-app` with a pass action that references a non-existing upstream, you will get : ```shell kubectl describe ts secure-app - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -412,8 +408,8 @@ Events: Note how the events section includes a Warning event with the Rejected reason. -**Note**: If you make an existing resource invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX. +**Note**: If you make an existing resource invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. ## Customization via ConfigMap -The [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) keys (except for `stream-snippets`, `stream-log-format`, `resolver-addresses`, `resolver-ipv6`, `resolver-valid` and `resolver-timeout`) do not affect TransportServer resources. +The [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource.md" >}}) keys (except for `stream-snippets`, `stream-log-format`, `resolver-addresses`, `resolver-ipv6`, `resolver-valid` and `resolver-timeout`) do not affect TransportServer resources. diff --git a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md index bf74e6e4e7..10de579463 100644 --- a/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/docs/content/configuration/virtualserver-and-virtualserverroute-resources.md @@ -2,18 +2,22 @@ docs: DOCS-599 doctypes: - '' -title: VirtualServer and VirtualServerRoute Resources +title: VirtualServer and VirtualServerRoute resources toc: true weight: 1600 --- +This document is reference material for the VirtualServer and VirtualServerRoute resources used by F5 NGINX Ingress Controller. + VirtualServer and VirtualServerRoute resources are load balancing configurations recommended as an alternative to the Ingress resource. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. The resources are implemented as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). -This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the [examples/custom-resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources) folder in our GitHub repo. +The GitHub repository has [examples of the resources](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources) for specific use cases. + +--- -## VirtualServer Specification +## VirtualServer specification The VirtualServer resource defines load balancing configuration for a domain name, such as `example.com`. Below is an example of such configuration: @@ -52,7 +56,7 @@ spec: pass: tea ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. When using a wildcard domain like ``*.example.com`` the domain must be contained in double quotes. The ``host`` value needs to be unique among all Ingress and VirtualServer resources. See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/handling-host-and-listener-collisions). | ``string`` | Yes | @@ -68,7 +72,7 @@ spec: |``internalRoute`` | Specifies if the VirtualServer resource is an internal route or not. | ``boolean`` | No | |``http-snippets`` | Sets a custom snippet in the http context. | ``string`` | No | |``server-snippets`` | Sets a custom snippet in server context. Overrides the ``server-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{}} ### VirtualServer.TLS @@ -80,13 +84,13 @@ redirect: enable: true ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. If the secret is not specified but [wildcard TLS secret](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-wildcard-tls-secret) is configured, NGINX will use the wildcard secret for TLS termination. | ``string`` | No | |``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect | |``cert-manager`` | The cert-manager configuration of the TLS for a VirtualServer. | [tls.cert-manager](#virtualservertlscertmanager) | No | ### VirtualServer.TLS.CertManager | -{{% /table %}} +{{}} ### VirtualServer.TLS.Redirect @@ -98,13 +102,13 @@ code: 301 basedOn: scheme ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables a TLS redirect for a VirtualServer. The default is ``False``. | ``boolean`` | No | |``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | |``basedOn`` | The attribute of a request that NGINX will evaluate to send a redirect. The allowed values are ``scheme`` (the scheme of the request) or ``x-forwarded-proto`` (the ``X-Forwarded-Proto`` header of the request). The default is ``scheme``. | ``string`` | No | ### VirtualServer.Policy | -{{% /table %}} +{{}} ### VirtualServer.TLS.CertManager @@ -115,7 +119,7 @@ cert-manager: cluster-issuer: "my-issuer-name" ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``issuer`` | the name of an Issuer. An Issuer is a cert-manager resource which describes the certificate authority capable of signing certificates. The Issuer must be in the same namespace as the VirtualServer resource. Please note that one of `issuer` and `cluster-issuer` are required, but they are mutually exclusive - one and only one must be defined. | ``string`` | No | @@ -127,7 +131,7 @@ cert-manager: |``renew-before`` | this annotation allows you to configure spec.renewBefore field for the Certificate to be generated. Must be specified using a [Go time.Duration](https://pkg.go.dev/time#ParseDuration) string format, which does not allow the d (days) suffix. You must specify these values using s, m, and h suffixes instead. | ``string`` | No | |``usages`` | This field allows you to configure spec.usages field for the Certificate to be generated. Pass a string with comma-separated values i.e. ``key agreement,digital signature, server auth``. An exhaustive list of supported key usages can be found in the [the cert-manager api documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.KeyUsage). | ``string`` | No | |``issue-temp-cert`` | When ``true``, ask cert-manager for a [temporary self-signed certificate](https://cert-manager.io/docs/usage/certificate/#temporary-certificates-while-issuing) pending the issuance of the Certificate. This allows HTTPS-only servers to use ACME HTTP01 challenges when the TLS secret does not exist yet. | ``boolean`` | No | -{{% /table %}} +{{}} ### VirtualServer.Listener The listener field defines a custom HTTP and/or HTTPS listener. @@ -138,12 +142,12 @@ http: http-8083 https: https-8443 ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``http`` | The name of am HTTP listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No | |``https`` | The name of an HTTPS listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No | -{{% /table %}} +{{}} ### VirtualServer.ExternalDNS @@ -153,7 +157,7 @@ The externalDNS field configures controlling DNS records dynamically for Virtual enable: true ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables ExternalDNS integration for a VirtualServer resource. The default is ``false``. | ``string`` | No | @@ -161,7 +165,7 @@ enable: true |``providerSpecific`` | Configure provider specific properties which holds the name and value of a configuration which is specific to individual DNS providers. | [[]ProviderSpecific](#virtualserverexternaldnsproviderspecific) | No | |``recordTTL`` | TTL for the DNS record. This defaults to 0 if not defined. See [the ExternalDNS TTL documentation for provider-specific defaults](https://kubernetes-sigs.github.io/external-dns/v0.12.0/ttl/#providers) | ``int64`` | No | |``recordType`` | The record Type that should be created, e.g. "A", "AAAA", "CNAME". This is automatically computed based on the external endpoints if not defined. | ``string`` | No | -{{% /table %}} +{{}} ### VirtualServer.ExternalDNS.ProviderSpecific @@ -174,12 +178,12 @@ The providerSpecific field of the externalDNS block allows the specification of value: my-value2 ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the key value pair. | ``string`` | Yes | |``value`` | The value of the key value pair. | ``string`` | Yes | -{{% /table %}} +{{}} ### VirtualServer.Policy @@ -189,12 +193,12 @@ The policy field references a [Policy resource](/nginx-ingress-controller/config name: access-control ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of a policy. If the policy doesn't exist or invalid, NGINX will respond with an error response with the `500` status code. | ``string`` | Yes | |``namespace`` | The namespace of a policy. If not specified, the namespace of the VirtualServer resource is used. | ``string`` | No | -{{% /table %}} +{{}} ### VirtualServer.Route @@ -206,7 +210,7 @@ The route defines rules for matching client requests to actions like passing a r pass: tea ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``path`` | The path of the route. NGINX will match it against the URI of a request. Possible values are: a prefix ( ``/`` , ``/path`` ), an exact match ( ``=/exact/match`` ), a case insensitive regular expression ( ``~*^/Bar.*\.jpg`` ) or a case sensitive regular expression ( ``~^/foo.*\.jpg`` ). In the case of a prefix (must start with ``/`` ) or an exact match (must start with ``=`` ), the path must not include any whitespace characters, ``{`` , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all routes of the VirtualServer. Check the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive for more information. | ``string`` | Yes | @@ -218,11 +222,11 @@ The route defines rules for matching client requests to actions like passing a r |``route`` | The name of a VirtualServerRoute resource that defines this route. If the VirtualServerRoute belongs to a different namespace than the VirtualServer, you need to include the namespace. For example, ``tea-namespace/tea``. | ``string`` | No | |``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | |``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{}} \* -- a route must include exactly one of the following: `action`, `splits`, or `route`. -## VirtualServerRoute Specification +## VirtualServerRoute specification The VirtualServerRoute resource defines a route for a VirtualServer. It can consist of one or multiple subroutes. The VirtualServerRoute is an alternative to [Mergeable Ingress types](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration). @@ -278,14 +282,14 @@ spec: Note that each subroute must have a `path` that starts with the same prefix (here `/coffee`), which is defined in the route of the VirtualServer. Additionally, the `host` in the VirtualServerRoute must be the same as the `host` of the VirtualServer. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. When using a wildcard domain like ``*.example.com`` the domain must be contained in double quotes. Must be the same as the ``host`` of the VirtualServer that references this resource. | ``string`` | Yes | |``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | |``subroutes`` | A list of subroutes. | [[]subroute](#virtualserverroutesubroute) | No | |``ingressClassName`` | Specifies which Ingress Controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | -{{% /table %}} +{{}} ### VirtualServerRoute.Subroute @@ -297,7 +301,7 @@ action: pass: coffee ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``path`` | The path of the subroute. NGINX will match it against the URI of a request. Possible values are: a prefix ( ``/`` , ``/path`` ), an exact match ( ``=/exact/match`` ), a case insensitive regular expression ( ``~*^/Bar.*\.jpg`` ) or a case sensitive regular expression ( ``~^/foo.*\.jpg`` ). In the case of a prefix, the path must start with the same path as the path of the route of the VirtualServer that references this resource. In the case of an exact or regex match, the path must be the same as the path of the route of the VirtualServer that references this resource. A matching path of the route of the VirtualServer but in different type is not accepted, e.g. a regex path (`~/match`) cannot be used with a prefix path in VirtualServer (`/match`) In the case of a prefix or an exact match, the path must not include any whitespace characters, ``{`` , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all subroutes of the VirtualServerRoute. | ``string`` | Yes | @@ -308,11 +312,11 @@ action: |``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | |``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | |``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` of the VirtualServer (if set) or the ``location-snippets`` ConfigMap key. | ``string`` | No | -{{% /table %}} +{{}} \* -- a subroute must include exactly one of the following: `action` or `splits`. -## Common Parts of the VirtualServer and VirtualServerRoute +## Common VirtualServer and VirtualServerRoute specifications ### Upstream @@ -342,12 +346,12 @@ tls: **Note**: The WebSocket protocol is supported without any additional configuration. -{{% table %}} +{{}} |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/v3.5.2/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 | +|``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, NGINX 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 NGINX 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 | |``lb-method`` | 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``. The default is specified in the ``lb-method`` ConfigMap key. | ``string`` | No | @@ -373,7 +377,7 @@ tls: |``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#listeners) and configure TLS termination in the VirtualServer. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | |``backupPort`` | The port of the backup service. The backup port is required if the backup service name is provided. The port must fall into the range ``1..65535``. | ``uint16`` | No | -{{% /table %}} +{{}} ### Upstream.Buffers @@ -386,20 +390,20 @@ size: 8K See the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive for additional information. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``number`` | Configures the number of buffers. The default is set in the ``proxy-buffers`` ConfigMap key. | ``int`` | Yes | |``size`` | Configures the size of a buffer. The default is set in the ``proxy-buffers`` ConfigMap key. | ``string`` | Yes | -{{% /table %}} +{{}} ### Upstream.TLS -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables HTTPS for requests to upstream servers. The default is ``False`` , meaning that HTTP will be used. Note: by default, NGINX will not verify the upstream server certificate. To enable the verification, configure an [EgressMTLS Policy](/nginx-ingress-controller/configuration/policy-resource/#egressmtls). | ``boolean`` | No | -{{% /table %}} +{{}} ### Upstream.Queue @@ -414,12 +418,12 @@ See [`queue`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue Note: This feature is supported only in NGINX Plus. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``size`` | The size of the queue. | ``int`` | Yes | |``timeout`` | The timeout of the queue. A request cannot be queued for a period longer than the timeout. The default is ``60s``. | ``string`` | No | -{{% /table %}} +{{}} ### Upstream.Healthcheck @@ -454,7 +458,7 @@ healthCheck: Note: This feature is supported only in NGINX Plus. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | @@ -475,7 +479,7 @@ Note: This feature is supported only in NGINX Plus. |``mandatory`` | Require every newly added server to pass all configured health checks before NGINX Plus sends traffic to it. If this is not specified, or is set to false, the server will be initially considered healthy. When combined with [slow-start](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start), it gives a new server more time to connect to databases and “warm up” before being asked to handle their full share of traffic. | ``bool`` | No | |``persistent`` | Set the initial “up” state for a server after reload if the server was considered healthy before reload. Enabling persistent requires that the mandatory parameter is also set to `true`. | ``bool`` | No | |``keepalive-time`` | Enables [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) connections for health checks and specifies the time during which requests can be processed through one keepalive connection. The default is ``60s``. | ``string`` | No | -{{% /table %}} +{{}} ### Upstream.SessionCookie @@ -502,7 +506,7 @@ See the [`sticky`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html? Note: This feature is supported only in NGINX Plus. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``enable`` | Enables session persistence with a session cookie for an upstream server. The default is ``false``. | ``boolean`` | No | @@ -513,7 +517,7 @@ Note: This feature is supported only in NGINX Plus. |``httpOnly`` | Adds the ``HttpOnly`` attribute to the cookie. | ``boolean`` | No | |``secure`` | Adds the ``Secure`` attribute to the cookie. | ``boolean`` | No | |``samesite`` | Adds the ``SameSite`` attribute to the cookie. The allowed values are: ``strict``, ``lax``, ``none`` | ``string`` | No | -{{% /table %}} +{{}} ### Header @@ -524,12 +528,12 @@ name: Host value: example.com ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the header. | ``string`` | Yes | |``value`` | The value of the header. | ``string`` | No | -{{% /table %}} +{{}} ### Action @@ -543,14 +547,14 @@ In the example below, client requests are passed to an upstream `coffee`: pass: coffee ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``pass`` | Passes requests to an upstream. The upstream with that name must be defined in the resource. | ``string`` | No | |``redirect`` | Redirects requests to a provided URL. | [action.redirect](#actionredirect) | No | |``return`` | Returns a preconfigured response. | [action.return](#actionreturn) | No | |``proxy`` | Passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers). | [action.proxy](#actionproxy) | No | -{{% /table %}} +{{}} \* -- an action must include exactly one of the following: `pass`, `redirect`, `return` or `proxy`. @@ -566,12 +570,12 @@ redirect: code: 301 ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme`` , ``$http_x_forwarded_proto`` , ``$request_uri`` , ``$host``. Variables must be enclosed in curly braces. For example: ``${host}${request_uri}``. | ``string`` | Yes | |``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | -{{% /table %}} +{{}} ### Action.Return @@ -589,14 +593,14 @@ return: value: espresso ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``code`` | The status code of the response. The allowed values are: ``2XX``, ``4XX`` or ``5XX``. The default is ``200``. | ``int`` | No | |``type`` | The MIME type of the response. The default is ``text/plain``. | ``string`` | No | |``body`` | The body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``Request is ${request_uri}\n``. | ``string`` | Yes | |``headers`` | The custom headers of the response. | [[]Action.Return.Header](#actionreturnheader) | No | -{{% /table %}} +{{}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing` and `$connections_waiting`. @@ -609,12 +613,12 @@ name: x-coffee value: espresso ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the header. | ``string`` | Yes | |``value`` | The value of the header. | ``string`` | Yes | -{{% /table %}} +{{}} ### Action.Proxy @@ -649,25 +653,25 @@ proxy: rewritePath: / ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | |``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | |``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | |``rewritePath`` | The rewritten URI. If the route path is a regular expression -- starts with `~` -- the `rewritePath` can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginxinc/kubernetes-ingress/tree/v3.5.2/examples/custom-resources/rewrites) example. | ``string`` | No | -{{% /table %}} +{{}} ### Action.Proxy.RequestHeaders The RequestHeaders field modifies the headers of the request to the proxied upstream server. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``pass`` | Passes the original request headers to the proxied upstream server. See the [proxy_pass_request_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_headers) directive for more information. Default is true. | ``bool`` | No | |``set`` | Allows redefining or appending fields to present request headers passed to the proxied upstream servers. See the [proxy_set_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive for more information. | [[]header](#actionproxyrequestheaderssetheader) | No | -{{% /table %}} +{{}} ### Action.Proxy.RequestHeaders.Set.Header @@ -678,19 +682,19 @@ name: My-Header value: My-Value ``` -It is possible to override the default value of the `Host` header, which the Ingress Controller sets to [`$host`](https://nginx.org/en/docs/http/ngx_http_core_module.html#var_host): +It is possible to override the default value of the `Host` header, which NGINX Ingress Controller sets to [`$host`](https://nginx.org/en/docs/http/ngx_http_core_module.html#var_host): ```yaml name: Host value: example.com ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the header. | ``string`` | Yes | |``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | -{{% /table %}} +{{}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). @@ -698,14 +702,14 @@ value: example.com The ResponseHeaders field modifies the headers of the response to the client. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``hide`` | The headers that will not be passed* in the response to the client from a proxied upstream server. See the [proxy_hide_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directive for more information. | ``[]string`` | No | |``pass`` | Allows passing the hidden header fields* to the client from a proxied upstream server. See the [proxy_pass_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directive for more information. | ``[]string`` | No | |``ignore`` | Disables processing of certain headers** to the client from a proxied upstream server. See the [proxy_ignore_headers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_headers) directive for more information. | ``[]string`` | No | |``add`` | Adds headers to the response to the client. | [[]addHeader](#addheader) | No | -{{% /table %}} +{{}} \* -- Default hidden headers are: `Date`, `Server`, `X-Pad` and `X-Accel-...`. @@ -721,17 +725,17 @@ value: My-Value always: true ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the header. | ``string`` | Yes | |``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | |``always`` | If set to true, add the header regardless of the response status code**. Default is false. See the [add_header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive for more information. | ``bool`` | No | -{{% /table %}} +{{}} \* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). -\*\* -- If `always` is false, the response header is added only if the response status code is any of `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` or `308`. +{{< note >}} If `always` is false, the response header is added only if the response status code is any of `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` or `308`. {{< /note >}} ### Split @@ -749,12 +753,12 @@ splits: pass: coffee-v2 ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``weight`` | The weight of an action. Must fall into the range ``0..100``. The sum of the weights of all splits must be equal to ``100``. | ``int`` | Yes | |``action`` | The action to perform for a request. | [action](#action) | Yes | -{{% /table %}} +{{}} ### Match @@ -800,21 +804,21 @@ action: pass: coffee ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``conditions`` | A list of conditions. Must include at least 1 condition. | [[]condition](#condition) | Yes | |``action`` | The action to perform for a request. | [action](#action) | No | |``splits`` | The splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | -{{% /table %}} +{{}} -\* -- a match must include exactly one of the following: `action` or `splits`. +{{< note >}} A match must include exactly one of the following: `action` or `splits`. {{< /note >}} ### Condition The condition defines a condition in a match. -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``header`` | The name of a header. Must consist of alphanumeric characters or ``-``. | ``string`` | No | @@ -822,9 +826,9 @@ The condition defines a condition in a match. |``argument`` | The name of an argument. Must consist of alphanumeric characters or ``_``. | ``string`` | No | |``variable`` | The name of an NGINX variable. Must start with ``$``. See the list of the supported variables below the table. | ``string`` | No | |``value`` | The value to match the condition against. How to define a value is shown below the table. | ``string`` | Yes | -{{% /table %}} +{{}} -\* -- a condition must include exactly one of the following: `header`, `cookie`, `argument` or `variable`. +{{< note >}} a condition must include exactly one of the following: `header`, `cookie`, `argument` or `variable`. {{< /note >}} Supported NGINX variables: `$args`, `$http2`, `$https`, `$remote_addr`, `$remote_port`, `$query_string`, `$request`, `$request_body`, `$request_uri`, `$request_method`, `$scheme`. Find the documentation for each variable [here](https://nginx.org/en/docs/varindex.html). @@ -838,7 +842,7 @@ The value supports two kinds of matching: - `!~^yes` -- negation of the previous regular expression that succeeds for strings like `YES`, `Yes123`, `noyes`. (The negation mechanism is not part of the PCRE syntax). - `~*no$` -- a case-insensitive regular expression that matches any string that ends with `no`. For example: `no`, `123no`, `123NO`. -**Note**: a value must not include any unescaped double quotes (`"`) and must not end with an unescaped backslash (`\`). For example, the following are invalid values: `some"value`, `somevalue\`. +{{< note >}} A value must not include any unescaped double quotes (`"`) and must not end with an unescaped backslash (`\`). For example, the following are invalid values: `some"value`, `somevalue\`. {{< /note >}} ### ErrorPage @@ -857,15 +861,15 @@ errorPages: body: "Original resource not found, but success!" ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``codes`` | A list of error status codes. | ``[]int`` | Yes | |``redirect`` | The redirect action for the given status codes. | [errorPage.Redirect](#errorpageredirect) | No | |``return`` | The canned response action for the given status codes. | [errorPage.Return](#errorpagereturn) | No | -{{% /table %}} +{{}} -\* -- an errorPage must include exactly one of the following: `return` or `redirect`. +{{< note >}} An errorPage must include exactly one of the following: `return` or `redirect`. {{< /note >}} ### ErrorPage.Redirect @@ -880,12 +884,12 @@ redirect: url: ${scheme}://cafe.example.com/error.html ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | |``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme`` and ``$http_x_forwarded_proto``. Variables must be enclosed in curly braces. For example: ``${scheme}``. | ``string`` | Yes | -{{% /table %}} +{{}} ### ErrorPage.Return @@ -905,14 +909,14 @@ return: value: ${upstream_status} ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``code`` | The status code of the response. The default is the status code of the original response. | ``int`` | No | |``type`` | The MIME type of the response. The default is ``text/html``. | ``string`` | No | |``body`` | The body of the response. Supported NGINX variable: ``$upstream_status`` . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | Yes | |``headers`` | The custom headers of the response. | [[]errorPage.Return.Header](#errorpagereturnheader) | No | -{{% /table %}} +{{}} ### ErrorPage.Return.Header @@ -923,12 +927,12 @@ name: x-debug-original-statuses value: ${upstream_status} ``` -{{% table %}} +{{}} |Field | Description | Type | Required | | ---| ---| ---| --- | |``name`` | The name of the header. | ``string`` | Yes | |``value`` | The value of the header. Supported NGINX variable: ``$upstream_status`` . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | No | -{{% /table %}} +{{}} ## Using VirtualServer and VirtualServerRoute @@ -938,7 +942,8 @@ For example, the following command creates a VirtualServer resource defined in ` ```shell kubectl apply -f cafe-virtual-server.yaml - +``` +```text virtualserver.k8s.nginx.org "cafe" created ``` @@ -946,14 +951,15 @@ You can get the resource by running: ```shell kubectl get virtualserver cafe - +``` +```text NAME STATE HOST IP PORTS AGE cafe Valid cafe.example.com 12.13.23.123 [80,443] 3m ``` -In the kubectl get and similar commands, you can also use the short name `vs` instead of `virtualserver`. +In `kubectl get` and similar commands, you can use the short name `vs` instead of `virtualserver`. -Working with VirtualServerRoute resources is analogous. In the kubectl commands, use `virtualserverroute` or the short name `vsr`. +Similarly, for VirtualServerRoute you can use `virtualserverroute` or the short name `vsr`. ### Using Snippets @@ -993,28 +999,14 @@ spec: pass: coffee ``` -Snippets are intended to be used by advanced NGINX users who need more control over the generated NGINX configuration. - -However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the [`enable-snippets`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-enable-snippets) command-line argument. - -Disadvantages of using snippets: - -- *Complexity*. To use snippets, you will need to: - - Understand NGINX configuration primitives and implement a correct NGINX configuration. - - Understand how the IC generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration. -- *Decreased robustness*. An incorrect snippet makes the NGINX config invalid which will lead to a failed reload. This will prevent any new configuration updates, including updates for the other VirtualServer and VirtualServerRoute resources until the snippet is fixed. -- *Security implications*. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress and VirtualServer resources. - -To help catch errors when using snippets, the Ingress Controller reports config reload errors in the logs as well as in the events and status field of VirtualServer and VirtualServerRoute resources. Additionally, a number of Prometheus metrics show the stats about failed reloads – `controller_nginx_last_reload_status` and `controller_nginx_reload_errors_total`. - -> Note that during a period when the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration. +For additional information, view the [Advanced configuration with Snippets]({{< relref "configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) topic. ### Validation Two types of validation are available for VirtualServer and VirtualServerRoute resources: - *Structural validation* by the `kubectl` and Kubernetes API server. -- *Comprehensive validation* by the Ingress Controller. +- *Comprehensive validation* by NGINX Ingress Controller. #### Structural Validation @@ -1026,31 +1018,34 @@ If you try to create (or update) a resource that violates the structural schema ```shell kubectl apply -f cafe-virtual-server.yaml - - error: error validating "cafe-virtual-server.yaml": error validating data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.VirtualServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + ```text + error: error validating "cafe-virtual-server.yaml": error validating data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.VirtualServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false ``` - Example of Kubernetes API server validation: ```shell kubectl apply -f cafe-virtual-server.yaml --validate=false - - The VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: - spec.upstreams.port in body must be of type integer: "string" + ``` + ```text + The VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.upstreams.port in body must be of type integer: "string" ``` -If a resource is not rejected (it doesn't violate the structural schema), the Ingress Controller will validate it further. +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. #### Comprehensive Validation -The Ingress Controller validates the fields of the VirtualServer and VirtualServerRoute resources. If a resource is invalid, the Ingress Controller will reject it: the resource will continue to exist in the cluster, but the Ingress Controller will ignore it. +NGINX Ingress Controller validates the fields of the VirtualServer and VirtualServerRoute resources. If a resource is invalid, NGINX Ingress Controller will reject it: the resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. -You can check if the Ingress Controller successfully applied the configuration for a VirtualServer. For our example `cafe` VirtualServer, we can run: +You can check if NGINX Ingress Controller successfully applied the configuration for a VirtualServer. For our example `cafe` VirtualServer, we can run: ```shell kubectl describe vs cafe - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -1059,12 +1054,13 @@ Events: Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. -If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a VirtualServer `cafe` with two upstream with the same name `tea`, you will get: +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a VirtualServer `cafe` with two upstream with the same name `tea`, you will get: ```shell kubectl describe vs cafe - -. . . +``` +```text +... Events: Type Reason Age From Message ---- ------ ---- ---- ------- @@ -1077,8 +1073,9 @@ Additionally, this information is also available in the `status` field of the Vi ```shell kubectl describe vs cafe - -. . . +``` +```text +... Status: External Endpoints: Ip: 12.13.23.123 @@ -1088,11 +1085,11 @@ Status: State: Invalid ``` -The Ingress Controller validates VirtualServerRoute resources in a similar way. +NGINX Ingress Controller validates VirtualServerRoute resources in a similar way. -**Note**: If you make an existing resource invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX. +**Note**: If you make an existing resource invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. -## Customization via ConfigMap +## Customization using ConfigMap You can customize the NGINX configuration for VirtualServer and VirtualServerRoutes resources using the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource). Most of the ConfigMap keys are supported, with the following exceptions: diff --git a/docs/content/installation/integrations/app-protect-waf/installation.md b/docs/content/installation/integrations/app-protect-waf/installation.md index 98f1a632ff..5f48967649 100644 --- a/docs/content/installation/integrations/app-protect-waf/installation.md +++ b/docs/content/installation/integrations/app-protect-waf/installation.md @@ -68,7 +68,7 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA ### Makefile targets {#makefile-targets} -{{}} +{{}} | Makefile Target | Description | Compatible Systems | |---------------------------|-------------------------------------------------------------------|---------------------| | **debian-image-nap-plus** | Builds a Debian-based image with NGINX Plus and the [NGINX App Protect WAF](/nginx-app-protect-waf/) module. | Debian | @@ -81,13 +81,6 @@ Follow these steps to build the NGINX Controller Image with NGINX App Protect WA {{}} For the complete list of _Makefile_ targets and customizable variables, see the [Building NGINX Ingress Controller]({{< relref "installation/building-nginx-ingress-controller.md#makefile-details" >}}) guide. {{}} -If you intend to use [external references](/nginx-app-protect-waf/v4/configuration/#external-references) in NGINX App Protect WAF policies, you may want to provide a custom CA certificate to authenticate with the hosting server. - -To do so, place the `*.crt` file in the build folder and uncomment the lines following this comment: -`#Uncomment the lines below if you want to install a custom CA certificate` - -{{}} External references are deprecated in NGINX Ingress Controller and will not be supported in future releases. {{}} - --- ## Push the image to your private registry