Configuration reference

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

check Jump to heading

Available since

version 1.4

Enables TCP level health checks on pods and attempts a TCP connection periodically.

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

Available since

version 1.4

Enables HTTP level health checks on pods and sends an HTTP request periodically. The check setting must be true.

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

Available since

version 1.4

Sets the interval between health checks when check is enabled.

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"

backend-config-snippet Jump to heading

Available since

version 1.5

Defines a group of configuration directives to add directly to a HAProxy backend section.

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)

Available since

version 1.4

Enables persistent connections (sticky sessions) between a client and a pod by inserting a cookie into the client’s browser that is used to remember which backend pod they connected to before. Dynamic cookies are used by default via a dynamic-cookie-key in order to support sticky sessions across multiple Ingress Controller instances/replicas.

  • 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"

forwarded-for Jump to heading

Available since

version 1.4

Adds the X-Forwarded-For HTTP header to requests to capture and relay the client’s source IP address to backend pods.

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

Available since

version 1.4

Sets the load-balancing algorithm to use.

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

Available since

version 1.4

Sets the maximum number of concurrent connections (maxconn) on a backend server (application pod).

  • 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

Available since

version 1.6

Insert a custom route (use_backend rule) to route ingress traffic to the annotated service based on the provided ACL.

  • 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

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

send-proxy-protocol Jump to heading

Available since

version 1.5

Uses the PROXY Protocol when connecting to backend servers.

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

Available since

version 1.5

Sets the certificate authority for backend servers enabling HAProxy to check backend certificates (TLS authentication) when sending encrypted traffic to the kubernetes applications.

  • 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

Available since

version 1.5

Specifies the path of a secret containing a certificate that HAProxy can provide during TLS communication with the backend servers.

  • 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

Available since

version 1.5

HTTP/1.1 is the default protocol for backend servers communication. Currently, the server-proto annotation supports only “h2” as a value (supporting fcgi is also planned) which transmits HTTP/2 messages in the clear to the backend servers. However, when SSL is enabled on the backend, server-proto is ignored and both HTTP/1.1 and HTTP/2 are advertised via ALPN and transmitted as encrypted messages.

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

Available since

version 1.4

Enables SSL to pods.

  • 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"

scale-server-slots Jump to heading

Available since

version 1.4

Sets the number of server slots to provision in order for HAProxy to scale dynamically with no reload. If this number is greater than the available endpoints/addresses, the remaining slots will be disabled (put on stand-by) and ready to be used. If this number is lower, the remaining endpoints/addresses will be added after scaling the HAProxy backend with a reload.

  • 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"

ssl-passthrough Jump to heading

Available since

version 1.4

Passes SSL/TLS traffic through at Layer 4 directly to the backend service without Layer 7 inspection.

  • Traffic is proxied in TCP mode which makes unavailable a number of the controller annotations (requiring HTTP mode).

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

Available since

version 1.10

Creates a specific and separated backend for this ingress in case multiple ingresses refer to the same service.

  • 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

Available since

version 1.4

Sets an additional check timeout, but only after a connection has been already established.

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

Available since

version 1.4

Sets the maximum inactivity time on the server side.

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

If this page was useful, please, Leave the feedback.