HAProxy Kubernetes Ingress Controller Documentation 1.4

HAProxy Kubernetes Ingress Controller ConfigMap options

These options can be stored in a ConfigMap to change the ingress controller’s global behavior, affecting all Ingress routes.

A ConfigMap is created during the installation and you can find it with the kubectl get configmaps command.

$ kubectl get configmaps --namespace haproxy-controller

  NAME                         DATA   AGE
  haproxy-kubernetes-ingress   0      13s

You can edit the ConfigMap:

$ kubectl edit configmap haproxy-kubernetes-ingress --namespace haproxy-controller

`blacklist`

Blocks given IP addresses and/or IP address ranges.

The value is treated as a pattern file (see --configmap-patternfiles) if it starts with patterns/. It should consist of a list of IPs or CIDRs, one per line.

Values

Comma-separated list of IP addresses and/or CIDR ranges
Path to a pattern file, e.g. pattern/ips

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  blacklist: "192.168.1.0/24, 192.168.2.100"

`check`

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

Values

true
false

Default

true

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  check: "true"
  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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  check: "true"
  check-interval: "1m"

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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  cookie-persistence: "mycookie"

`dontlognull`

Do not log connections that sends no data, which can happen with monitoring systems.

Values

true
false

Default

true

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  dontlognull: "true"

`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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  forwarded-for: "true"

`hard-stop-after`

Defines the maximum time allowed to perform a clean soft-stop.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  hard-stop-after: 30s

`http-keep-alive`

Deprecated, use http-connection-mode instead. Enables HTTP Keep-Alive both from the client to HAProxy and from HAProxy to the backend.

Values

true
false

Default

true

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  http-keep-alive: "true"

`http-server-close`

Deprecated, use http-connection-mode instead. Disables HTTP Keep-Alive between HAProxy and the backend, while allowing it to stay enabled from the client to HAProxy.

Values

true
false

Default

false

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  http-server-close: "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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  load-balance: "leastconn"

`log-format`

Sets the log format string to use for HTTP traffic.

Default log-format is: %ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs \"%HM %[var(txn.base)] %HV\" Which will look like this: 10.244.0.1:5793 [10/Apr/2020:10:32:50.132] https~ test-echo1-8080/SRV_TFW8V 0/0/1/2/3 200 653 - - ---- 1/1/0/0/0 0/0 "GET test.k8s.local/ HTTP/2.0

Values

Log format string. More information in HAProxy documentation

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  log-format: "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs \"%HM %[var(txn.base)] %HV\""

`logasap`

Logs request and response data as soon as the server returns a complete set of HTTP response headers, instead of waiting for the response to finish sending all data.

Values

true
false

Default

false

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  logasap: "true"

`maxconn`

Sets the maximum number of concurrent connections that HAProxy will accept.

Values

An integer setting the allowed number of concurrent connections

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  maxconn: "2000"

`nbthread`

Sets the number of worker threads that the HAProxy process will start. If not set, HAProxy will create a thread for each available processor.

Values

An integer setting the number of worker threads

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  nbthread: "8"

`path-rewrite`

Replaces the entire URL path with the given value.

Values

A single path, such as “/”, to turn any path into “/”
Two parameters. A regular expression to match and a path to replace it with.
Multiline annotation is split into more rewrite rules.

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:
  path-rewrite: "/"                        # replace all paths with /
  path-rewrite: (.*) /foo\1                # add the prefix /foo... "/bar?q=1" into "/foo/bar?q=1"
  path-rewrite: ([^?]*)(\?(.*))? \1/foo\2  # add the suffix /foo ... "/bar?q=1" into "/bar/foo?q=1"
  path-rewrite: /foo/(.*) /\1              # strip /foo ... "/foo/bar?q=1" into "/bar?q=1"
  
  # strip /foo ... "/foo/bar?q=1" into "/bar?q=1" and replace "/bar/*" with "/baz/*"
  # with multiline (using `|`) annotation
  path-rewrite: |
    /foo/(.*) /\1
    /bar/(.*) /baz/\1

`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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  pod-maxconn: 30

