From 35a237cc5aa929f1fe257071b00d471f84f13b0d Mon Sep 17 00:00:00 2001 From: Michael Pleshakov Date: Thu, 25 Oct 2018 17:14:04 +0100 Subject: [PATCH] Improve and move the customization example - Improve the customization example - Move it to the docs folder - Remove the example yaml files --- README.md | 2 +- docs/configmap-and-annotations.md | 176 ++++++++++++++++++ docs/custom-annotations.md | 2 +- docs/installation.md | 2 +- docs/nginx-ingress-controllers.md | 4 +- docs/report-ingress-status.md | 2 +- examples/custom-templates/README.md | 2 +- examples/customization/README.md | 132 +------------ .../cafe-ingress-with-annotations.yaml | 32 ---- examples/customization/nginx-config.yaml | 69 ------- examples/tcp-udp/README.md | 2 +- 11 files changed, 185 insertions(+), 240 deletions(-) create mode 100644 docs/configmap-and-annotations.md delete mode 100644 examples/customization/cafe-ingress-with-annotations.yaml delete mode 100644 examples/customization/nginx-config.yaml diff --git a/README.md b/README.md index c8b70722dd..7ba826256a 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ We provide the following extensions to our Ingress controller: * [Session Persistence](examples/session-persistence) (NGINX Plus only), which guarantees that all the requests from the same client are always passed to the same backend container. * [Support for JWTs](examples/jwt) (NGINX Plus only), which allows NGINX Plus to authenticate requests by validating JSON Web Tokens (JWTs). -Additional extensions as well as a mechanism to customize NGINX configuration are available. See [examples/customization](examples/customization). +Additional extensions as well as a mechanism to customize NGINX configuration are available. See [ConfigMap and Annotations doc](docs/configmap-and-annotations.md). ## NGINX Ingress Controller Releases diff --git a/docs/configmap-and-annotations.md b/docs/configmap-and-annotations.md new file mode 100644 index 0000000000..93a8c59ecf --- /dev/null +++ b/docs/configmap-and-annotations.md @@ -0,0 +1,176 @@ +# ConfigMap and Annotations + +The Ingress resource only allows you to use basic NGINX features -- host and path-based routing and TLS termination. Thus, advanced features like rewriting the request URI or inserting additional response headers are not available. + +In addition to using advanced features, often it is necessary to customize or fine tune NGINX behavior. For example, set the number of worker processes or customize the access log format. + +Special **ConfigMap** resource and **Annotations** applied to an Ingress resource allow you to: +* Use advanced NGINX features. +* Customize NGINX behavior. + +This document describes how to use the ConfigMap resource and Annotations and what features and customization options are available. + +## Using ConfigMap + +1. Our [installation instructions](installation.md) deploy an empty ConfigMap while the [default installation manifests](../deployments) specify it in the command-line arguments of the Ingress controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use through the [command-line arguments](cli-arguments.md) of the Ingress controller. + +1. Create a ConfigMap file with the name *nginx-config.yaml* and set the values +that make sense for your setup: + ```yaml + kind: ConfigMap + apiVersion: v1 + metadata: + name: nginx-config + namespace: nginx-ingress + data: + proxy-connect-timeout: "10s" + proxy-read-timeout: "10s" + client-max-body-size: "2m" + ``` + See the section [Summary of ConfigMap and Annotations](#Summary-of-ConfigMap-and-Annotations) for the explanation of the available ConfigMap keys (such as `proxy-connect-timeout` in this example). + +1. Create a new (or update the existing) ConfigMap resource: + ``` + $ kubectl apply -f nginx-config.yaml + ``` + The NGINX configuration will be updated. + +## Using Annotations + +Here is an example of using annotations to customize the configuration for a particular Ingress resource: +```yaml +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: cafe-ingress-with-annotations + annotations: + nginx.org/proxy-connect-timeout: "30s" + nginx.org/proxy-read-timeout: "20s" + nginx.org/client-max-body-size: "4m" + nginx.org/server-snippets: | + location / { + return 302 /coffee; + } +spec: + rules: + - host: cafe.example.com + http: + paths: + - path: /tea + backend: + serviceName: tea-svc + servicePort: 80 + - path: /coffee + backend: + serviceName: coffee-svc + servicePort: 80 +``` +**Note**: Annotations take precedence over the ConfigMap. + +## Summary of ConfigMap and Annotations + + +**Note**: The annotations that start with `nginx.com` are only supported with NGINX Plus. + +### Ingress Controller (Not Related to NGINX Configuration) + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| `kubernetes.io/ingress.class` | N/A | Specifies which Ingress controller must handle the Ingress resource. Set to `nginx` to make NGINX Ingress controller handle it. | N/A | [Multiple Ingress controllers](../examples/multiple-ingress-controllers). | +| N/A | `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](report-ingress-status.md). | + +### General Customization + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| `nginx.org/proxy-connect-timeout` | `proxy-connect-timeout` | Sets the value of the [proxy_connect_timeout](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](http://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | `60s` | | +| `nginx.org/client-max-body-size` | `client-max-body-size` | Sets the value of the [client_max_body_size](http://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](http://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](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | `1024m` | | +| N/A | `set-real-ip-from` | Sets the value of the [set_real_ip_from](http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | +| N/A | `real-ip-header` | Sets the value of the [real_ip_header](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | `X-Real-IP`| | +| N/A | `real-ip-recursive` | Enables or disables the [real_ip_recursive](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | `False`| | +| `nginx.org/server-tokens` | `server-tokens` | Enables or disables the [server_tokens](http://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`| | +| N/A | `worker-processes` | Sets the value of the [worker_processes](http://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | `auto` | | +| N/A | `worker-rlimit-nofile` | Sets the value of the [worker_rlimit_nofile](http://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | +| N/A | `worker-connections` | Sets the value of the [worker_connections](http://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive. | `1024` | | +| N/A | `worker-cpu-affinity` | Sets the value of the [worker_cpu_affinity](http://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity) directive. | N/A | | +| N/A | `worker-shutdown-timeout` | Sets the value of the [worker_shutdown_timeout](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout) directive. | N/A | | +| N/A | `server-names-hash-bucket-size` | Sets the value of the [server_names_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | Depends on the size of the processor’s cache line. | | +| N/A | `server-names-hash-max-size` | Sets the value of the [server_names_hash_max_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | `512` | | + +### Logging + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| N/A | `error-log-level` | Sets the global [error log level](http://nginx.org/en/docs/ngx_core_module.html#error_log) for NGINX. | `notice` | | +| N/A | `log-format` | Sets the custom [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format). | See the [template file](../internal/nginx/templates/nginx.tmpl). | | +| N/A | `stream-log-format` | Sets the custom [log format](http://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format) for TCP/UDP load balancing. | See the [template file](../internal/nginx/templates/nginx.tmpl). | | + +### Request URI/Header Manipulation + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| `nginx.org/proxy-hide-headers` | `proxy-hide-headers` | Sets the value of one or more [proxy_hide_header](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directives. Example: `"nginx.org/proxy-pass-headers": "header-a,header-b"` | N/A | | +| `nginx.org/rewrites` | N/A | Configures URI rewriting. | N/A | [Rewrites Support](../examples/rewrites). | + +### Auth and SSL/TLS + +| 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`| | +| N/A | `ssl-protocols` | Sets the value of the [ssl_protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | `TLSv1 TLSv1.1 TLSv1.2`| | +| N/A | `ssl-prefer-server-ciphers` | Enables or disables the [ssl_prefer_server_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | `False`| | +| N/A | `ssl-ciphers` | Sets the value of the [ssl_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | `HIGH:!aNULL:!MD5`| | +| N/A | `ssl-dhparam-file` | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file. | 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)](../examples/jwt). | +| `nginx.com/jwt-realm` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](../examples/jwt). | +| `nginx.com/jwt-token` | N/A | Specifies a variable that contains JSON Web Token. | By default, a JWT is expected in the `Authorization` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](../examples/jwt). | +| `nginx.com/jwt-login-url` | N/A | Specifies a URL to which a client is redirected in case of an invalid or missing JWT. | N/A | [Support for JSON Web Tokens (JWTs)](../examples/jwt). | + +### Listeners + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| N/A | `http2` | Enables HTTP/2 in servers with SSL enabled. | `False` | +| `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]` | | +| N/A | `proxy-protocol` | Enables PROXY Protocol for incoming connections. | `False` | [Proxy Protocol](../examples/proxy-protocol). | + +### Backend Services (Upstreams) + +| 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 when connecting to the endpoints of services. | N/A | [SSL Services Support](../examples/ssl-services). | +| `nginx.org/grpc-services` | N/A | Enables gRPC for services. | N/A | [GRPC Services Support](../examples/grpc-services).| +| `nginx.org/websocket-services` | N/A | Enables WebSocket for services. | N/A | [WebSocket support](../examples/websocket). | +| `nginx.org/max-fails` | `max-fails` | Sets the value of the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the `server` directive. | `1` | | +| `nginx.org/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](../examples/session-persistence). | +| `nginx.org/keepalive` | `keepalive` | Sets the value of the [keepalive](http://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](../examples/health-checks). | +| `nginx.com/health-checks-mandatory` | N/A | Configures active health checks as mandatory. | `False` | [Support for Active Health Checks](../examples/health-checks). | +| `nginx.com/health-checks-mandatory-queue` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | `0` | [Support for Active Health Checks](../examples/health-checks). | +| `nginx.com/slow-start` | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly added servers, configure [mandatory active health checks](../examples/health-checks). | `"0s"` | | + + +### Snippets and Custom Templates + +| Annotation | ConfigMap Key | Description | Default | Example | +| ---------- | -------------- | ----------- | ------- | ------- | +| N/A | `main-snippets` | Sets a custom snippet in main context. | N/A | | +| N/A | `http-snippets` | Sets a custom snippet in http context. | N/A | | +| `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 | | +| N/A | `stream-snippets` | Sets a custom snippet in stream context. | N/A | [Support for TCP/UDP Load Balancing](../examples/tcp-udp). | +| N/A | `main-template` | Sets the main NGINX configuration template. | By default the template is read from the file in the container. | [Custom Templates](../examples/custom-templates). | +| N/A | `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](../examples/custom-templates). | diff --git a/docs/custom-annotations.md b/docs/custom-annotations.md index 877f1d6a44..17ca45c871 100644 --- a/docs/custom-annotations.md +++ b/docs/custom-annotations.md @@ -4,7 +4,7 @@ Custom annotations enable you to quickly extend the Ingress Controller to suppor ## What are Custom Annotations -NGINX Ingress Controller supports a number of annotations 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](../examples/customization). +NGINX Ingress Controller supports a number of annotations 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](configmap-and-annotations.md). The annotations are provided only for the most common features and use cases, meaning that not every NGINX feature or a customization option is available through the annotations. Additionally, even if an annotation is available, it might not give you the satisfactory level of control of a particular NGINX feature. diff --git a/docs/installation.md b/docs/installation.md index 2216adcb64..49412f1330 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -24,7 +24,7 @@ The installation manifests are located in the [deployments](../deployments) fold **Note**: The default server returns the Not Found page with the 404 status code for all requests for domains for which there are no Ingress rules defined. For testing purposes we include a self-signed certificate and key that we generated. However, we recommend that you use your own certificate and key. -1. Create a config map for customizing NGINX configuration (read more about customization [here](../examples/customization)): +1. Create a config map for customizing NGINX configuration (read more about customization [here](configmap-and-annotations.md)): ``` $ kubectl apply -f common/nginx-config.yaml ``` diff --git a/docs/nginx-ingress-controllers.md b/docs/nginx-ingress-controllers.md index f25a0ff6df..105355af8d 100644 --- a/docs/nginx-ingress-controllers.md +++ b/docs/nginx-ingress-controllers.md @@ -18,8 +18,8 @@ The table below summarizes the key difference between nginxinc/kubernetes-ingres | Commercial support | N/A | N/A | Included | | **Load balancing configuration** | | Merging Ingress rules with the same host | Supported | Supported | Supported | -| HTTP load balancing extensions - Annotations | See the [supported annotations](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/annotations.md) | See the [supported annotations](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/customization) | See the [supported annotations](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/customization)| -| HTTP load balancing extensions -- ConfigMap | See the [supported ConfigMap keys](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/configmap.md) | See the [supported ConfigMap keys](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/customization) | See the [supported ConfigMap keys](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/customization) | +| HTTP load balancing extensions - Annotations | See the [supported annotations](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/annotations.md) | See the [supported annotations](configmap-and-annotations.md) | See the [supported annotations](configmap-and-annotations.md)| +| HTTP load balancing extensions -- ConfigMap | See the [supported ConfigMap keys](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/configmap.md) | See the [supported ConfigMap keys](configmap-and-annotations.md) | See the [supported ConfigMap keys](configmap-and-annotations.md) | | TCP/UDP | Supported via a ConfigMap | Supported via a ConfigMap with native NGINX configuration | Supported via a ConfigMap with native NGINX configuration | | Websocket | Supported | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/websocket) | Supported via an [annotation](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/websocket) | | TCP SSL Passthrough | Supported via a ConfigMap | Not supported | Not supported | diff --git a/docs/report-ingress-status.md b/docs/report-ingress-status.md index b166c3115d..88b2b64509 100644 --- a/docs/report-ingress-status.md +++ b/docs/report-ingress-status.md @@ -13,7 +13,7 @@ The Ingress controller must be configured to report an Ingress status: 1. Use the command-line flag `-report-ingress-status`. 2. Define a source for an external address. This can be either of: - 1. A user defined address, specified in the `external-status-address` [ConfigMap key](../examples/customization). + 1. A user defined address, specified in the `external-status-address` [ConfigMap key](configmap-and-annotations.md). 2. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. 3. If you're running multiple replicas of the Ingress controller, enable leader election with the `-enable-leader-election` flag to ensure that only one replica updates an Ingress status. diff --git a/examples/custom-templates/README.md b/examples/custom-templates/README.md index b0781a95b2..436e5bf917 100644 --- a/examples/custom-templates/README.md +++ b/examples/custom-templates/README.md @@ -1,6 +1,6 @@ # Custom Templates -The Ingress controller allows you to customize your templates through a [ConfigMap](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples/customization) via the following keys: +The Ingress controller allows you to customize your templates through a [ConfigMap](../../docs/configmap-and-annotations.md) via the following keys: * `main-template` - Sets the main NGINX configuration template. * `ingress-template` - Sets the Ingress NGINX configuration template for an Ingress resource. diff --git a/examples/customization/README.md b/examples/customization/README.md index 17ef49e27b..2ab97d0f03 100644 --- a/examples/customization/README.md +++ b/examples/customization/README.md @@ -1,133 +1,3 @@ # Customization of NGINX Configuration -You can customize the NGINX configuration using ConfigMaps or Annotations. - -The table below summarizes all of the options. For some of them, there are examples in the [examples](..) folder. - -**Note**: The annotations that start with `nginx.com` are only supported with NGINX Plus Ingress controller. - -| Annotation | ConfigMaps Key | Description | Default | Example | -| ---------- | -------------- | ----------- | ------- | ------- | -| `kubernetes.io/ingress.class` | N/A | Specifies which Ingress controller must handle the Ingress resource. Set to `nginx` to make NGINX Ingress controller handle it. | N/A | [Multiple Ingress controllers](../multiple-ingress-controllers). | -| `nginx.org/proxy-connect-timeout` | `proxy-connect-timeout` | Sets the value of the [proxy_connect_timeout](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](http://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | `60s` | | -| `nginx.org/client-max-body-size` | `client-max-body-size` | Sets the value of the [client_max_body_size](http://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](http://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](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](http://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](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | `1024m` | | -| `nginx.org/proxy-hide-headers` | `proxy-hide-headers` | Sets the value of one or more [proxy_hide_header](http://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](http://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 | | -| N/A | `server-names-hash-bucket-size` | Sets the value of the [server_names_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | Depends on the size of the processor’s cache line. | | -| N/A | `server-names-hash-max-size` | Sets the value of the [server_names_hash_max_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | `512` | | -| N/A | `http2` | Enables HTTP/2 in servers with SSL enabled. | `False` | -| `nginx.org/redirect-to-https` | `redirect-to-https` | Sets the 301 redirect rule based on the value of the `http_x_forwarded_proto` header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress controller — see [115](https://github.com/nginxinc/kubernetes-ingress/issues/115) | `False` | | -| `ingress.kubernetes.io/ssl-redirect` | `ssl-redirect` | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | `True` | | -| N/A | `error-log-level` | Sets the global [error log level](http://nginx.org/en/docs/ngx_core_module.html#error_log) for NGINX. | `notice` | | -| N/A | `log-format` | Sets the custom [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format). | See the [template file](../../internal/nginx/templates/nginx.tmpl). | | -| `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`| | -| N/A | `ssl-protocols` | Sets the value of the [ssl_protocols](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | `TLSv1 TLSv1.1 TLSv1.2`| | -| N/A | `ssl-prefer-server-ciphers` | Enables or disables the [ssl_prefer_server_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | `False`| | -| N/A | `ssl-ciphers` | Sets the value of the [ssl_ciphers](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | `HIGH:!aNULL:!MD5`| | -| N/A | `ssl-dhparam-file` | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file. | N/A | | -| N/A | `set-real-ip-from` | Sets the value of the [set_real_ip_from](http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | -| N/A | `real-ip-header` | Sets the value of the [real_ip_header](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | `X-Real-IP`| | -| N/A | `real-ip-recursive` | Enables or disables the [real_ip_recursive](http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | `False`| | -| `nginx.org/server-tokens` | `server-tokens` | Enables or disables the [server_tokens](http://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`| | -| N/A | `main-snippets` | Sets a custom snippet in main context. | N/A | | -| N/A | `http-snippets` | Sets a custom snippet in http context. | N/A | | -| N/A | `main-template` | Sets the main NGINX configuration template. | By default the template is read from the file in the container. | [Custom Templates](../custom-templates). | -| N/A | `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](../custom-templates). | -| `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 | | -| `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/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]` | | -| N/A | `worker-processes` | Sets the value of the [worker_processes](http://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | `auto` | | -| N/A | `worker-rlimit-nofile` | Sets the value of the [worker_rlimit_nofile](http://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | -| N/A | `worker-connections` | Sets the value of the [worker_connections](http://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive. | `1024` | | -| N/A | `worker-cpu-affinity` | Sets the value of the [worker_cpu_affinity](http://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity) directive. | N/A | | -| N/A | `worker-shutdown-timeout` | Sets the value of the [worker_shutdown_timeout](http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout) directive. | N/A | | -| `nginx.org/keepalive` | `keepalive` | Sets the value of the [keepalive](http://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` | | -| N/A | `proxy-protocol` | Enables PROXY Protocol for incoming connections. | `False` | [Proxy Protocol](../proxy-protocol). | -| `nginx.org/rewrites` | N/A | Configures URI rewriting. | N/A | [Rewrites Support](../rewrites). | -| `nginx.org/ssl-services` | N/A | Enables HTTPS when connecting to the endpoints of services. | N/A | [SSL Services Support](../ssl-services). | -| `nginx.org/grpc-services` | N/A | Enables gRPC for services. | N/A | [GRPC Services Support](../grpc-services).| -| `nginx.org/websocket-services` | N/A | Enables WebSocket for services. | N/A | [WebSocket support](../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/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](../session-persistence). | -| `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)](../jwt). | -| `nginx.com/jwt-realm` | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](../jwt). | -| `nginx.com/jwt-token` | N/A | Specifies a variable that contains JSON Web Token. | By default, a JWT is expected in the `Authorization` header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](../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)](../jwt). | -| `nginx.com/health-checks` | N/A | Enables active health checks. | `False` | [Support for Active Health Checks](../health-checks). | -| `nginx.com/health-checks-mandatory` | N/A | Configures active health checks as mandatory. | `False` | [Support for Active Health Checks](../health-checks). | -| `nginx.com/health-checks-mandatory-queue` | N/A | When active health checks are mandatory, configures a queue for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. | `0` | [Support for Active Health Checks](../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](../health-checks). | `"0s"` | | -| N/A | `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](../../docs/report-ingress-status.md). | -| N/A | `stream-snippets` | Sets a custom snippet in stream context. | N/A | [Support for TCP/UDP Load Balancing](../tcp-udp). | -| N/A | `stream-log-format` | Sets the custom [log format](http://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format) for TCP/UDP load balancing. | See the [template file](../../internal/nginx/templates/nginx.tmpl). | | - -## Using ConfigMaps - -1. Make sure that you specify the configmaps resource to use when you start an Ingress controller. -For example, `-nginx-configmaps=default/nginx-config`, where we specify -the config map to use with the following format: `/`. - -1. Create a configmaps file with the name *nginx-config.yaml* and set the values -that make sense for your setup: - ```yaml - kind: ConfigMap - apiVersion: v1 - metadata: - name: nginx-config - data: - proxy-connect-timeout: "10s" - proxy-read-timeout: "10s" - client-max-body-size: "2m" - ``` - See the **nginx-config.yaml** from this directory for a complete example. - -1. Create a configmaps resource: - ``` - $ kubectl apply -f nginx-config.yaml - ``` - The NGINX configuration will be updated. - -1. If you want to update the configmaps, update the file and run the apply command again: - ``` - $ kubectl apply -f nginx-config.yaml - ``` - The NGINX configuration will be updated. - -## Using Annotations - -If you want to customize the configuration for a particular Ingress resource only, you can use Annotations. -Here is an example (**cafe-ingress-with-annotations.yaml**): -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: cafe-ingress-with-annotations - annotations: - nginx.org/proxy-connect-timeout: "30s" - nginx.org/proxy-read-timeout: "20s" - nginx.org/client-max-body-size: "4m" -spec: - rules: - - host: cafe.example.com - http: - paths: - - path: /tea - backend: - serviceName: tea-svc - servicePort: 80 - - path: /coffee - backend: - serviceName: coffee-svc - servicePort: 80 -``` -Annotations take precedence over ConfigMaps. +This example has been transformed into the [ConfigMap and Annotations doc](../../docs/configmap-and-annotations.md). \ No newline at end of file diff --git a/examples/customization/cafe-ingress-with-annotations.yaml b/examples/customization/cafe-ingress-with-annotations.yaml deleted file mode 100644 index fec0ecd2e0..0000000000 --- a/examples/customization/cafe-ingress-with-annotations.yaml +++ /dev/null @@ -1,32 +0,0 @@ -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: cafe-ingress-with-annotations - annotations: - nginx.org/proxy-connect-timeout: "30s" - nginx.org/proxy-read-timeout: "20s" - nginx.org/client-max-body-size: "4m" - nginx.org/location-snippets: | - if ($ssl_client_verify = SUCCESS) { - set $auth_basic off; - } - if ($ssl_client_verify != SUCCESS) { - set $auth_basic "Restricted"; - } - auth_basic $auth_basic; - auth_basic_user_file "/var/run/secrets/nginx.org/auth-basic-file"; - nginx.org/server-snippets: | - ssl_verify_client optional; -spec: - rules: - - host: cafe.example.com - http: - paths: - - path: /tea - backend: - serviceName: tea-svc - servicePort: 80 - - path: /coffee - backend: - serviceName: coffee-svc - servicePort: 80 diff --git a/examples/customization/nginx-config.yaml b/examples/customization/nginx-config.yaml deleted file mode 100644 index bc63915350..0000000000 --- a/examples/customization/nginx-config.yaml +++ /dev/null @@ -1,69 +0,0 @@ -kind: ConfigMap -apiVersion: v1 -metadata: - name: nginx-config - namespace: nginx-ingress -data: - proxy-connect-timeout: "10s" # default is "60s". Sets the value of proxy_connect_timeout and grpc_connect_timeout directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout , http://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout - proxy-read-timeout: "10s" # default is "60s". Sets the value of proxy_read_timeout and grpc_read_timeout directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout , http://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout - proxy-hide-headers: "header-a,header-b" # No default. Sets the value of one or more proxy_hide_header directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header - proxy-pass-headers: "header-a,header-b" # No default. Sets the value of one or more proxy_pass_header directives. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header - client-max-body-size: "2m" # default is "1m". See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size - server-names-hash-bucket-size: "64" # default value depends on the size of the processor’s cache line. See http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size - server-names-hash-max-size: "1024" # default is "512". See http://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size - http2: "True" # default is "False". Enables HTTP/2 in servers with SSL enabled. See https://nginx.org/en/docs/http/ngx_http_v2_module.html - proxy-buffering: "False" # default is "True". Enables or disables buffering of responses from the proxied server. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering - proxy-buffers: "16 8k" # default value depends on the platform. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers - proxy-buffer-size: "2k" # default value depends on the platform. Sets proxy_buffer_size and grpc_buffer_size. See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size , http://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size - proxy-max-temp-file-size: "0" # default is "1024m". See http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size - log-format: '{ "@timestamp": "$time_iso8601", "@version": "1", "clientip": "$remote_addr", "tag": "ingress", "remote_user": "$remote_user", "bytes": $bytes_sent, "duration": $request_time, "status": $status, "request": "$request_uri", "urlpath": "$uri", "urlquery": "$args", "method": "$request_method", "referer": "$http_referer", "useragent": "$http_user_agent", "software": "nginx", "version": "$nginx_version", "host": "$host", "upstream": "$upstream_addr", "upstream-status": "$upstream_status" }' - # log-format default is set in the nginx.conf.tmpl file. Also see http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format - hsts: "True" # default is "False". Enables HTTP Strict Transport Security (HSTS): the HSTS header is added to the responses from backends. See https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/ - hsts-max-age: "31536000" # default is 2592000 (1 month). - hsts-include-subdomains: "True" # default is "False". - ssl-protocols: "TLSv1.2" # default is "TLSv1 TLSv1.1 TLSv1.2". See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols - ssl-prefer-server-ciphers: "True" # default is "False". Enables or disables the ssl_prefer_server_ciphers directive. See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers - ssl-ciphers: "HIGH:!aNULL:!MD5" # default is "HIGH:!aNULL:!MD5". See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers - ssl-dhparam-file: | - -----BEGIN DH PARAMETERS----- - ... - -----END DH PARAMETERS----- - # Sets the content of the dhparam file. The controller will create the file and set the value of the ssl_dhparam directive with the path of the file. Also see http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam - set-real-ip-from: "192.168.192.168" # No default. Sets the value of the set_real_ip_from directive. See http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from - real-ip-header: "proxy_protocol" # default is X-Real-IP. Sets the value of the real_ip_header directive. http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header - real-ip-recursive: "True" # default is "False". Enables or disables the real_ip_recursive directive. See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive - server-tokens: "False" # default is "True". Enables or disables the server_tokens directive. See http://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens - main-snippets: | # No default. Pipe is used for multiple line snippets. - load_module "modules/ngx_http_geoip_module.so"; - load_module "modules/ngx_stream_module.so"; - http-snippets: | # Pipe is used for multiple line snippets. Make sure the snippet is not a default value, in order to avoid duplication. - map $uri $new_uri { - /old.html /index.html; - } - server-snippets: | # No default. Pipe is used for multiple line snippets. Make sure the snippet is not a default value, in order to avoid duplication. - # Old website redirect - if ($new_uri) { - rewrite ^ $new_uri permanent; - } - lb-method: "round_robin" # default is random two least_conn. Sets the load balancing method for upstreams. See https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method - location-snippets: | # No default. Pipe is used for multiple line snippets. Make sure the snippet is not a default value, in order to avoid duplication. - proxy_temp_path /var/nginx/proxy_temp; - charset koi8-r; - worker-processes: "1" # default is "auto". Sets the value of the worker_processes directive. See http://nginx.org/en/docs/ngx_core_module.html#worker_processes - worker-rlimit-nofile: "65536" # No default. Sets the value of the worker_rlimit_nofile directive. See http://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile - worker-connections: "10240" # default is "1024". Sets the value of the worker_connections directive. See http://nginx.org/en/docs/ngx_core_module.html#worker_connections - worker-cpu-affinity: "auto" # No default. Sets the value of the worker_cpu_affinity directive. See http://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity - worker-shutdown-timeout: "5m" # No default. Sets the value of the worker_shutdown_timeout directive. See http://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout - keepalive: "32" # default is 0. When > 0, sets the value of the keepalive directive and adds 'proxy_set_header Connection "";' to a location block. See http://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive - max-fails: "0" # default is 1. Sets the value of the max_fails parameter of the `server` directive. See https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails - fail-timeout: "5s" # default is 10s. Sets the value of the fail_timeout parameter of the `server` directive. See https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout - error-log-level: "crit" # default is "notice". Sets the value of the error-log-level directive. Can be debug, info, notice, warn, error, crit, alert, or emerg. See http://nginx.org/en/docs/ngx_core_module.html#error_log - stream-log-format: "$remote_addr $protocol" # stream-log-format default is set in the nginx.conf.tmpl file. Also see http://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format - stream-snippets: | - upstream tcp-coffee { - server tcp-coffee-svc.default.svc.cluster.local:9944; - } - server { - listen 4456; - proxy_pass tcp-coffee; - } diff --git a/examples/tcp-udp/README.md b/examples/tcp-udp/README.md index c479001562..030d9bd175 100644 --- a/examples/tcp-udp/README.md +++ b/examples/tcp-udp/README.md @@ -1,6 +1,6 @@ # Support for TCP/UDP Load Balancing -In this example we deploy the NGINX or NGINX Plus Ingress controller, a DNS server and then configure both TCP and UDP load balancing for the DNS server using the `stream-snippets` [ConfigMap key](../customization). +In this example we deploy the NGINX or NGINX Plus Ingress controller, a DNS server and then configure both TCP and UDP load balancing for the DNS server using the `stream-snippets` [ConfigMap key](../../docs/configmap-and-annotations.md). The standard Kubernetes Ingress resources assume that all traffic is HTTP-based; they do not cater for the case of basic TCP or UDP load balancing. In this example, we use the `stream-snippets` ConfigMap key to embed the required TCP and UDP load-balancing configuration directly into the `stream{}` block of the NGINX configuration file.