From efec983ed48a77dd957ab9c3749a0889e25bdf9f Mon Sep 17 00:00:00 2001 From: Manuel Alejandro de Brito Fontes Date: Fri, 26 Jan 2018 16:36:12 -0300 Subject: [PATCH] Add comment about bolean and number values (#1991) --- docs/annotations.md | 93 ---------------------------------- docs/user-guide/annotations.md | 26 ++++++---- docs/user-guide/configmap.md | 58 +++++++++++---------- 3 files changed, 48 insertions(+), 129 deletions(-) delete mode 100644 docs/annotations.md diff --git a/docs/annotations.md b/docs/annotations.md deleted file mode 100644 index 562fae40e5..0000000000 --- a/docs/annotations.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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. - -All annotations are assumed to be prefixed with `nginx.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 -* `voyager`: [Voyager by AppsCode](https://github.com/appscode/voyager) - Secure HAProxy based Ingress Controller for Kubernetes -* `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) - -## TLS-related - -| Name | Meaning | Default | Controller -| --- | --- | --- | --- | -| `ssl-passthrough` | Pass TLS connections directly to backend; do not offload. | `false` | nginx, voyager, haproxy -| `ssl-redirect` | Redirect non-TLS requests to TLS when TLS is enabled. | `true` | nginx, voyager, haproxy, trafficserver -| `force-ssl-redirect` | Redirect non-TLS requests to TLS even when TLS is not configured. | `false` | nginx, voyager, trafficserver -| `secure-backends` | Use TLS to communicate with origin (pods). | `false` | nginx, voyager, haproxy, trafficserver -| `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. | | voyager, trafficserver -| `hsts-include-subdomains` | Add includeSubdomains to the HSTS header. | | voyager, trafficserver - -## Authentication related - -| Name | Meaning | Default | Controller -| --- | --- | --- | --- | -| `auth-type` | Authentication type: `basic`, `digest`, ... | | nginx, voyager, haproxy, trafficserver -| `auth-secret` | Secret name for authentication. | | nginx, voyager, haproxy, trafficserver -| `auth-realm` | Authentication realm. | | nginx, voyager, haproxy, trafficserver -| `auth-tls-secret` | Name of secret for TLS client certification validation. | | nginx, voyager, haproxy -| `auth-tls-verify-depth` | Maximum chain length of TLS client certificate. | | nginx -| `auth-tls-error-page` | The page that user should be redirected in case of Auth error | | nginx, voyager -| `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, voyager, haproxy, trafficserver - -## URL related - -| 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 -| `base-url-scheme` | Specify the scheme of the `` tags. | | nginx -| `preserve-host` | Whether to pass the client request host (`true`) or the origin hostname (`false`) in the HTTP Host field. | | trafficserver -| `x-forwarded-prefix` | Add the non-standard `X-Forwarded-Prefix` header to the request with the value of the matched location. | | nginx - -## CORS Related -| Name | Meaning | Default | Controller -| --- | --- | --- | --- | -| `enable-cors` | Enable CORS headers in response. | false | nginx, voyager -| `cors-allow-origin` | Specifies the Origin allowed in CORS (Access-Control-Allow-Origin) | * | nginx -| `cors-allow-headers` | Specifies the Headers allowed in CORS (Access-Control-Allow-Headers) | DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization | nginx -| `cors-allow-methods` | Specifies the Methods allowed in CORS (Access-Control-Allow-Methods) | GET, PUT, POST, DELETE, PATCH, OPTIONS | nginx -| `cors-allow-credentials` | Specifies the Access-Control-Allow-Credentials | true | nginx -| `cors-max-age` | Specifies the Access-Control-Max-Age | 1728000 | nginx - -## Miscellaneous - -| Name | Meaning | Default | Controller -| --- | --- | --- | --- | -| `configuration-snippet` | Arbitrary text to put in the generated configuration file. | | nginx -| `limit-connections` | Limit concurrent connections per IP address[1]. | | nginx, voyager -| `limit-rps` | Limit requests per second per IP address[1]. | | nginx, voyager -| `limit-rpm` | Limit requests per minute per IP address. | | nginx, voyager -| `affinity` | Specify a method to stick clients to origins across requests. Found in `nginx`, where the only supported value is `cookie`. | | nginx, voyager -| `session-cookie-name` | When `affinity` is set to `cookie`, the name of the cookie to use. | | nginx, voyager -| `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, voyager, haproxy -| `proxy-pass-params` | Parameters for proxy-pass directives. | | -| `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. - -## Caching - -| 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 diff --git a/docs/user-guide/annotations.md b/docs/user-guide/annotations.md index 928f219c98..a6a45509de 100644 --- a/docs/user-guide/annotations.md +++ b/docs/user-guide/annotations.md @@ -1,10 +1,16 @@ +**IMPORTANT:** + +The key and values in annotations can only be strings. +This means that we want a value with boolean values we need to quote the values, like "true" or "false". +Same for numbers, like "100". + # Annotations The following annotations are supported: |Name | type | |---------------------------|------| -|[nginx.ingress.kubernetes.io/add-base-url](#rewrite)|true or false| +|[nginx.ingress.kubernetes.io/add-base-url](#rewrite)|"true" or "false"| |[nginx.ingress.kubernetes.io/app-root](#rewrite)|string| |[nginx.ingress.kubernetes.io/affinity](#session-affinity)|cookie| |[nginx.ingress.kubernetes.io/auth-realm](#authentication)|string| @@ -14,20 +20,20 @@ The following annotations are supported: |[nginx.ingress.kubernetes.io/auth-tls-verify-depth](#certificate-authentication)|number| |[nginx.ingress.kubernetes.io/auth-tls-verify-client](#certificate-authentication)|string| |[nginx.ingress.kubernetes.io/auth-tls-error-page](#certificate-authentication)|string| -|[nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream](#certificate-authentication)|true or false| +|[nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream](#certificate-authentication)|"true" or "false"| |[nginx.ingress.kubernetes.io/auth-url](#external-authentication)|string| |[nginx.ingress.kubernetes.io/base-url-scheme](#rewrite)|string| |[nginx.ingress.kubernetes.io/client-body-buffer-size](#client-body-buffer-size)|string| |[nginx.ingress.kubernetes.io/configuration-snippet](#configuration-snippet)|string| |[nginx.ingress.kubernetes.io/default-backend](#default-backend)|string| -|[nginx.ingress.kubernetes.io/enable-cors](#enable-cors)|true or false| +|[nginx.ingress.kubernetes.io/enable-cors](#enable-cors)|"true" or "false"| |[nginx.ingress.kubernetes.io/cors-allow-origin](#enable-cors)|string| |[nginx.ingress.kubernetes.io/cors-allow-methods](#enable-cors)|string| |[nginx.ingress.kubernetes.io/cors-allow-headers](#enable-cors)|string| -|[nginx.ingress.kubernetes.io/cors-allow-credentials](#enable-cors)|true or false| +|[nginx.ingress.kubernetes.io/cors-allow-credentials](#enable-cors)|"true" or "false"| |[nginx.ingress.kubernetes.io/cors-max-age](#enable-cors)|number| -|[nginx.ingress.kubernetes.io/force-ssl-redirect](#server-side-https-enforcement-through-redirect)|true or false| -|[nginx.ingress.kubernetes.io/from-to-www-redirect](#redirect-from-to-www)|true or false| +|[nginx.ingress.kubernetes.io/force-ssl-redirect](#server-side-https-enforcement-through-redirect)|"true" or "false"| +|[nginx.ingress.kubernetes.io/from-to-www-redirect](#redirect-from-to-www)|"true" or "false"| |[nginx.ingress.kubernetes.io/limit-connections](#rate-limiting)|number| |[nginx.ingress.kubernetes.io/limit-rps](#rate-limiting)|number| |[nginx.ingress.kubernetes.io/proxy-body-size](#custom-max-body-size)|string| @@ -39,14 +45,14 @@ The following annotations are supported: |[nginx.ingress.kubernetes.io/proxy-redirect-from](#proxy-redirect)|string| |[nginx.ingress.kubernetes.io/proxy-redirect-to](#proxy-redirect)|string| |[nginx.ingress.kubernetes.io/rewrite-target](#rewrite)|URI| -|[nginx.ingress.kubernetes.io/secure-backends](#secure-backends)|true or false| +|[nginx.ingress.kubernetes.io/secure-backends](#secure-backends)|"true" or "false"| |[nginx.ingress.kubernetes.io/server-alias](#server-alias)|string| |[nginx.ingress.kubernetes.io/server-snippet](#server-snippet)|string| -|[nginx.ingress.kubernetes.io/service-upstream](#service-upstream)|true or false| +|[nginx.ingress.kubernetes.io/service-upstream](#service-upstream)|"true" or "false"| |[nginx.ingress.kubernetes.io/session-cookie-name](#cookie-affinity)|string| |[nginx.ingress.kubernetes.io/session-cookie-hash](#cookie-affinity)|string| -|[nginx.ingress.kubernetes.io/ssl-redirect](#server-side-https-enforcement-through-redirect)|true or false| -|[nginx.ingress.kubernetes.io/ssl-passthrough](#ssl-passthrough)|true or false| +|[nginx.ingress.kubernetes.io/ssl-redirect](#server-side-https-enforcement-through-redirect)|"true" or "false"| +|[nginx.ingress.kubernetes.io/ssl-passthrough](#ssl-passthrough)|"true" or "false"| |[nginx.ingress.kubernetes.io/upstream-max-fails](#custom-nginx-upstream-checks)|number| |[nginx.ingress.kubernetes.io/upstream-fail-timeout](#custom-nginx-upstream-checks)|number| |[nginx.ingress.kubernetes.io/upstream-hash-by](#custom-nginx-upstream-hashing)|string| diff --git a/docs/user-guide/configmap.md b/docs/user-guide/configmap.md index 4695be7cf0..a12edbe187 100644 --- a/docs/user-guide/configmap.md +++ b/docs/user-guide/configmap.md @@ -13,6 +13,12 @@ data: ssl-protocols: SSLv2 ``` +**IMPORTANT:** + +The key and values in a ConfigMap can only be strings. +This means that we want a value with boolean values we need to quote the values, like "true" or "false". +Same for numbers, like "100". + ## Configuration options The following table shows a configuration option's name, type, and the default value: @@ -20,36 +26,36 @@ The following table shows a configuration option's name, type, and the default v |name|type|default| |:---|:---|:------| |[add‑headers](#add-headers)|string|""| -|[allow‑backend‑server‑header](#allow-backend-server-header)|bool|false| +|[allow‑backend‑server‑header](#allow-backend-server-header)|bool|"false"| |[hide‑headers](#hide-headers)|string array|empty| |[access‑log‑path](#access-log-path)|string|"/var/log/nginx/access.log"| |[error‑log‑path](#error-log-path)|string|"/var/log/nginx/error.log"| -|[enable‑dynamic‑tls‑records](#enable-dynamic-tls-records)|bool|true| -|[enable‑modsecurity](#enable-modsecurity)|bool|false| -|[enable‑owasp‑modsecurity‑crs](#enable-owasp-modsecurity-crs)|bool|false| +|[enable‑dynamic‑tls‑records](#enable-dynamic-tls-records)|bool|"true"| +|[enable‑modsecurity](#enable-modsecurity)|bool|"false"| +|[enable‑owasp‑modsecurity‑crs](#enable-owasp-modsecurity-crs)|bool|"false"| |[client‑header‑buffer‑size](#client-header-buffer-size)|string|"1k"| |[client‑header‑timeout](#client-header-timeout)|int|60| |[client‑body‑buffer‑size](#client-body-buffer-size)|string|"8k"| |[client‑body‑timeout](#client-body-timeout)|int|60| -|[disable‑access‑log](#disable-access-log)|bool|false| -|[disable‑ipv6](#disable-ipv6)|bool|false| -|[enable‑underscores‑in‑headers](#enable-underscores-in-headers)|bool|false| -|[ignore‑invalid‑headers](#ignore-invalid-headers)|bool|true| -|[enable‑vts‑status](#enable-vts-status)|bool|false| +|[disable‑access‑log](#disable-access-log)|bool|"false"| +|[disable‑ipv6](#disable-ipv6)|bool|"false"| +|[enable‑underscores‑in‑headers](#enable-underscores-in-headers)|bool|"false"| +|[ignore‑invalid‑headers](#ignore-invalid-headers)|bool|"true"| +|[enable‑vts‑status](#enable-vts-status)|bool|"false"| |[vts‑status‑zone‑size](#vts-status-zone-size)|string|"10m"| |[vts‑default‑filter‑key](#vts-default-filter-key)|string|"$geoip_country_code country::*"| -|[retry‑non‑idempotent](#retry-non-idempotent)|bool|false| +|[retry‑non‑idempotent](#retry-non-idempotent)|bool|"false"| |[error‑log‑level](#error-log-level)|string|"notice"| |[http2‑max‑field‑size](#http2-max-field-size)|string|"4k"| |[http2‑max‑header‑size](#http2-max-header-size)|string|"16k"| -|[hsts](#hsts)|bool|true| -|[hsts‑include‑subdomains](#hsts-include-subdomains)|bool|true| +|[hsts](#hsts)|bool|"true"| +|[hsts‑include‑subdomains](#hsts-include-subdomains)|bool|"true"| |[hsts‑max‑age](#hsts-max-age)|string|"15724800"| -|[hsts‑preload](#hsts-preload)|bool|false| +|[hsts‑preload](#hsts-preload)|bool|"false"| |[keep‑alive](#keep-alive)|int|75| |[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‑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‑stream](#log-format-stream)|string|`[$time_local] $protocol $status $bytes_sent $bytes_received $session_time`| |[max‑worker‑connections](#max-worker-connections)|int|16384| @@ -60,23 +66,23 @@ The following table shows a configuration option's name, type, and the default v |[server‑name‑hash‑bucket‑size](#server-name-hash-bucket-size)|int|`` |[proxy‑headers‑hash‑max‑size](#proxy-headers-hash-max-size)|int|512| |[proxy‑headers‑hash‑bucket‑size](#proxy-headers-hash-bucket-size)|int|64| -|[server‑tokens](#server-tokens)|bool|true| +|[server‑tokens](#server-tokens)|bool|"true"| |[ssl‑ciphers](#ssl-ciphers)|string|"ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"| |[ssl‑ecdh‑curve](#ssl-ecdh-curve)|string|"auto"| |[ssl‑dh‑param](#ssl-dh-param)|string|""| |[ssl‑protocols](#ssl-protocols)|string|"TLSv1.2"| -|[ssl‑session‑cache](#ssl-session-cache)|bool|true| +|[ssl‑session‑cache](#ssl-session-cache)|bool|"true"| |[ssl‑session‑cache‑size](#ssl-session-cache-size)|string|"10m"| -|[ssl‑session‑tickets](#ssl-session-tickets)|bool|true| +|[ssl‑session‑tickets](#ssl-session-tickets)|bool|"true"| |[ssl‑session‑ticket‑key](#ssl-session-ticket-key)|string|`` |[ssl‑session‑timeout](#ssl-session-timeout)|string|"10m"| |[ssl‑buffer‑size](#ssl-buffer-size)|string|"4k"| -|[use‑proxy‑protocol](#use-proxy-protocol)|bool|false| -|[use‑gzip](#use-gzip)|bool|true| -|[enable‑brotli](#enable-brotli)|bool|true| +|[use‑proxy‑protocol](#use-proxy-protocol)|bool|"false"| +|[use‑gzip](#use-gzip)|bool|"true"| +|[enable‑brotli](#enable-brotli)|bool|"true"| |[brotli‑level](#brotli-level)|int|4| |[brotli‑types](#brotli-types)|string|"application/xml+rss application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"| -|[use‑http2](#use-http2)|bool|true| +|[use‑http2](#use-http2)|bool|"true"| |[gzip‑types](#gzip-types)|string|"application/atom+xml application/javascript application/x-javascript application/json application/rss+xml application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/svg+xml image/x-icon text/css text/plain text/x-component"| |[worker‑processes](#worker-processes)|string|``| |[worker‑shutdown‑timeout](#worker-shutdown-timeout)|string|"10s"| @@ -90,8 +96,8 @@ The following table shows a configuration option's name, type, and the default v |[bind‑address‑ipv4](#bind-address-ipv4)|[]string|""| |[bind‑address‑ipv6](#bind-address-ipv6)|[]string|""| |[forwarded‑for‑header](#forwarded-for-header)|string|"X-Forwarded-For"| -|[compute‑full‑forwarded‑for](#compute-full-forwarded-for)|bool|false| -|[enable‑opentracing](#enable-opentracing)|bool|false| +|[compute‑full‑forwarded‑for](#compute-full-forwarded-for)|bool|"false"| +|[enable‑opentracing](#enable-opentracing)|bool|"false"| |[zipkin‑collector‑host](#zipkin-collector-host)|string|""| |[zipkin‑collector‑port](#zipkin-collector-port)|int|9411| |[zipkin‑service‑name](#zipkin-service-name)|string|"nginx"| @@ -114,7 +120,7 @@ The following table shows a configuration option's name, type, and the default v |[proxy‑next‑upstream](#proxy-next-upstream)|string|"error timeout invalid_header http_502 http_503 http_504"| |[proxy‑redirect‑from](#proxy-redirect-from)|string|"off"| |[proxy‑request‑buffering](#proxy-request-buffering)|string|"on"| -|[ssl‑redirect](#ssl-redirect)|bool|true| +|[ssl‑redirect](#ssl-redirect)|bool|"true"| |[whitelist‑source‑range](#whitelist-source-range)|[]string|[]string{}| |[skip‑access‑log‑urls](#skip-access-log-urls)|[]string|[]string{}| |[limit‑rate](#limit-rate)|int|0| @@ -194,7 +200,7 @@ _References:_ ## disable-access-log -Disables the Access Log from the entire Ingress Controller. This is 'false' by default. +Disables the Access Log from the entire Ingress Controller. This is '"false"' by default. _References:_ - http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log @@ -300,7 +306,7 @@ _References:_ ## log-format-escape-json -Sets if the escape parameter allows JSON (true) or default characters escaping in variables (false) Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format). +Sets if the escape parameter allows JSON ("true") or default characters escaping in variables ("false") Sets the nginx [log format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format). ## log-format-upstream