HAProxy Kubernetes Ingress Controller Documentation 1.4

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.

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"

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"

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 [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: 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

  • 1s

Example

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

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

  • 128

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

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"

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

  • 42

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

  • 301
  • 302
  • 303

Default

  • 302

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"

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

Service annotations