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.
Enables the selected authentication strategy.
Values
Default
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
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 annotaiton format is a secret path namespace/secretName. If the namespace is ommited (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 passowrd
. 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
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
Provides the HTTP Authentication Realm
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/auth-realm: Admin Area
Blocks given IP addresses and/or IP address ranges.
Values
- Comma-separated list of IP addresses and/or CIDR ranges
Default
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"
Enables TCP level health checks on pods and attempts a TCP connection periodically.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/check: "true"
haproxy.org/check-http: "/health"
Sets the interval between health checks when check
is enabled.
Values
- Integer with time unit suffix (1m = 1 minute, 10s = 10 seconds)
Default
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 CORS rules for corresponding Ingress traffic.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-enable: "true"
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})?$"
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 seperated 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"
Sets the Access-Control-Allow-Credentials
response header to tell browsers if credentials can be used to access the requested resource.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-allow-credentials: "true"
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 seperated 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"
Sets the Access-Control-Allow-Age
response header to tell browsers how long the result of a preflight request can be cached.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cors-max-age: "1m"
Defines a group of configuration directives to add directly to a HAProxy backend section.
Values
- One or more valid HAProxy directives
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
Enables persistent connections 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.
- This will insert the following cookie configuration in the corresponding backend
cookie <cookie-name> insert indirect nocache
with <cookie-name>
the value of this annotation.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/cookie-persistence: "mycookie"
Set the source IP from a header rather than the L3 connection.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/src-ip-header: "True-Client-IP"
Adds the X-Forwarded-For HTTP header to requests to capture and relay the client’s source IP address to backend pods.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/forwarded-for: "true"
Targets an ingress controller by class name for this ingress to use.
- Any ingress object which have class specified and its different from one defined in image arguments will be ignored
- default: “” - all ingress objects are monitored
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ingress.class: "haproxy"
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/load-balance: "leastconn"
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.
Default
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"
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"
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"
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-requests: 15
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/rate-limit-size: 1000000
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
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)
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
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
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
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
Default
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
Defines the HTTP redirection code used in redirection set with request-redirect.
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/request-redirect-code: "303"
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
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"
Specifies the path of a secret containing a CA certificate (certificate authority) enabling HAProxy to verify a backend’s certificate via the ca-file
directive. When the CA certificate is properly configured this also sets the HAProxy verify directive to required.
- The secret must use ‘tls.crt’ key.
Values
- Secret path following namespace/secretname format.
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ca: "ns1/ca"
Specifies the path of a secret containing a client certificate that HAProxy can provide during SSL communication with the backend servers via the HAProxy crt
directive.
- The secret must use ‘tls.key’ and ‘tls.crt’ keys.
Values
- Secret path following namespace/secretname format.
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-crt: "ns1/client"
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-proto: "h2"
Enables SSL to pods.
- Enable HTTP/2 support for backend severs.
- Current implementation does not verify server certificates
Values
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/server-ssl: "true"
Sets the Host header to send to backend services.
Values
- The value of the Host header
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/set-host: "example.local"
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
Default
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/ssl-passthrough: "true"
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
Default
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"
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"
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
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
Example
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: web-ingress
namespace: default
annotations:
haproxy.org/timeout-check: 5s
Blocks all IP addresses except the whitelisted ones (annotation value).
Values
- Comma-separated list of IP addresses and/or CIDR ranges
Default
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"