From 60e48a55d3aeeaf6971f2b123bac98f2b469f2f7 Mon Sep 17 00:00:00 2001 From: Tony Li Date: Fri, 11 Aug 2017 21:35:52 -0400 Subject: [PATCH 1/9] Add gce annotations Related to creating HTTPS load balancers. --- docs/annotations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/annotations.md b/docs/annotations.md index 54bbdfa1a..6a6be9312 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -21,6 +21,7 @@ Key: | `force-ssl-redirect` | Redirect non-TLS requests to TLS even when TLS is not configured. Default `false`. (nginx, trafficserver). | `secure-backends` | Use TLS to communicate with origin (pods). Default `false`. (nginx, haproxy, trafficserver) | `kubernetes.io/ingress.allow-http` | Whether to accept non-TLS HTTP connections. (gce) +| `pre-shared-cert` | Name of the TLS certificate in GCP to use when provisioning the HTTPS load balancer. (gce) | `hsts-max-age` | Set an HSTS header with this lifetime. (trafficserver) | `hsts-include-subdomains` | Add includeSubdomains to the HSTS header. (trafficserver) @@ -58,7 +59,8 @@ Key: | `session-cookie-name` | When `affinity` is set to `cookie`, the name of the cookie to use. (nginx) | `session-cookie-hash` | When `affinity` is set to `cookie`, the hash algorithm used: `md5`, `sha`, `index`. (nginx) | `proxy-body-size` | Maximum request body size. (nginx, haproxy) -| `follow-redirects` | Follow HTTP redirects in the response and deliver the redirect target to the client. (trafficserver) +| `follow-redirects` | Follow HTTP redirects in the response and deliver the redirect target to the client. (trafficserver) +| `kubernetes.io/ingress.global-static-ip-name` | Name of the static global IP address in GCP to use when provisioning the HTTPS load balanver. (gce) [1] The documentation for the `nginx` controller says that only one of `limit-connections` or `limit-rps` may be specified; it's not clear why this is. From e8f045754e32c20c7509a9be8ee7f7b896af58ac Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 02:52:20 -0400 Subject: [PATCH 2/9] make easier to read --- docs/annotations.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 6a6be9312..662980fcb 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -1,14 +1,17 @@ # Ingress Annotations -This file defines a list of annotations which are supported by various Ingress controllers (both those based on the common ingress code, and alternative implementations). The intention is to ensure the maximum amount of compatibility between different implementations. +This file defines a list of annotations which are supported by various Ingress controllers (both those based on the common ingress code, and alternative implementations). +The intention is to ensure the maximum amount of compatibility between different implementations. -All annotations are assumed to be prefixed with `ingress.kubernetes.io/` except where otherwise specified. There is no attempt to record implementation-specific annotations using other prefixes. (Traefik in particular defines several of its own annotations which are not described here, and does not seem to support any of the standard annotations.) +All annotations are assumed to be prefixed with `ingress.kubernetes.io/` except where otherwise specified. +There is no attempt to record implementation-specific annotations using other prefixes. +(Traefik in particular defines several of its own annotations which are not described here, and does not seem to support any of the standard annotations.) Key: * `nginx`: the `kubernetes/ingress` nginx controller * `gce`: the `kubernetes/ingress` GCE controller -* `traefik`: Traefik's built-in Ingress controller +* `traefik`: Traefik's built-in Ingress controller * `haproxy`: Joao Morais' [HAProxy Ingress controller](https://github.com/jcmoraisjr/haproxy-ingress) * `trafficserver`: Torchbox's [Apache Traffic Server controller plugin](https://github.com/torchbox/k8s-ts-ingress) From 49108c9a07300cc852c9d2ae0f30fdfc168f60a3 Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 03:14:08 -0400 Subject: [PATCH 3/9] fix typo --- docs/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/annotations.md b/docs/annotations.md index 662980fcb..523154b2f 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -63,7 +63,7 @@ Key: | `session-cookie-hash` | When `affinity` is set to `cookie`, the hash algorithm used: `md5`, `sha`, `index`. (nginx) | `proxy-body-size` | Maximum request body size. (nginx, haproxy) | `follow-redirects` | Follow HTTP redirects in the response and deliver the redirect target to the client. (trafficserver) -| `kubernetes.io/ingress.global-static-ip-name` | Name of the static global IP address in GCP to use when provisioning the HTTPS load balanver. (gce) +| `kubernetes.io/ingress.global-static-ip-name` | Name of the static global IP address in GCP to use when provisioning the HTTPS load balancer. (gce) [1] The documentation for the `nginx` controller says that only one of `limit-connections` or `limit-rps` may be specified; it's not clear why this is. From 3f5cfb51f0b728dfcb7a754e61513d99cb62f1e6 Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 02:58:08 -0400 Subject: [PATCH 4/9] leverage table --- docs/annotations.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 523154b2f..9a2634039 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -17,16 +17,16 @@ Key: ## TLS-related -| Name | Meaning -| --- | --- -| `ssl-passthrough` | Pass TLS connections directly to backend; do not offload. Default `false`. (nginx, haproxy) -| `ssl-redirect` | Redirect non-TLS requests to TLS when TLS is enabled. Default `true`. (nginx, haproxy, trafficserver) -| `force-ssl-redirect` | Redirect non-TLS requests to TLS even when TLS is not configured. Default `false`. (nginx, trafficserver). -| `secure-backends` | Use TLS to communicate with origin (pods). Default `false`. (nginx, haproxy, trafficserver) -| `kubernetes.io/ingress.allow-http` | Whether to accept non-TLS HTTP connections. (gce) -| `pre-shared-cert` | Name of the TLS certificate in GCP to use when provisioning the HTTPS load balancer. (gce) -| `hsts-max-age` | Set an HSTS header with this lifetime. (trafficserver) -| `hsts-include-subdomains` | Add includeSubdomains to the HSTS header. (trafficserver) +| Name | Meaning | Default | Controller +| --- | --- | --- | --- | +| `ssl-passthrough` | Pass TLS connections directly to backend; do not offload. | `false` | nginx, haproxy +| `ssl-redirect` | Redirect non-TLS requests to TLS when TLS is enabled. | `true` | nginx, haproxy, trafficserver +| `force-ssl-redirect` | Redirect non-TLS requests to TLS even when TLS is not configured. | `false` | nginx, trafficserver +| `secure-backends` | Use TLS to communicate with origin (pods). | `false` | nginx, haproxy, trafficserver +| `kubernetes.io/ingress.allow-http` | Whether to accept non-TLS HTTP connections. | | gce +| `pre-shared-cert` | Name of the TLS certificate in GCP to use when provisioning the HTTPS load balancer. | | gce +| `hsts-max-age` | Set an HSTS header with this lifetime. | | trafficserver +| `hsts-include-subdomains` | Add includeSubdomains to the HSTS header. | | trafficserver ## Authentication related From 00550f6d01aaa51330a10d35359894b925e1b978 Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 02:58:52 -0400 Subject: [PATCH 5/9] add defaults --- docs/annotations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 9a2634039..86d1e3e11 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -23,8 +23,8 @@ Key: | `ssl-redirect` | Redirect non-TLS requests to TLS when TLS is enabled. | `true` | nginx, haproxy, trafficserver | `force-ssl-redirect` | Redirect non-TLS requests to TLS even when TLS is not configured. | `false` | nginx, trafficserver | `secure-backends` | Use TLS to communicate with origin (pods). | `false` | nginx, haproxy, trafficserver -| `kubernetes.io/ingress.allow-http` | Whether to accept non-TLS HTTP connections. | | gce -| `pre-shared-cert` | Name of the TLS certificate in GCP to use when provisioning the HTTPS load balancer. | | gce +| `kubernetes.io/ingress.allow-http` | Whether to accept non-TLS HTTP connections. | `true` | gce +| `pre-shared-cert` | Name of the TLS certificate in GCP to use when provisioning the HTTPS load balancer. | empty string | gce | `hsts-max-age` | Set an HSTS header with this lifetime. | | trafficserver | `hsts-include-subdomains` | Add includeSubdomains to the HSTS header. | | trafficserver From 00ea9428fb9983fcf80c04d7c16a1e671bbe619f Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 03:04:39 -0400 Subject: [PATCH 6/9] update auth table --- docs/annotations.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 86d1e3e11..1939cc95e 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -30,15 +30,15 @@ Key: ## Authentication related -| Name | Meaning -| --- | --- -| `auth-type` | Authentication type: `basic`, `digest`, ... (nginx, haproxy, trafficserver) -| `auth-secret` | Secret name for authentication. (nginx, haproxy, trafficserver) -| `auth-realm` | Authentication realm. (nginx, haproxy, trafficserver) -| `auth-tls-secret` | Name of secret for TLS client certification validation. (nginx, haproxy) -| `auth-tls-verify-depth` | Maximum chain length of TLS client certificate. (nginx) -| `auth-satisfy` | Behaviour when more than one of `auth-type`, `auth-tls-secret` or `whitelist-source-range` are configured: `all` (default) or `any`. (trafficserver) | `trafficserver` -| `whitelist-source-range` | Comma-separate list of IP addresses to enable access to. (nginx, haproxy, trafficserver) +| Name | Meaning | Default | Controller +| --- | --- | --- | --- | +| `auth-type` | Authentication type: `basic`, `digest`, ... | | nginx, haproxy, trafficserver +| `auth-secret` | Secret name for authentication. | | nginx, haproxy, trafficserver +| `auth-realm` | Authentication realm. | | nginx, haproxy, trafficserver +| `auth-tls-secret` | Name of secret for TLS client certification validation. | | nginx, haproxy +| `auth-tls-verify-depth` | Maximum chain length of TLS client certificate. | | nginx +| `auth-satisfy` | Behaviour when more than one of `auth-type`, `auth-tls-secret` or `whitelist-source-range` are configured: `all` or `any`. | `all` | trafficserver | `trafficserver` +| `whitelist-source-range` | Comma-separate list of IP addresses to enable access to. | | nginx, haproxy, trafficserver ## URL related From 10ff0d129dfcc4023ff95cdf4cf866d047a36c1b Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 03:07:41 -0400 Subject: [PATCH 7/9] update url table --- docs/annotations.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 1939cc95e..22aa5f2f6 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -42,12 +42,12 @@ Key: ## URL related -| Name | Meaning -| --- | --- -| `app-root` | Redirect requests without a path (i.e., for `/`) to this location. (nginx, haproxy, trafficserver) -| `rewrite-target` | Replace matched Ingress `path` with this value. (nginx, trafficserver) -| `add-base-url` | Add `` tag to HTML. (nginx) -| `preserve-host` | Whether to pass the client request host (`true`) or the origin hostname (`false`) in the HTTP Host field. (trafficserver) +| Name | Meaning | Default | Controller +| --- | --- | --- | --- | +| `app-root` | Redirect requests without a path (i.e., for `/`) to this location. | | nginx, haproxy, trafficserver +| `rewrite-target` | Replace matched Ingress `path` with this value. | | nginx, trafficserver +| `add-base-url` | Add `` tag to HTML. | | nginx +| `preserve-host` | Whether to pass the client request host (`true`) or the origin hostname (`false`) in the HTTP Host field. | | trafficserver ## Miscellaneous From 15ab17994f577964233b2dfb58133ab3dd75eff3 Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 03:09:42 -0400 Subject: [PATCH 8/9] update misc table --- docs/annotations.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 22aa5f2f6..24651437f 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -51,19 +51,19 @@ Key: ## Miscellaneous -| Name | Meaning -| --- | --- -| `configuration-snippet` | Arbitrary text to put in the generated configuration file. (nginx) -| `enable-cors` | Enable CORS headers in response. (nginx) -| `limit-connections` | Limit concurrent connections per IP address[1]. (nginx) -| `limit-rps` | Limit requests per second per IP address[1]. (nginx) -| `limit-rpm` | Limit requests per minute per IP address. (nginx) -| `affinity` | Specify a method to stick clients to origins across requests. Found in `nginx`, where the only supported value is `cookie`. (nginx) -| `session-cookie-name` | When `affinity` is set to `cookie`, the name of the cookie to use. (nginx) -| `session-cookie-hash` | When `affinity` is set to `cookie`, the hash algorithm used: `md5`, `sha`, `index`. (nginx) -| `proxy-body-size` | Maximum request body size. (nginx, haproxy) -| `follow-redirects` | Follow HTTP redirects in the response and deliver the redirect target to the client. (trafficserver) -| `kubernetes.io/ingress.global-static-ip-name` | Name of the static global IP address in GCP to use when provisioning the HTTPS load balancer. (gce) +| Name | Meaning | Default | Controller +| --- | --- | --- | --- | +| `configuration-snippet` | Arbitrary text to put in the generated configuration file. | | nginx +| `enable-cors` | Enable CORS headers in response. | | nginx +| `limit-connections` | Limit concurrent connections per IP address[1]. | | nginx +| `limit-rps` | Limit requests per second per IP address[1]. | | nginx +| `limit-rpm` | Limit requests per minute per IP address. | | nginx +| `affinity` | Specify a method to stick clients to origins across requests. Found in `nginx`, where the only supported value is `cookie`. | | nginx +| `session-cookie-name` | When `affinity` is set to `cookie`, the name of the cookie to use. | | nginx +| `session-cookie-hash` | When `affinity` is set to `cookie`, the hash algorithm used: `md5`, `sha`, `index`. | | nginx +| `proxy-body-size` | Maximum request body size. | | nginx, haproxy +| `follow-redirects` | Follow HTTP redirects in the response and deliver the redirect target to the client. | | trafficserver +| `kubernetes.io/ingress.global-static-ip-name` | Name of the static global IP address in GCP to use when provisioning the HTTPS load balancer. | empty string | gce [1] The documentation for the `nginx` controller says that only one of `limit-connections` or `limit-rps` may be specified; it's not clear why this is. From 1fde6e4100598d964f772cc6a9207a5a3eb99f1b Mon Sep 17 00:00:00 2001 From: Tony Li Date: Sat, 12 Aug 2017 03:12:02 -0400 Subject: [PATCH 9/9] update cache table --- docs/annotations.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/annotations.md b/docs/annotations.md index 24651437f..2cc42af9b 100644 --- a/docs/annotations.md +++ b/docs/annotations.md @@ -69,11 +69,11 @@ Key: ## Caching -| Name | Meaning -| --- | --- -| `cache-enable` | Cache responses according to Expires or Cache-Control headers (trafficserver) -| `cache-generation` | An arbitrary numeric value included in the cache key; changing this effectively clears the cache for this ingress. (trafficserver) -| `cache-ignore-query-params` | Space-separate list of globs matching URL parameters to ignore when doing cache lookups. (trafficserver) -| `cache-whitelist-query-params` | Ignore any URL parameters not in this whitespace-separate list of globs. (trafficserver) -| `cache-sort-query-params` | Lexically sort the query parameters by name before cache lookup. (trafficserver) -| `cache-ignore-cookies` | Requests containing a `Cookie:` header will not use the cache unless all the cookie names match this whitespace-separate list of globs. (trafficserver) +| Name | Meaning | Default | Controller +| --- | --- | --- | --- | +| `cache-enable` | Cache responses according to Expires or Cache-Control headers. | | trafficserver +| `cache-generation` | An arbitrary numeric value included in the cache key; changing this effectively clears the cache for this ingress. | | trafficserver +| `cache-ignore-query-params` | Space-separate list of globs matching URL parameters to ignore when doing cache lookups. | | trafficserver +| `cache-whitelist-query-params` | Ignore any URL parameters not in this whitespace-separate list of globs. | | trafficserver +| `cache-sort-query-params` | Lexically sort the query parameters by name before cache lookup. | | trafficserver +| `cache-ignore-cookies` | Requests containing a `Cookie:` header will not use the cache unless all the cookie names match this whitespace-separate list of globs. | | trafficserver