HAProxy Kubernetes Ingress Controller Documentation 1.9

HAProxy Kubernetes Ingress Controller Ingress annotations

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

`auth-type`

Enables the selected HTTP authentication strategy.

Values

basic-auth

Default

no default value

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/auth-type: basic-auth
    haproxy.org/auth-secret: default/haproxy-credentials

`auth-secret`

Selects the Kubernetes Secret where authentication data can be found.

Encrypted passwords are evaluated using the crypt(3) function, so depending on the system’s capabilities, different algorithms are supported.
Unencrypted passwords (used with HAProxy insecure-password are not accepted.

Values

The annotation format is a secret path namespace/secretName. If the namespace is omitted (path is only secretName) then the ingress namespace will be used. For Basic Authentication, the Secret data should contain user credentials in the form of username: encrypted and base-64 encoded password. For example:

bob: JDEkYWJjJEJYQnFwYjlCWmNaaFhMZ2JlZS4wcy8=

Create the Kubernetes Secret resource in the following way:

kubectl create secret generic haproxy-credentials \
  --from-literal=bob=$(openssl passwd -1 bobPassword) \
  --from-literal=alice=$(openssl passwd -1 alicePassword)

  # secret/haproxy-credentials created

Default

no default value

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/auth-type: basic-auth
    haproxy.org/auth-secret: default/haproxy-credentials

`auth-realm`

Provides the HTTP Authentication Realm

Values

Realm name

Default

Protected Content

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/auth-realm: Admin Area

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

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

`cors-enable`

Enables CORS rules for corresponding Ingress traffic.

Values

true
false

Default

false

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-enable: "true"

`cors-allow-origin`

Sets the Access-Control-Allow-Origin response header to tell browsers which origin is allowed to access the requested resource.

With “regex” value, it is possible to allow a list of origins. If one of them matches the request Origin header it will be returned to the client.

Values

Wildcard *, allow access form any origin.
Regex, regex should match an origin (request Origin header) in the format <scheme> "://" <hostname> [ ":" <port> ] if the origin is matched then it will be the value of Access-Control-Allow-Origin.

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-allow-origin: "*"
    haproxy.org/cors-allow-origin: "https://example.com"
    haproxy.org/cors-allow-origin: "^https://(.+\.)?(example-1\.com|example-2\.com)(:\d{1,5})?$"

`cors-allow-methods`

Sets the Access-Control-Allow-Methods response header to tell browsers the HTTP methods allowed when accessing the request resource.

Values

Wildcard *, allow access for all HTTP methods.
A comma-separated list of HTTP methods

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-allow-methods: "*"
    haproxy.org/cors-allow-methods: "GET"
    haproxy.org/cors-allow-methods: "GET, POST"

`cors-allow-credentials`

Sets the Access-Control-Allow-Credentials response header to tell browsers if credentials can be used to access the requested resource.

Values

true
false

Default

false

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-allow-credentials: "true"

`cors-allow-headers`

Sets the Access-Control-Allow-Headers response header to tell browsers which HTTP headers can be used when accessing the request resource.

Values

Wildcard *, allow access for all HTTP headers.
A comma-separated list of HTTP headers

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-allow-headers: "*"
    haproxy.org/cors-allow-headers: "X-Custom-Header"
    haproxy.org/cors-allow-headers: "X-Custom-Header, Upgrade-Insecure-Requests"

`cors-max-age`

Sets the Access-Control-Allow-Age response header to tell browsers how long the result of a preflight request can be cached.

Values

A time duration

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cors-max-age: "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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/cookie-persistence: "mycookie"

`src-ip-header`

Set the source IP from a header rather than the L3 connection.

Values

any header name

Default

null

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/src-ip-header: "True-Client-IP"

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/forwarded-for: "true"

`ingress.class`

Identifies the ingress controller to be used. If this value is the same as the –ingress.class controller arg, the ingress resource will be processed.

In kubernetes 1.18+, a new IngressClass resource can be referenced by Ingress objects to target an Ingress Controller. More details can be found in the IngressClass doc entry.
In case both ingress.class annotation and ingressClassName are used, ingress.class will have precedence.

Values

The ingress class name

Default

no default value

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/ingress.class: "haproxy"

`load-balance`

Sets the load-balancing algorithm to use.

Values

roundrobin
static-rr
leastconn
first
source
uri
url_param
hdr([name])
random
random([draws])
rdp-cookie
rdp-cookie([name])

Default

roundrobin

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/load-balance: "leastconn"

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/path-rewrite: "/"                        # replace all paths with /
    haproxy.org/path-rewrite: (.*) /foo\1                # add the prefix /foo... "/bar?q=1" into "/foo/bar?q=1"
    haproxy.org/path-rewrite: ([^?]*)(\?(.*))? \1/foo\2  # add the suffix /foo ... "/bar?q=1" into "/bar/foo?q=1"
    haproxy.org/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
    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/pod-maxconn: 30

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/rate-limit-period: "1m"

`rate-limit-status-code`

Sets the status code to return when rate limiting has been triggered.

Values

HTTP status codes; Defaults to 403.

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/rate-limit-status-code: "429"

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    # capture a single value
    haproxy.org/request-capture: cookie(my-cookie)
    
    # capture multiple values
    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/request-capture: cookie(my-cookie)
    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    # single header
    haproxy.org/request-set-header: Ingress-ID abcd123
    
    # multiple headers
    haproxy.org/request-set-header: |
      Ingress-ID abcd123
      Another-Header 12345

`request-redirect`

Enables HTTP request redirection based on host and port substitution in original request.

HTTP redirection code is settable with request-redirect-code annotation.
Port alone is not allowed.

Values

host
host:port

Default

no default value

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/request-redirect: example.com
    haproxy.org/request-redirect: example.com:8888

`request-redirect-code`

Defines the HTTP redirection code used in redirection set with request-redirect.

Values

Integer value.

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/request-redirect-code: "303"

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    # single header
    haproxy.org/response-set-header: Cache-Control "no-store,no-cache,private"
    
    # multiple headers
    haproxy.org/response-set-header: |
      Cache-Control "no-store,no-cache,private"
      Strict-Transport-Security "max-age=31536000"

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/ssl-redirect: "false"
    haproxy.org/ssl-certificate: "default/tls-secret"

`ssl-redirect-code`

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

Values

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

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

`ssl-redirect-port`

Sets the HTTPS port to redirect to when HTTP to HTTPS traffic redirection is enabled when ssl-redirect is true.

When setting the HTTPS port value, keep in mind that this is the HTTPS port as seen by the client, not as set on the Ingress Controller. The reason for this distinction lies in the fact that there will probably be some middleware with its own ports mapping between the client and the Ingress Controller. As a consequence, it must be set with a distinct consideration of how the HTTPS port is set on Ingress Controller with the https-bind-port command line option.

Values

Integer HTTPS port number

Default

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/ssl-redirect: "true"
    haproxy.org/ssl-redirect-port: 8443

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/timeout-check: 5s

`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: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:

    haproxy.org/whitelist: "192.168.1.0/24, 192.168.2.100"

Next up

HAProxy Kubernetes Ingress Controller Service annotations

More Versions

HAProxy Products Documentation

HAProxy Kubernetes Ingress Controller Ingress annotations

Your feedback is important to us!