HAProxy Kubernetes Ingress Controller Service annotations

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

check

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

Values

• true
• false

Default

• true

Example

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/check: "true"

check-http

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/check: "true"
    haproxy.org/check-http: "/health"

check-interval

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/check: "true"
    haproxy.org/check-interval: "1m"

cookie-persistence

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/cookie-persistence: "mycookie"

forwarded-for

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/forwarded-for: "true"

load-balance

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/load-balance: "leastconn"

pod-maxconn

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/pod-maxconn: 30

server-ssl

Enables SSL to pods.

• Enable HTTP/2 support for backend severs.

Values

• true
• false

Default

• false

Example

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/server-ssl: "true"

scale-server-slots

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/scale-server-slots: "75"

ssl-passthrough

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/ssl-passthrough: "true"

timeout-check

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

apiVersion: v1
kind: Service
metadata:
  labels:
    run: web
  name: web
  annotations:

    haproxy.org/timeout-check: 5s

Next up