`proxy-protocol`

Enables Proxy Protocol on client side for a comma-delimited list of IP addresses and/or CIDR ranges. The 0.0.0.0/0 CIDR will enable Proxy Protocol for all incoming traffic.

Connection will fail with 400 Bad Request if source IP is in annotation list but no Proxy Protocol data is sent.

Values

A list of IP addresses and/or CIDR ranges

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  proxy-protocol: "192.168.1.0/24, 192.168.2.100"

`rate-limit-period`

Sets the period of time over which requests are tracked for a given source IP address.

Values

Integer with unit of time (1s = 1 second, 1m = 1 minute); Defaults to 1 second

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  rate-limit-period: "1m"

`rate-limit-requests`

Sets the maximum number of requests that will be accepted from a source IP address during the rate-limit-period.

If this number is exceeded, HAProxy will deny requests with 403 status code.
To track the http requests rate, a stick-table named “Ratelimit-" will be created. For example, if the `rate-limit-period` is set to *2s*, the name of the table will be *Ratelimit-2000*.

Values

An integer representing the maximum number of requests to accept

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  rate-limit-requests: 15

`rate-limit-size`

Sets how many source IP addresses to track, after which older entries are replaced by new entries.

If this number is exceeded, older entries will be dropped as new ones come

Values

An integer defining how many IP addresses to track for rate limiting; Defaults to 100,000

Default

100k

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  rate-limit-size: 1000000

`request-capture`

When you include %hr in the log-format string, which is included in the default log format, it captures custom information in the logs, which you define with this field. For example, you can capture specific cookie values or HTTP header values.

Captures samples of the request using sample expression and log them in HAProxy traffic logs.

Values

A header value, e.g. hdr(header-name)
A cookie value, e.g. cookie(cookie-name)
Multiple expressions by using a multiline YAML string

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:
  # capture a single value
  request-capture: cookie(my-cookie)
  
  # capture multiple values
  request-capture: |
    cookie(my-cookie)
    hdr(Host)
    hdr(User-Agent)

`request-capture-len`

Sets how many characters to allocate for fields captured by request-capture.

Values

An integer representing the number of characters for captured fields; Defaults to 128

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  request-capture: cookie(my-cookie)
  request-capture-len: 350

`request-set-header`

Sets an HTTP header in the request before it is passed to the backend service.

This sets header before HAProxy does any service/backend dispatch. So in the case you want to change the Host header this will impact HAProxy decision on which service/backend to use (based on matching Host against ingress rules). In order to set the Host header after service selection, use set-host annotation.

Values

The name of the field, following by its value, e.g. Ingress-ID abcd123
Multiple headers can be set using a multiline YAML string

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:
  # single header
  request-set-header: Ingress-ID abcd123
  
  # multiple headers
  request-set-header: |
    Ingress-ID abcd123
    Another-Header 12345

`response-set-header`

Sets an HTTP header in the response before it is passed to the client.

Values

The name of the field, following by its value, e.g. Cache-Control “no-store,no-cache,private”
Multiple headers can be set using a multiline YAML string

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:
  # single header
  response-set-header: Cache-Control "no-store,no-cache,private"
  
  # multiple headers
  response-set-header: |
    Cache-Control "no-store,no-cache,private"
    Strict-Transport-Security "max-age=31536000"

`server-ssl`

Enables SSL to pods.

Enable HTTP/2 support for backend severs.

Values

true
false

Default

false

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  server-ssl: "true"

`set-host`

Sets the Host header to send to backend services.

Values

The value of the Host header

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  set-host: "example.local"

`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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  scale-server-slots: "75"

`ssl-certificate`

Sets the name of the Kubernetes secret that contains both the TLS key and certificate.

this replaces default certificate

Values

Name of Kubernetes secret

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  ssl-certificate: "default/tls-secret"

`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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  ssl-passthrough: "true"

