Merge pull request #98192 from jmanthei/OSDOCS-12909

OSDOCS-12909 Route-specific-annotation updates

Author: dfitzmau

modules/nw-route-specific-annotations.adoc

@@ -17,35 +17,31 @@ To create an allow list with multiple source IPs or subnets, use a space-delimit
 //*route definition* for the route to alter its configuration.
 
 .Route annotations
-[cols="3*", options="header"]
+[cols="2*", options="header"]
 |===
-|Variable | Description | Environment variable used as default
-|`haproxy.router.openshift.io/balance`| Sets the load-balancing algorithm. Available options are `random`, `source`, `roundrobin`[^1^], and `leastconn`.  The default value is `source` for TLS passthrough routes. For all other routes, the default is `random`. |`ROUTER_TCP_BALANCE_SCHEME` for passthrough routes. Otherwise, use `ROUTER_LOAD_BALANCE_ALGORITHM`.
-|`haproxy.router.openshift.io/disable_cookies`| Disables the use of cookies to track related connections. If set to `'true'` or `'TRUE'`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request. |
+|Variable | Description 
+|`haproxy.router.openshift.io/balance`| Sets the load-balancing algorithm. Available options are `random`, `source`, `roundrobin`[^1^], and `leastconn`.  The default value is `source` for TLS passthrough routes. For all other routes, the default is `random`.
+|`haproxy.router.openshift.io/disable_cookies`| Disables the use of cookies to track related connections. If set to `'true'` or `'TRUE'`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request.
 |`router.openshift.io/cookie_name`| Specifies an optional cookie to use for
 this route. The name must consist of any combination of upper and lower case letters, digits, "_",
-and "-". The default is the hashed internal key name for the route. |
+and "-". The default is the hashed internal key name for the route.
 |`haproxy.router.openshift.io/pod-concurrent-connections`| Sets the maximum number of connections that are allowed to a backing pod from a router. +
-Note: If there are multiple pods, each can have this many connections.  If you have multiple routers, there is no coordination among them, each may connect this many times. If not set, or set to 0, there is no limit. |
+Note: If there are multiple pods, each can have this many connections.  If you have multiple routers, there is no coordination among them, each may connect this many times. If not set, or set to 0, there is no limit.
 |`haproxy.router.openshift.io/rate-limit-connections`| Setting `'true'` or `'TRUE'` enables rate limiting functionality which is implemented through stick-tables on the specific backend per route. +
-Note: Using this annotation provides basic protection against denial-of-service attacks. |
+Note: Using this annotation provides basic protection against denial-of-service attacks.
 |`haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp`| Limits the number of concurrent TCP connections made through the same source IP address. It accepts a numeric value. +
-Note: Using this annotation provides basic protection against denial-of-service attacks. |
+Note: Using this annotation provides basic protection against denial-of-service attacks.
 |`haproxy.router.openshift.io/rate-limit-connections.rate-http`| Limits the rate at which a client with the same source IP address can make HTTP requests. It accepts a numeric value.  +
-Note: Using this annotation provides basic protection against denial-of-service attacks. |
+Note: Using this annotation provides basic protection against denial-of-service attacks.
 |`haproxy.router.openshift.io/rate-limit-connections.rate-tcp`| Limits the rate at which a client with the same source IP address can make TCP connections. It accepts a numeric value.  +
-Note: Using this annotation provides basic protection against denial-of-service attacks. |
-|`haproxy.router.openshift.io/timeout` | Sets a server-side timeout for the route. (TimeUnits) | `ROUTER_DEFAULT_SERVER_TIMEOUT`
-|`haproxy.router.openshift.io/timeout-tunnel` | This timeout applies to a tunnel connection, for example, WebSocket over cleartext, edge, reencrypt, or passthrough routes. With cleartext, edge, or reencrypt route types, this annotation is applied as a timeout tunnel with the existing timeout value. For the passthrough route types, the annotation takes precedence over any existing timeout value set. | `ROUTER_DEFAULT_TUNNEL_TIMEOUT`
-|`ingresses.config/cluster ingress.operator.openshift.io/hard-stop-after` | You can set either an IngressController or the ingress config . This annotation redeploys the router and configures the HA proxy to emit the haproxy `hard-stop-after` global option, which defines the maximum time allowed to perform a clean soft-stop. | `ROUTER_HARD_STOP_AFTER`
-|`router.openshift.io/haproxy.health.check.interval`| Sets the interval for the back-end health checks. (TimeUnits) | `ROUTER_BACKEND_CHECK_INTERVAL`
+|`router.openshift.io/haproxy.health.check.interval`| Sets the interval for the back-end health checks. (TimeUnits)
 |`haproxy.router.openshift.io/ip_allowlist`
 | Sets an allowlist for the route. The allowlist is a space-separated list of IP addresses and CIDR ranges for the approved source addresses. Requests from IP addresses that are not in the allowlist are dropped.
 
-The maximum number of IP addresses and CIDR ranges directly visible in the `haproxy.config` file is 61. [^2^] |
+The maximum number of IP addresses and CIDR ranges directly visible in the `haproxy.config` file is 61. [^2^]
 
