HAProxy Kubernetes Ingress Controller Documentation 1.10

Service annotations

These options can be set in a Kubernetes Service 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"

`backend-config-snippet`

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

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)

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

`route-acl`

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.

Values

A string describing an in-line HAProxy ACL.

Default

no default value

Example

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

    haproxy.org/route-acl: cookie(staging) -m found

`send-proxy-protocol`

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

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

    haproxy.org/send-proxy-protocol: proxy-v2

`server-ca`

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.
The secret must use ‘tls.crt’ key.

Values

Secret path following namespace/secretname format.

Default

no default value

Example

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

    haproxy.org/server-ca: "ns1/ca"

`server-crt`

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.

Values

Secret path following namespace/secretname format.

Default

no default value

Example

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

    haproxy.org/server-crt: "ns1/client"

`server-proto`

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

Default

no default value

Example

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

    haproxy.org/server-proto: "h2"

`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

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"

`standalone-backend`

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

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

    haproxy.org/standalone-backend: "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

Set an IngressClassName

More Versions

HAProxy Products Documentation

Service annotations

Your feedback is important to us!