`ssl-redirect`

Sets whether to redirect traffic from HTTP to HTTPS.

SSL redirection is enabled by default for any ingress resource defined with a TLS section spec.tls[].secretName.
Automatic redirects for ingress resources with TLS enabled, can be disabled by setting annotation to “false” in configmap

Values

true
false

Default

false

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  ssl-redirect: "false"
  ssl-certificate: "default/tls-secret"

`ssl-redirect-code`

Sets the HTTP status code to use when ssl-redirect is true.

Values

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  ssl-redirect: "true"
  ssl-certificate: "default/tls-secret"
  ssl-redirect-code: "301"

`syslog-server`

Sets one or more Syslog servers where logs should be forwarded. Each server is placed onto its own line. A line supports the following arguments, which are separated by commas

More information can be found in the HAProxy documentation

Values

address - Required - IP address where the syslog server is listening.
facility - Required - One of the 24 syslog facilities (kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, auth2, ftp, ntp, audit, alert, con2, local0, local1, local2, local3, local4, local5, local6, local7); In general, you will want to use one of the localX values, since the others are registered for specific types of applications.
format - Syslog format, one of the following - rfc3164, rfc5424, short, raw. to rfc3164. HAProxy default is rfc3164
length - Maximum syslog line length. HAProxy default is 1024.
level - Maximum verbosity level to filter outgoing messages; Only messages with a severity at least as important as this level will be sent; Use one of the following (emerg, alert, crit, err, warning, notice, info, debug); Traffic logs are emitted at “info” or higher severity. Haproxy default is to send all messages.
minlevel - Minimum verbosity level. Logs emitted with a more severe level than this one will be capped to this level. HAProxy default does not set a minlevel.
port - Port number where the syslog server is listening. HAProxy default is 514.

Default

address:127.0.0.1, facility: local0, level: notice

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:
  # a single entry
  syslog-server: "address:192.158.1.1, port:514, facility:local0"
  
  # log to stdout
  syslog-server: "address:stdout, format: raw, facility:daemon"
  
  # multiple entries
  syslog-server: |
    address:127.0.0.1, port:514, facility:local0
    address:192.168.1.1, port:514, facility:local1

`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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-check: 5s

`timeout-client`

Set the maximum inactivity time on the client side.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-client: 5s

`timeout-client-fin`

Sets the inactivity timeout on the client side for half-closed connections.

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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-client-fin: 5s

`timeout-connect`

Sets the maximum time to wait for a connection attempt to a server to succeed.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-connect: 5s

`timeout-http-request`

Sets the maximum allowed time to wait for a complete HTTP request.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-http-request: 5s

`timeout-http-keep-alive`

Sets the maximum allowed time to wait for a new HTTP request to appear.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-http-keep-alive: 5s

`timeout-queue`

Sets the maximum time to wait in the queue for a connection slot to be free.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-queue: 5s

`timeout-server`

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

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-server: 5s

`timeout-server-fin`

Sets the inactivity timeout on the server side for half-closed connections.

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: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-server-fin: 5s

`timeout-tunnel`

Set the maximum inactivity time on the client and server side for tunnels.

Values

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

Default

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  timeout-tunnel: 30m

`whitelist`

Blocks all IP addresses except the whitelisted ones (annotation value).

The value is treated as a pattern file (see --configmap-patternfiles) if it starts with patterns/. It should consist of a list of IPs or CIDRs, one per line.

Values

Comma-separated list of IP addresses and/or CIDR ranges
Path to a pattern file, e.g. pattern/ips

Default

no default value

Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: haproxy-kubernetes-ingress
  namespace: default
data:

  whitelist: "192.168.1.0/24, 192.168.2.100"

Next up

HAProxy Kubernetes Ingress Controller Ingress annotations

HAProxy Kubernetes Ingress Controller ConfigMap options

Your feedback is important to us!