Ingress Options

These options can be set in an 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.

Values

  • Comma-separated list of IP addresses and/or CIDR ranges

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"
spec:
  # ingress specification...

check

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

Values

  • true (default)

  • false

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/check: "true"
spec:
  # ingress specification...

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

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/check: "true"
    haproxy.org/check-http: "/health"
spec:
  # ingress specification...

check-interval

Sets the interval between health checks when check is enabled.

Values

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

Example

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

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 (default)

  • false

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/forwarded-for: "true"
spec:
  # ingress specification...

ingress.class

Targets an ingress controller by class name for this ingress to use.

Values

  • The ingress class name

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/ingress.class: "haproxy"
spec:
  # ingress specification...

load-balance

Sets the load-balancing algorithm to use.

Values

  • roundrobin (default)

  • static-rr

  • leastconn

  • first

  • source

  • uri

  • url_param

  • hdr([name])

  • random

  • random([draws])

  • rdp-cookie

  • rdp-cookie([name])

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/load-balance: "leastconn"
spec:
  # ingress specification...

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.

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    # replace all paths with /
    haproxy.org/path-rewrite: "/"

    # remove the prefix /foo... "/bar?q=1" into "/foo/bar?q=1"
    haproxy.org/path-rewrite: (.*) /foo\1

    # add the suffix /foo ... "/bar?q=1" into "/bar/foo?q=1"
    haproxy.org/path-rewrite: ([^?]*)(\?(.*))? \1/foo\2

    # strip /foo ... "/foo/bar?q=1" into "/bar?q=1"
    haproxy.org/path-rewrite: /foo/(.*) /\1
spec:
  # ingress specification...

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

Example

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

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.

Values

  • A header value, e.g. hrd(header-name)

  • A cookie value, e.g. cookie(cookie-name)

  • Multiple expressions by using a multiline YAML string

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)

    # capturing multiple values
    haproxy.org/request-capture: |-
      cookie(my-cookie)
      hdr(Host)
      hdr(User-Agent)
spec:
  # ingress specification...

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

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
spec:
  # ingress specification...

request-set-header

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

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

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
spec:
  # ingress specification...

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

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"
spec:
  # ingress specification...

server-ssl

Enables SSL to pods.

Values

  • true

  • false (default)

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/server-ssl: "true"
spec:
  # ingress specification...

set-host

Sets the Host header to send to backend services.

Values

  • The value of the Host header

Example

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

ssl-passthrough

Passes SSL/TLS traffic through at Layer 4 directly to the backend service without Layer 7 inspection.

Values

  • true

  • false (default)

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/ssl-passthrough: "true"
spec:
  # ingress specification...

ssl-redirect

Sets whether to redirect traffic from HTTP to HTTPS. By default, this is activated when ssl-certificate is set.

Values

  • true

  • false (default)

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/ssl-redirect: "false"
spec:
  # ingress specification...

ssl-redirect-code

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

Values

  • 301

  • 302 (default)

  • 303

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/ssl-redirect: "true"
    haproxy.org/ssl-redirect-code: "301"
spec:
  # ingress specification...

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)

Example

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: web-ingress
  namespace: default
  annotations:
    haproxy.org/timeout-check: "5s"
spec:
  # ingress specification...

whitelist

Sets a list of IP addresses or CIDRs to exclude from deny rules, such as rate limiting.

Values

  • Comma-separated list of IP addresses and/or CIDR ranges

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"
spec:
  # ingress specification...

Next up

Service