Service annotations

These annotations can be set in a Kubernetes Service object’s metadata.annotations section to change how requests are routed for a particular service.

backend-config-snippet Jump to heading #

Values

• One or more valid HAProxy directives

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/backend-config-snippet: |
      http-send-name-header x-dst-server
      stick-table type string len 32 size 100k expire 30m
      stick on req.cook(sessionid)

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/backend-config-snippet: |
      http-send-name-header x-dst-server
      stick-table type string len 32 size 100k expire 30m
      stick on req.cook(sessionid)

check Jump to heading #

Values

• true
• false

Default

• true

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"

check-http Jump to heading #

Values

• URI to make HTTP requests to, e.g. /health
• URI with method, e.g. HEAD /health
• URI, method and HTTP version, e.g. HEAD /health HTTP/1.1

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"
    haproxy.org/check-http: "/health"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"
    haproxy.org/check-http: "/health"

check-interval Jump to heading #

Values

• Integer with time unit suffix (1m = 1 minute, 10s = 10 seconds)

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"
    haproxy.org/check-interval: "1m"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/check: "true"
    haproxy.org/check-interval: "1m"

cookie-persistence Jump to heading #

• This will insert the following cookie configuration in the corresponding backend cookie <cookie-name> insert indirect nocache dynamic with <cookie-name> the value of this annotation.
• This annotation is resolved at the service level, falling back to the configmap default. As the HAProxy backend is shared by every ingress referencing the same service, setting it on an ingress is ignored to avoid a non-deterministic backend configuration. The service value takes precedence over the configmap default.

Values

• A name for the cookie

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/cookie-persistence: "mycookie"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/cookie-persistence: "mycookie"

cookie-persistence-no-dynamic Jump to heading #

• This will insert the following cookie configuration in the corresponding backend cookie <cokkie-name> indirect nocache insert with <cookie-name> the value of this annotation. The server line will have server <server-name> <server-address> enabled cookie <server-name>
• This annotation is resolved at the service level, falling back to the configmap default. As the HAProxy backend is shared by every ingress referencing the same service, setting it on an ingress is ignored to avoid a non-deterministic backend configuration. The service value takes precedence over the configmap default.

Values

• A name for the cookie

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/cookie-persistence-no-dynamic: "mycookie"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/cookie-persistence-no-dynamic: "mycookie"

forwarded-for Jump to heading #

Values

• true
• false

Default

• true

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/forwarded-for: "true"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/forwarded-for: "true"

load-balance Jump to heading #

Values

• roundrobin
• static-rr
• leastconn
• first
• source
• uri [path-only] [whole] [len num] [depth num]
• url_param name [check_post num]
• hdr[(name)] [use_domain_only]
• random[(draws)]
• rdp-cookie[(name)]

Default

• roundrobin

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/load-balance: "leastconn"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/load-balance: "leastconn"

pod-maxconn Jump to heading #

• NB, If multiple HAProxy instances are running, the maxconn will be pod-maxconn number devided by the number of haproxy instances.

Values

• An integer setting the maximum number of concurrent backend connections

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/pod-maxconn: "30"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/pod-maxconn: "30"

route-acl Jump to heading #

• In order for the service to be handled by the Ingress Controller, it is still mandatory to put it in an ingress rule. Using only route-acl won’t be enough.
• Note that this annotation is not compatible with an Ingress having multiple paths that will match a request. Without this annotation, the precedence is given first to the longest matching path. But with the annotation, the first use_backend rule in the config that matches the request will be used.

Values

• A string describing an in-line HAProxy ACL.

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/route-acl: cookie(staging) -m found

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/route-acl: cookie(staging) -m found

scale-server-slots Jump to heading #

• Equivalent old annotations are servers-increment and server-slots

Values

• Integer value indicating the number of backend servers to provision. Defaults to 42.

Default

• 42

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/scale-server-slots: "75"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/scale-server-slots: "75"

send-proxy-protocol Jump to heading #

Values

• proxy - Uses PROXY v1
• proxy-v1 - Uses PROXY v1
• proxy-v2 - Uses PROXY v2
• proxy-v2-ssl Uses PROXY v2 with SSL information extension
• proxy-v2-ssl-cn Uses PROXY v2 with SSL and Common Name information extension

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/send-proxy-protocol: proxy-v2

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/send-proxy-protocol: proxy-v2

server-ca Jump to heading #

• When used with server-crt resulting configuration provides mutual TLS authentication (mTLS).
• The secret must use ‘tls.crt’ key.

Values

• Secret path following namespace/secretname format.

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-ca: "ns1/ca"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-ca: "ns1/ca"

server-crt Jump to heading #

• The secret must use ‘tls.key’ and ‘tls.crt’ keys.
• When used with server-ca resulting configuration provides mutual TLS authentication (mTLS).

Values

• Secret path following namespace/secretname format.

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-crt: "ns1/client"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-crt: "ns1/client"

server-proto Jump to heading #

Values

• h2

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-proto: "h2"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-proto: "h2"

server-ssl Jump to heading #

• Enable HTTP/2 support for backend severs.

Values

• true
• false

Default

• false

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-ssl: "true"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/server-ssl: "true"

ssl-passthrough Jump to heading #

• Traffic is proxied in TCP mode which makes unavailable a number of the controller annotations (requiring HTTP mode).
• HTTPS frontend is conserved and still listening at port 8444 when previous HTTPS port is moved to SSL Frontend.

Values

• true
• false

Default

• false

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/ssl-passthrough: "true"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/ssl-passthrough: "true"

standalone-backend Jump to heading #

• With this annotation you can create your own separate backend whose configuration won’t be impacted by others ingresses. As a reminder, all ingresses refering to the same service have their configuration inserted in the same backend which can cause some conflict.

Values

• true
• false

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/standalone-backend: "true"

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/standalone-backend: "true"

timeout-check Jump to heading #

Values

• An integer with a unit of time (1 second = 1s, 1 minute = 1m, 1h = 1 hour)

Default

• No default value

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/timeout-check: 5s

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/timeout-check: 5s

timeout-server Jump to heading #

Values

• An integer with a unit of time (1 second = 1s, 1 minute = 1m, 1h = 1 hour); Defaults to 50s

Default

• 50s

Example

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/timeout-server: 5s

yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:
    haproxy.org/timeout-server: 5s