From 469797e2426f72cb503ec87aaa09589d4a0d2106 Mon Sep 17 00:00:00 2001 From: Manuel Alejandro de Brito Fontes Date: Thu, 11 Oct 2018 22:09:01 -0300 Subject: [PATCH] Fix documentation links [skip ci] (#3229) --- docs/examples/index.md | 1 - docs/user-guide/exposing-tcp-udp-services.md | 63 ----------- docs/user-guide/ingress-path-matching.md | 105 +++++++++---------- mkdocs.yml | 6 +- 4 files changed, 54 insertions(+), 121 deletions(-) delete mode 100644 docs/user-guide/exposing-tcp-udp-services.md diff --git a/docs/examples/index.md b/docs/examples/index.md index df1d01d5e..04f42ea60 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -15,7 +15,6 @@ Customization | [Custom configuration](customization/custom-configuration/README Customization | [Custom DH parameters for perfect forward secrecy](customization/ssl-dh-param/README.md) | TODO | TODO Customization | [Custom errors](customization/custom-errors/README.md) | serve custom error pages from the default backend | Intermediate Customization | [Custom headers](customization/custom-headers/README.md) | set custom headers before sending traffic to backends | Advanced -Customization | [Custom upstream check](customization/custom-upstream-check/README.md) | TODO | TODO Customization | [External authentication with response header propagation](customization/external-auth-headers/README.md) | TODO | TODO Customization | [Sysctl tuning](customization/sysctl/README.md) | TODO | TODO Features | [Rewrite](rewrite/README.md) | TODO | TODO diff --git a/docs/user-guide/exposing-tcp-udp-services.md b/docs/user-guide/exposing-tcp-udp-services.md deleted file mode 100644 index d7be2c081..000000000 --- a/docs/user-guide/exposing-tcp-udp-services.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/ingress-path-matching.md b/docs/user-guide/ingress-path-matching.md index c7c360562..281e76f66 100644 --- a/docs/user-guide/ingress-path-matching.md +++ b/docs/user-guide/ingress-path-matching.md @@ -4,10 +4,9 @@ The ingress controller supports **case insensitive** regular expressions in the `spec.rules.http.paths.path` field. +See the [description](./nginx-configuration/annotations.md#use-regex) of the `use-regex` annotation for more details. -See the [description](./nginx-configuration/annotations.md#use-regex) of the `use-regex` annotation for more details. - -``` +```yaml apiVersion: extensions/v1beta1 kind: Ingress metadata: @@ -17,17 +16,17 @@ metadata: spec: host: test.com rules: - - http: - paths: - - path: /foo/.* - backend: - serviceName: test - servicePort: 80 + - http: + paths: + - path: /foo/.* + backend: + serviceName: test + servicePort: 80 ``` The preceding ingress definition would translate to the following location block within the NGINX configuration for the `test.com` server: -``` +```txt location ~* ^/foo/.* { ... } @@ -35,15 +34,15 @@ location ~* ^/foo/.* { ## Path Priority -In NGINX, regular expressions follow a **first match** policy. In order to enable more acurate path matching, ingress-nginx first orders the paths by descending length before writing them to the NGINX template as location blocks. +In NGINX, regular expressions follow a **first match** policy. In order to enable more acurate path matching, ingress-nginx first orders the paths by descending length before writing them to the NGINX template as location blocks. -__Please read the [warning](#warning) before using regular expressions in your ingress definitions.__ +**Please read the [warning](#warning) before using regular expressions in your ingress definitions.** ### Example Let the following two ingress definitions be created: -``` +```yaml apiVersion: extensions/v1beta1 kind: Ingress metadata: @@ -51,19 +50,19 @@ metadata: spec: host: test.com rules: - - http: - paths: - - path: /foo/bar - backend: - serviceName: test - servicePort: 80 - - path: /foo/bar/ - backend: - serviceName: test - servicePort: 80 + - http: + paths: + - path: /foo/bar + backend: + serviceName: test + servicePort: 80 + - path: /foo/bar/ + backend: + serviceName: test + servicePort: 80 ``` -``` +```yaml apiVersion: extensions/v1beta1 kind: Ingress metadata: @@ -73,19 +72,17 @@ metadata: spec: host: test.com rules: - - http: - paths: - - path: /foo/bar/.+ - backend: - serviceName: test - servicePort: 80 + - http: + paths: + - path: /foo/bar/.+ + backend: + serviceName: test + servicePort: 80 ``` +The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the `test.com` server: - -The ingress controller would define the following location blocks, in order of descending length, within the NGINX template for the `test.com` server: - -``` +```txt location ~* ^/foo/bar/.+\/?(?.*) { ... } @@ -98,26 +95,29 @@ location ~* ^/foo/bar { ... } ``` + The following request URI's would match the corresponding location blocks: + - `test.com/foo/bar/1` matches `~* ^/foo/bar/.+\/?(?.*)` - `test.com/foo/bar/` matches `~* ^/foo/bar/` - `test.com/foo/bar` matches `~* ^/foo/bar` -__IMPORTANT NOTES__: -- paths created under the `rewrite-ingress` are sorted before `\/?(?.*)` is appended. For example if the path defined within `test-ingress-2` was `/foo/.+` then the location block for `^/foo/.+\/?(?.*)` would be the LAST block listed. -- If the `use-regex` OR `rewrite-target` annotation is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on. +**IMPORTANT NOTES**: +- paths created under the `rewrite-ingress` are sorted before `\/?(?.*)` is appended. For example if the path defined within `test-ingress-2` was `/foo/.+` then the location block for `^/foo/.+\/?(?.*)` would be the LAST block listed. +- If the `use-regex` OR `rewrite-target` annotation is used on any Ingress for a given host, then the case insensitive regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) will be enforced on ALL paths for a given host regardless of what Ingress they are defined on. ## Warning -The following example describes a case that may inflict unwanted path matching behaviour. -This case is expected and a result of NGINX's a first match policy for paths that use the regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location). For more information about how a path is chosen, please read the following article: ["Understanding Nginx Server and Location Block Selection Algorithms"](https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms). +The following example describes a case that may inflict unwanted path matching behaviour. + +This case is expected and a result of NGINX's a first match policy for paths that use the regular expression [location modifier](https://nginx.org/en/docs/http/ngx_http_core_module.html#location). For more information about how a path is chosen, please read the following article: ["Understanding Nginx Server and Location Block Selection Algorithms"](https://www.digitalocean.com/community/tutorials/understanding-nginx-server-and-location-block-selection-algorithms). ### Example Let the following ingress be defined: -``` +```yaml apiVersion: extensions/v1beta1 kind: Ingress metadata: @@ -127,21 +127,21 @@ metadata: spec: host: test.com rules: - - http: - paths: - - path: /foo/bar/bar - backend: - serviceName: test - servicePort: 80 - - path: /foo/bar/[A-Z0-9]{3} - backend: - serviceName: test - servicePort: 80 + - http: + paths: + - path: /foo/bar/bar + backend: + serviceName: test + servicePort: 80 + - path: /foo/bar/[A-Z0-9]{3} + backend: + serviceName: test + servicePort: 80 ``` -The ingress controller would define the following location blocks (in this order) within the NGINX template for the `test.com` server: +The ingress controller would define the following location blocks (in this order) within the NGINX template for the `test.com` server: -``` +```txt location ~* ^/foo/bar/[A-Z0-9]{3} { ... } @@ -152,4 +152,3 @@ location ~* ^/foo/bar/bar { ``` A request to `test.com/foo/bar/bar` would match the `^/foo/[A-Z0-9]{3}` location block instead of the longest EXACT matching path. - diff --git a/mkdocs.yml b/mkdocs.yml index 8b10fbd20..1a9398dc2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,8 +4,7 @@ repo_name: "kubernetes/ingress-nginx" repo_url: "https://github.com/kubernetes/ingress-nginx" markdown_extensions: - admonition - - codehilite: - linenums: true + - codehilite - pymdownx.inlinehilite - pymdownx.tasklist: custom_checkbox: true @@ -51,7 +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" - Prometheus and Grafana installation: "user-guide/monitoring.md" @@ -74,7 +73,6 @@ nav: - Custom Configuration: "examples/customization/custom-configuration/README.md" - Custom Errors: "examples/customization/custom-errors/README.md" - Custom Headers: "examples/customization/custom-headers/README.md" - - Custom Upstream server checks: "examples/customization/custom-upstream-check/README.md" - External authentication: "examples/customization/external-auth-headers/README.md" - Custom DH parameters for perfect forward secrecy: "examples/customization/ssl-dh-param/README.md" - Sysctl tuning: "examples/customization/sysctl/README.md"