Configuration reference

Ingress annotations

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

Ingress annotations reference Jump to heading

allow-list Jump to heading

Available since

version 1.11

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/allow-list: "192.168.1.0/24, 192.168.2.100"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/allow-list: "192.168.1.0/24, 192.168.2.100"

auth-realm Jump to heading

Available since

version 1.5

Values

  • Realm name

Default

  • Protected Content

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-realm: Admin Area
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-realm: Admin Area

auth-secret Jump to heading

Available since

version 1.5

  • 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=
bob: JDEkYWJjJEJYQnFwYjlCWmNaaFhMZ2JlZS4wcy8=

Create the Kubernetes Secret resource in the following way:

bash
kubectl create secret generic haproxy-credentials \
--from-literal=bob=$(openssl passwd -1 bobPassword) \
--from-literal=alice=$(openssl passwd -1 alicePassword)
# secret/haproxy-credentials created
bash
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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-type: basic-auth
haproxy.org/auth-secret: default/haproxy-credentials
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-type: basic-auth
haproxy.org/auth-secret: default/haproxy-credentials

auth-type Jump to heading

Available since

version 1.5

Values

  • basic-auth

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-type: basic-auth
haproxy.org/auth-secret: default/haproxy-credentials
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-type: basic-auth
haproxy.org/auth-secret: default/haproxy-credentials

backend-config-snippet Jump to heading

Available since

version 1.5

Values

  • One or more valid HAProxy directives

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
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)
yaml
apiVersion: networking.k8s.io/v1
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)

blacklist Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/blacklist: "192.168.1.0/24, 192.168.2.100"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/blacklist: "192.168.1.0/24, 192.168.2.100"

check Jump to heading

Available since

version 1.4

Values

  • true
  • false

Default

  • true

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"

check-http Jump to heading

Available since

version 1.4

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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
haproxy.org/check-http: "/health"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
haproxy.org/check-http: "/health"

check-interval Jump to heading

Available since

version 1.4

Values

  • Integer with time unit suffix (1m = 1 minute, 10s = 10 seconds)

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
haproxy.org/check-interval: "1m"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
haproxy.org/check-interval: "1m"

Available since

version 1.4

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cookie-persistence: "mycookie"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cookie-persistence: "mycookie"

cors-allow-credentials Jump to heading

Available since

version 1.5

Values

  • true
  • false

Default

  • false

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-allow-credentials: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-allow-credentials: "true"

cors-allow-headers Jump to heading

Available since

version 1.5

Values

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

Default

Example

yaml
apiVersion: networking.k8s.io/v1
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"
yaml
apiVersion: networking.k8s.io/v1
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-allow-methods Jump to heading

Available since

version 1.5

Values

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

Default

Example

yaml
apiVersion: networking.k8s.io/v1
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"
yaml
apiVersion: networking.k8s.io/v1
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-origin Jump to heading

Available since

version 1.5

  • 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

yaml
apiVersion: networking.k8s.io/v1
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})?$"
yaml
apiVersion: networking.k8s.io/v1
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-enable Jump to heading

Available since

version 1.5

Values

  • true
  • false

Default

  • false

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-enable: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-enable: "true"

cors-max-age Jump to heading

Available since

version 1.5

Values

Default

  • 5s

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-max-age: "1m"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-max-age: "1m"

deny-list Jump to heading

Available since

version 1.11

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/deny-list: "192.168.1.0/24, 192.168.2.100"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/deny-list: "192.168.1.0/24, 192.168.2.100"

forwarded-for Jump to heading

Available since

version 1.4

Values

  • true
  • false

Default

  • true

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/forwarded-for: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/forwarded-for: "true"

ingress.class Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ingress.class: "haproxy"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ingress.class: "haproxy"

load-balance Jump to heading

Available since

version 1.4

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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/load-balance: "leastconn"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/load-balance: "leastconn"

path-rewrite Jump to heading

Available since

version 1.4

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

yaml
apiVersion: networking.k8s.io/v1
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
yaml
apiVersion: networking.k8s.io/v1
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 Jump to heading

Available since

version 1.4

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/pod-maxconn: 30
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/pod-maxconn: 30

rate-limit-period Jump to heading

Available since

version 1.4

Values

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

