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.

Service annotations reference Jump to heading #

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.

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>

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