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

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

:_mod-docs-content-type: CONCEPT
[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. Red Hat does not support adding a route annotation to an operator-managed route.

[IMPORTANT]
====
To create an allow list with multiple source IPs or subnets, use a space-delimited list. Any other delimiter type causes the list to be ignored without a warning or error message.
====

//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="2*", options="header"]
|===
|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.
|`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.
|`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.
|`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.
|`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.
|`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.  +
|`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^]

|`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.

`Strict`: the browser sends cookies only for same-site requests.

`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].

|`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:

`append`: appends the header, preserving any existing header. This is the default value.

`replace`: sets the header, removing any existing header.

`never`: never sets the header, but preserves any existing header.

`if-none`: sets the header if it is not already set.

|===
[.small]
--
1. By default, the router reloads every 5 s which resets the balancing connection across pods from the beginning. As a result, the `roundrobin` state is not preserved across reloads. This algorithm works best when pods have nearly identical computing capabilites and storage capacity. If your application or service has continuously changing endpoints, for example, due to the use of a CI/CD pipeline, uneven balancing can result. In this case, use a different algorithm.
2. If the number of IP addresses and CIDR ranges in an allowlist exceeds 61, they are written into a separate file that is then referenced from the `haproxy.config` file. This file is stored in the `/var/lib/haproxy/router/allowlists` folder.
+
[NOTE]
====
To ensure that the addresses are written to the allowlist, check that the full list of CIDR ranges are listed in the Ingress Controller configuration file. The etcd object size limit restricts how large a route annotation can be. Because of this, it creates a threshold for the maximum number of IP addresses and CIDR ranges that you can include in an allowlist.
====
--

.A route that allows only one specific IP address
[source,yaml]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_allowlist: 192.168.1.10
----

.A route that allows several IP addresses
[source,yaml]
----
metadata:
  annotations:
    haproxy.router.openshift.io/ip_allowlist: 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_allowlist: 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_allowlist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8
----

.A route specifying a rewrite target
[source,yaml]
----
apiVersion: route.openshift.io/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
|===

Certain special characters in `haproxy.router.openshift.io/rewrite-target` require special handling because they must be escaped properly. Refer to the following table to understand how these characters are handled.

.Special character handling
[cols="3*", options="header"]
|===
|For character|Use characters|Notes
|#|\#|Avoid # because it terminates the rewrite expression
|%|% or %%|Avoid odd sequences such as %%%
|‘| \’|Avoid ‘ because it is ignored
|===

All other valid URL characters can be used without escaping.