diff --git a/docs/deploy/index.md b/docs/deploy/index.md index 7ee1864dc..1abbc3e53 100644 --- a/docs/deploy/index.md +++ b/docs/deploy/index.md @@ -158,7 +158,7 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/mast ``` !!! tip - For extended notes regarding deployments on bare-metal, see [Bare-metal considerations](./baremetal.md/). + For extended notes regarding deployments on bare-metal, see [Bare-metal considerations](./baremetal.md). ### Verify installation diff --git a/docs/examples/customization/configuration-snippets/README.md b/docs/examples/customization/configuration-snippets/README.md index 044657f34..11b713faf 100644 --- a/docs/examples/customization/configuration-snippets/README.md +++ b/docs/examples/customization/configuration-snippets/README.md @@ -2,7 +2,7 @@ ## Ingress -The Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at [this example](/examples/customization/custom-headers/README). +The Ingress in this example adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at [this example](../custom-headers/README.md). ```console $ kubectl apply -f ingress.yaml diff --git a/docs/user-guide/cli-arguments.md b/docs/user-guide/cli-arguments.md index aa273061a..ac1fa2909 100644 --- a/docs/user-guide/cli-arguments.md +++ b/docs/user-guide/cli-arguments.md @@ -38,6 +38,8 @@ They are set in the container spec of the `nginx-ingress-controller` Deployment | `--stderrthreshold severity` | logs at or above this threshold go to stderr (default 2) | | `--sync-period duration` | Period at which the controller forces the repopulation of its local object stores. Disabled by default. | | `--sync-rate-limit float32` | Define the sync frequency upper limit (default 0.3) | +| `--tcp-services-configmap string` | Name of the ConfigMap containing the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form "namespace/name:port", where "port" can either be a port number or name. TCP ports 80 and 443 are reserved by the controller for servicing HTTP traffic. | +| `--udp-services-configmap string` | Name of the ConfigMap containing the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is a reference to a Service in the form "namespace/name:port", where "port" can either be a port name or number. | | `--update-status` | Update the load-balancer status of Ingress objects this controller satisfies. Requires setting the publish-service parameter to a valid Service reference. (default true) | | `--update-status-on-shutdown` | Update the load-balancer status of Ingress objects when the controller shuts down. Requires the update-status parameter. (default true) | | `-v`, `--v Level` | log level for V logs | diff --git a/docs/user-guide/exposing-tcp-udp-services.md b/docs/user-guide/exposing-tcp-udp-services.md new file mode 100644 index 000000000..5268f0081 --- /dev/null +++ b/docs/user-guide/exposing-tcp-udp-services.md @@ -0,0 +1,63 @@ +# Exposing TCP and UDP services + +Ingress does not support TCP or UDP services. For this reason this Ingress controller uses the flags `--tcp-services-configmap` and `--udp-services-configmap` to point to an existing config map where the key is the external port to use and the value indicates the service to expose using the format: +`::[PROXY]:[PROXY]` + +It is also possible to use a number or the name of the port. The two last fields are optional. +Adding `PROXY` in either or both of the two last fields we can use Proxy Protocol decoding (listen) and/or encoding (proxy_pass) in a TCP service https://www.nginx.com/resources/admin-guide/proxy-protocol + +The next example shows how to expose the service `example-go` running in the namespace `default` in the port `8080` using the port `9000` + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: tcp-services + namespace: ingress-nginx +data: + 9000: "default/example-go:8080" +``` + +Since 1.9.13 NGINX provides [UDP Load Balancing](https://www.nginx.com/blog/announcing-udp-load-balancing/). +The next example shows how to expose the service `kube-dns` running in the namespace `kube-system` in the port `53` using the port `53` + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: udp-services + namespace: ingress-nginx +data: + 53: "kube-system/kube-dns:53" +``` + +If TCP/UDP proxy support is used, then those ports need to be exposed in the Service defined for the Ingress. + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: ingress-nginx + namespace: ingress-nginx + labels: + app.kubernetes.io/name: ingress-nginx + app.kubernetes.io/part-of: ingress-nginx +spec: + type: LoadBalancer + ports: + - name: http + port: 80 + targetPort: 80 + protocol: TCP + - name: https + port: 443 + targetPort: 443 + protocol: TCP + - name: proxied-tcp-9000 + port: 9000 + targetPort: 9000 + protocol: TCP + selector: + app.kubernetes.io/name: ingress-nginx + app.kubernetes.io/part-of: ingress-nginx +``` diff --git a/docs/user-guide/nginx-configuration/configmap.md b/docs/user-guide/nginx-configuration/configmap.md index f2d9b1ddf..0367d73d1 100644 --- a/docs/user-guide/nginx-configuration/configmap.md +++ b/docs/user-guide/nginx-configuration/configmap.md @@ -57,7 +57,7 @@ The following table shows a configuration option's name, type, and the default v |[keep-alive-requests](#keep-alive-requests)|int|100| |[large-client-header-buffers](#large-client-header-buffers)|string|"4 8k"| |[log-format-escape-json](#log-format-escape-json)|bool|"false"| -|[log-format-upstream](#log-format-upstream)|string|`%v - [$the_real_ip] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status`| +|[log-format-upstream](#log-format-upstream)|string|`%v - [$the_real_ip] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id`| |[log-format-stream](#log-format-stream)|string|`[$time_local] $protocol $status $bytes_sent $bytes_received $session_time`| |[enable-multi-accept](#enable-multi-accept)|bool|"true"| |[max-worker-connections](#max-worker-connections)|int|16384| diff --git a/docs/user-guide/nginx-configuration/log-format.md b/docs/user-guide/nginx-configuration/log-format.md index eeed2a0da..cdd68e597 100644 --- a/docs/user-guide/nginx-configuration/log-format.md +++ b/docs/user-guide/nginx-configuration/log-format.md @@ -8,7 +8,7 @@ log_format upstreaminfo '[$the_real_ip] - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" "$http_user_agent" ' '$request_length $request_time [$proxy_upstream_name] $upstream_addr ' - '$upstream_response_length $upstream_response_time $upstream_status'; + '$upstream_response_length $upstream_response_time $upstream_status $req_id'; ``` | Placeholder | Description | @@ -30,6 +30,7 @@ log_format upstreaminfo | `$upstream_response_length` | the length of the response obtained from the upstream server | | `$upstream_response_time` | time spent on receiving the response from the upstream server as seconds with millisecond resolution | | `$upstream_status` | status code of the response obtained from the upstream server | +| `$req_id` | the randomly generated ID of the request | Additional available variables: diff --git a/mkdocs.yml b/mkdocs.yml index 1a9398dc2..d7a2e80ad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,6 +50,7 @@ nav: - Command line arguments: "user-guide/cli-arguments.md" - Custom errors: "user-guide/custom-errors.md" - Default backend: "user-guide/default-backend.md" + - Exposing TCP and UDP services: "user-guide/exposing-tcp-udp-services.md" - Regular expressions in paths: user-guide/ingress-path-matching.md - External Articles: "user-guide/external-articles.md" - Miscellaneous: "user-guide/miscellaneous.md"