-|`haproxy.router.openshift.io/hsts_header` | Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route. |
-|`haproxy.router.openshift.io/rewrite-target` | Sets the rewrite path of the request on the backend. |
+|`haproxy.router.openshift.io/hsts_header` | Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route.
+|`haproxy.router.openshift.io/rewrite-target` | Sets the rewrite path of the request on the backend.
 |`router.openshift.io/cookie-same-site` | Sets a value to restrict cookies. The values are:
 
 `Lax`: the browser does not send cookies on cross-site requests, but does send cookies when users navigate to the origin site from an external site. This is the default browser behavior when the `SameSite` value is not specified.
@@ -54,7 +50,7 @@ The maximum number of IP addresses and CIDR ranges directly visible in the `hapr
 
 `None`: the browser sends cookies for both cross-site and same-site requests.
 
-This value is applicable to re-encrypt and edge routes only. For more information, see the link:https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite cookies documentation].|
+This value is applicable to re-encrypt and edge routes only. For more information, see the link:https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite cookies documentation].
 
 |`haproxy.router.openshift.io/set-forwarded-headers` | Sets the policy for handling the `Forwarded` and `X-Forwarded-For` HTTP headers per route. The values are:
 
@@ -64,7 +60,7 @@ This value is applicable to re-encrypt and edge routes only. For more informatio
 
 `never`: never sets the header, but preserves any existing header.
 
-`if-none`: sets the header if it is not already set.| `ROUTER_SET_FORWARDED_HEADERS`
+`if-none`: sets the header if it is not already set.
 
 |===
 [.small]
@@ -78,53 +74,6 @@ To ensure that the addresses are written to the allowlist, check that the full l
 ====
 --
 
-[NOTE]
-====
-Environment variables cannot be edited.
-====
-
-.Router timeout variables
-
-`TimeUnits` are represented by a number followed by the unit: `us` *(microseconds), `ms` (milliseconds, default), `s` (seconds), `m` (minutes), `h` *(hours), `d` (days).
-
-The regular expression is: [1-9][0-9]*(`us`\|`ms`\|`s`\|`m`\|`h`\|`d`).
-[cols="2,1,2a", options="header"]
-|===
-|Variable | Default | Description
-| `ROUTER_BACKEND_CHECK_INTERVAL` | `5000ms` | Length of time between subsequent liveness checks on back ends.
-| `ROUTER_CLIENT_FIN_TIMEOUT` | `1s` | Controls the TCP FIN timeout period for the client connecting to the route. If the FIN sent to close the connection does not answer within the given time, HAProxy closes the connection. This is harmless if set to a low value and uses fewer resources on the router.
-| `ROUTER_DEFAULT_CLIENT_TIMEOUT` | `30s` | Length of time that a client has to acknowledge or send data.
-| `ROUTER_DEFAULT_CONNECT_TIMEOUT` | `5s` | The maximum connection time.
-| `ROUTER_DEFAULT_SERVER_FIN_TIMEOUT` | `1s` | Controls the TCP FIN timeout from the router to the pod backing the route.
-| `ROUTER_DEFAULT_SERVER_TIMEOUT` | `30s` | Length of time that a server has to acknowledge or send data.
-| `ROUTER_DEFAULT_TUNNEL_TIMEOUT` | `1h` | Length of time for TCP or WebSocket connections to remain open. This timeout period resets whenever HAProxy reloads.
-| `ROUTER_SLOWLORIS_HTTP_KEEPALIVE` | `300s` | Set the maximum time to wait for a new HTTP request to appear. If this is set too low, it can cause problems with browsers and applications not expecting a small `keepalive` value.
-
-Some effective timeout values can be the sum of certain variables, rather than the specific expected timeout. For example, `ROUTER_SLOWLORIS_HTTP_KEEPALIVE` adjusts `timeout http-keep-alive`. It is set to `300s` by default, but HAProxy also waits on `tcp-request inspect-delay`, which is set to `5s`. In this case, the overall timeout would be `300s` plus `5s`.
-| `ROUTER_SLOWLORIS_TIMEOUT` | `10s` | Length of time the transmission of an HTTP request can take.
-| `RELOAD_INTERVAL` | `5s` | Allows the minimum frequency for the router to reload and accept new changes.
-| `ROUTER_METRICS_HAPROXY_TIMEOUT` | `5s` | Timeout for the gathering of HAProxy metrics.
-
-|===
-
-.A route setting custom timeout
-[source,yaml]
-----
-apiVersion: route.openshift.io/v1
-kind: Route
-metadata:
-  annotations:
-    haproxy.router.openshift.io/timeout: 5500ms <1>
-...
-----
-<1> Specifies the new timeout with HAProxy supported units (`us`, `ms`, `s`, `m`, `h`, `d`). If the unit is not provided, `ms` is the default.
-
-[NOTE]
-====
-Setting a server-side timeout value for passthrough routes too low can cause
-WebSocket connections to timeout frequently on that route.
-====
-
 .A route that allows only one specific IP address
 [source,yaml]
 ----
@@ -202,4 +151,4 @@ Certain special characters in `haproxy.router.openshift.io/rewrite-target` requi
 |‘| \’|Avoid ‘ because it is ignored
 |===
 
-All other valid URL characters can be used without escaping.
+All other valid URL characters can be used without escaping.