openshift-docs/modules/nw-route-specific-annotations.adoc

// Module included in the following assemblies:
//
// * networking/routes/route-configuration.adoc

[id="nw-route-specific-annotations_{context}"]
= Route-specific annotations

The Ingress Controller can set the default options for all the routes it exposes. An individual route can override some of these defaults by providing specific configurations in its annotations.


//For all the variables outlined in this section, you can set annotations on the
//*route definition* for the route to alter its configuration.

.Route annotations
[cols="3*", options="header"]
|===
|Variable | Description | Environment variable used as default
|`haproxy.router.openshift.io/balance`| Sets the load-balancing algorithm. Available options are `source`, `roundrobin`, and `leastconn`. | `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. |
|`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. |
|`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.  But 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` to enables rate limiting functionality. |
|`haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp`| Limits the number of concurrent TCP connections shared by an IP address. |
|`haproxy.router.openshift.io/rate-limit-connections.rate-http`| Limits the rate at which an IP address can make HTTP requests. |
|`haproxy.router.openshift.io/rate-limit-connections.rate-tcp`| Limits the rate at which an IP address can make TCP connections. |
|`haproxy.router.openshift.io/timeout` | Sets a server-side timeout for the route. (TimeUnits) | `ROUTER_DEFAULT_SERVER_TIMEOUT`
|`router.openshift.io/haproxy.health.check.interval`| Sets the interval for the back-end health checks. (TimeUnits) | `ROUTER_BACKEND_CHECK_INTERVAL`
|`haproxy.router.openshift.io/ip_whitelist`
| Sets a whitelist for the route. The whitelist 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 whitelist are dropped. |
|`haproxy.router.openshift.io/hsts_header` | Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route. |
|`haproxy.router.openshift.io/log-send-hostname` | Sets the `hostname` field in the Syslog header. Uses the host name of the system. `log-send-hostname` is enabled by default if any Ingress API logging method, such as sidecar or Syslog facility, is enabled for the router. |
|`haproxy.router.openshift.io/rewrite-target` | Sets the rewrite path of the request on the backend. |
|===

[NOTE]
====
Environment variables cannot be edited.
====

.A route setting custom timeout
[source,yaml]
----
apiVersion: 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]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10
----

.A route that allows several IP addresses
[source,yaml]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 192.168.1.11 192.168.1.12
----

.A route that allows an IP address CIDR network
[source,yaml]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 192.168.1.0/24
----

.A route that allows both IP an address and IP address CIDR networks
[source,yaml]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_whitelist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8
----

.A route specifying a rewrite target
[source,yaml]
----
apiVersion: v1
kind: Route
metadata:
  annotations:
    haproxy.router.openshift.io/rewrite-target: / <1>
...
----
<1> Sets `/` as rewrite path of the request on the backend.

Setting the `haproxy.router.openshift.io/rewrite-target` annotation on a route specifies that the Ingress Controller should rewrite paths in HTTP requests using this route before forwarding the requests to the backend application.
The part of the request path that matches the path specified in `spec.path` is replaced with the rewrite target specified in the annotation.

The following table provides examples of the path rewriting behavior for various combinations of `spec.path`, request path, and rewrite target.

.rewrite-target examples:
[cols="4*", options="header"]
|===
|Route.spec.path|Request path|Rewrite target| Forwarded request path
|/foo|/foo|/|/
|/foo|/foo/|/|/
|/foo|/foo/bar|/|/bar
|/foo|/foo/bar/|/|/bar/
|/foo|/foo|/bar|/bar
|/foo|/foo/|/bar|/bar/
|/foo|/foo/bar|/baz|/baz/bar
|/foo|/foo/bar/|/baz|/baz/bar/
|/foo/|/foo|/|N/A (request path does not match route path)
|/foo/|/foo/|/|/
|/foo/|/foo/bar|/|/bar
|===