Default

  • 1s

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-period: "1m"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-period: "1m"

rate-limit-requests Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-requests: 15
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-requests: 15

rate-limit-size Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-size: 1000000
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-size: 1000000

rate-limit-status-code Jump to heading

Available since

version 1.5

Values

  • HTTP status codes; Defaults to 403.

Default

  • 403

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-status-code: "429"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-status-code: "429"

request-capture Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
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)
yaml
apiVersion: networking.k8s.io/v1
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 Jump to heading

Available since

version 1.4

Values

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

Default

  • 128

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-capture: cookie(my-cookie)
haproxy.org/request-capture-len: 350
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-capture: cookie(my-cookie)
haproxy.org/request-capture-len: 350

request-redirect Jump to heading

Available since

version 1.5

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

Values

  • host
  • host:port

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-redirect: example.com
haproxy.org/request-redirect: example.com:8888
yaml
apiVersion: networking.k8s.io/v1
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 Jump to heading

Available since

version 1.5

Values

  • Integer value.

Default

  • 302

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-redirect-code: "303"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-redirect-code: "303"

request-set-header Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
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
yaml
apiVersion: networking.k8s.io/v1
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

response-set-header Jump to heading

Available since

version 1.4

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

yaml
apiVersion: networking.k8s.io/v1
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"
yaml
apiVersion: networking.k8s.io/v1
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"

scale-server-slots Jump to heading

Available since

version 1.4

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/scale-server-slots: "75"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/scale-server-slots: "75"

send-proxy-protocol Jump to heading

Available since

version 1.5

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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/send-proxy-protocol: proxy-v2
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/send-proxy-protocol: proxy-v2

server-ca Jump to heading

Available since

version 1.5

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ca: "ns1/ca"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ca: "ns1/ca"

server-crt Jump to heading

Available since

version 1.5

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-crt: "ns1/client"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-crt: "ns1/client"

server-proto Jump to heading

Available since

version 1.5

Values

  • h2

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-proto: "h2"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-proto: "h2"

server-ssl Jump to heading

Available since

version 1.4

  • Enable HTTP/2 support for backend severs.

Values

  • true
  • false

Default

  • false

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ssl: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ssl: "true"

set-host Jump to heading

Available since

version 1.4

Values

  • The value of the Host header

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/set-host: "example.local"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/set-host: "example.local"

src-ip-header Jump to heading

Available since

version 1.5

Values

  • any header name

Default

  • null

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/src-ip-header: "True-Client-IP"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/src-ip-header: "True-Client-IP"

ssl-passthrough Jump to heading

Available since

version 1.4

  • Traffic is proxied in TCP mode which makes unavailable a number of the controller annotations (requiring HTTP mode).
  • HTTPS frontend is conserved and still listening at port 8444 when previous HTTPS port is moved to SSL Frontend.

Values

  • true
  • false

Default

  • false

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-passthrough: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-passthrough: "true"

ssl-redirect Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-redirect: "false"
haproxy.org/ssl-certificate: "default/tls-secret"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-redirect: "false"
haproxy.org/ssl-certificate: "default/tls-secret"

ssl-redirect-code Jump to heading

Available since

version 1.4

Values

  • 301
  • 302
  • 303

Default

  • 302

Example

yaml
apiVersion: networking.k8s.io/v1
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"
yaml
apiVersion: networking.k8s.io/v1
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 Jump to heading

Available since

version 1.5

  • 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

  • 8443

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-redirect: "true"
haproxy.org/ssl-redirect-port: "8443"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-redirect: "true"
haproxy.org/ssl-redirect-port: "8443"

standalone-backend Jump to heading

Available since

version 1.10

  • 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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/standalone-backend: "true"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/standalone-backend: "true"

timeout-check Jump to heading

Available since

version 1.4

Values

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

Default

  • No default value

Example

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/timeout-check: 5s
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/timeout-check: 5s

timeout-server Jump to heading

Available since

version 1.11

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: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/timeout-server: 5s
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/timeout-server: 5s

whitelist Jump to heading

Available since

version 1.4

  • 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

yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/whitelist: "192.168.1.0/24, 192.168.2.100"
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/whitelist: "192.168.1.0/24, 192.168.2.100"

Do you have any suggestions on how we can improve the content of this page?