This page refers to v0.10 documentation
The following command-line options are supported:
||namespace/servicename||haproxy’s 404 page|
||namespace/secretname||fake, auto generated|
||comma-separated list of keywords||
||/path/to/kubeconfig||in cluster config|
||num of files||
||uploads per second (float)||
||namespace/configmapname||no tcp svc|
||seconds as integer||
Configures the acme server and other static options used to authorize and sign certificates against a server which implements the acme protocol, version 2.
Supported acme command-line options:
--acme-check-period: interval between checks for expiring certificates. Defaults to
--acme-election-id: prefix of the ConfigMap name used to store the leader election data. Only the leader of a haproxy-ingress cluster should start the authorization and sign certificate process. Defaults to
--acme-fail-initial-duration: the starting time to wait and retry after a failed authorization and sign process. Defaults to
--acme-fail-max-duration: the time between retries of failed authorization will exponentially grow up to the max duration time. Defaults to
--acme-secret-key-name: secret name used to store the client private key. Defaults to
acme-private-key. A new key, hence a new client, is created if the secret does not exist.
--acme-server: mandatory, starts a local server used to answer challenges from the acme environment. This option should be provided on all haproxy-ingress instances to the certificate signing work properly.
--acme-token-configmap-name: the ConfigMap name used to store temporary tokens generated during the challenge. Defaults to
acme-validation-tokens. Such tokens need to be stored in k8s because any haproxy-ingress instance might receive the request from the acme environment.
--acme-track-tls-annotation: defines if ingress objects with annotation
kubernetes.io/tls-acme: "true"should also be tracked. Defaults to
- acme configuration keys doc, which has also an overview on how acme works on haproxy-ingress
--allow-cross-namespace argument, if added, will allow reading secrets from one namespace to an
ingress resource of another namespace. The default behavior is to deny such cross namespace reading.
This adds a breaking change from
annotation, where cross namespace reading were allowed without any configuration.
Changes the annotation prefix the controller should look for when parsing services and ingress
objects. The default value is
ingress.kubernetes.io if not declared, which means SSL Redirect
should be configured with the annotation name
with other prefix are ignored. This allows using HAProxy Ingress with other ingress controllers
that shares ingress and service objects without conflicting each other.
Configures the buckets of the histogram
haproxyingress_haproxy_response_time_seconds, used to compute the response time of the haproxy’s admin socket. The response time unit is in seconds.
namespace/servicename that should be used if the incoming request doesn’t match any
hostname, or the requested path doesn’t match any location within the desired hostname. An internal
404 error page is used if not declared.
namespace/secretname of the default certificate that should be used if ingress
resources using TLS configuration doesn’t provide it’s own certificate. A self-signed fake
certificate is used if not declared.
Defines a comma-separated list of HAProxy keywords that should not be used on annotation based configuration snippets. Configuration snippets added as a global config does not follow this option. Use an asterisk
* to disable configuration snippets using annotations.
Every keyword in the configuration will be compared with the first token of every configuration line, ignoring tabs and spaces. If a match occur, all the configuration snippet will be ignored and a warning is logged.
The default value is an empty string, enabling the configuration and accepting any HAProxy keyword.
Services of type ExternalName uses DNS lookup to define the target server IP list. Declare
--disable-external-name to disable a DNS based target IP list, refusing services of type ExternalName.
Defines if the ingress without the ingress.class annotation will be considered or not. If
--ignore-ingress-without-class=true then only the ingresses with the matching ingress.class annotation will be considered, ingresses with missing or different ingress.class annotation will not be considered. Default is false.
More than one ingress controller is supported per Kubernetes cluster. The
argument allow to override the class name of ingress resources that this instance of the
controller should listen to. Class names that match will be used in the HAProxy configuration.
Other classes will be ignored.
The ingress resource must use the
kubernetes.io/ingress.class annotation to name it’s
Ingress controller will try to connect to the Kubernetes master using environment variables and a
service account. This behavior can be changed using
--kubeconfig argument that reference a
kubeconfig file with master endpoint and credentials. This is a mandatory argument if the controller
is deployed outside of the Kubernetes cluster.
Everytime a configuration change need to update HAProxy, a configuration file is rewritten even if
dynamic update is used. By default the same file is recreated and the old configuration is lost.
--max-old-config-files to configure after how much files Ingress controller should start to
remove old configuration files. If
0, the default value, a single
haproxy.cfg is used.
Some infrastructure tools like
external-DNS relay in the ingress status to created access routes to the services exposed with ingress object.
apiVersion: extensions/v1beta1 kind: Ingress ... status: loadBalancer: ingress: - hostname: <ingressControllerLoadbalancerFQDN>
--publish-service=namespace/servicename to indicate the services fronting the ingress controller. The controller mirrors the address of this service’s endpoints to the load-balancer status of all Ingress objects it satisfies.
--rate-limit-update to change how much time to wait between HAProxy reloads. Note that the first
update is always immediate, the delay will only prevent two or more updates in the same time frame.
Moreover reloads will only occur if the cluster configuration has changed, otherwise no reload will
occur despite of the rate limit configuration.
This argument receives the allowed reloads per second. The default value is
0.5 which means no more
than one reload will occur within
2 seconds. The lower limit is
0.05 which means one reload within
20 seconds. The highest one is
10 which will allow ingress controller to reload HAProxy up to 10
times per second.
--reload-strategy command-line argument is used to select which reload strategy
HAProxy should use. The following options are available:
native: Uses native HAProxy reload option
reusesocket: (starting on v0.6) Uses HAProxy
-xcommand-line option to pass the listening sockets between old and new HAProxy process, allowing hitless reloads. This is the default option since v0.8.
multibinder: (deprecated on v0.6) Uses GitHub’s multibinder. This link describes how it works.
Defines if backend’s endpoints should be sorted by name. Since v0.8 the endpoints will stay in the
same order found in the Kubernetes’ endpoint objects if
--sort-backends is missing.
In v0.7 and older version, if
--sort-backends is missing, HAProxy Ingress randomly shuffle endpoints
on each reload in order to avoid requesting always the same backends just after haproxy reloads.
Sorting backends by name has a real effect only if using a distinct backend-server-naming option, because the default value builds the server name using a numeric sequence.
- backend-server-naming configuration key
Configures an endpoint with statistics, debugging and health checks. The following URIs are provided:
/healthz: a healthz URI for the haproxy-ingress
/metrics: Prometheus compatible metrics exporter
POST): starts check for missing, expiring or outdated certificates controlled by acme client. Should be issued in the leader.
/debug/pprof: profiling tools
/build: build information - controller name, version, git commit hash and repository
/stop: stops haproxy-ingress controller
--healthz-port: Defines the port number haproxy-ingress should listen to. Defaults to
--profiling: Configures if the profiling URI should be enabled. Defaults to
--stats-collect-processing-period: Defines the interval between two consecutive readings of haproxy’s
Idle_pct, used to generate
haproxy_processing_seconds_totalmetric. haproxy updates Idle_pct every
500ms, which makes that the best configuration value, and it’s also the default if not configured. Values higher than
500mswill produce a less accurate collect. Change to 0 (zero) to disable this metric.
--tcp-services-configmap argument with
namespace/configmapname resource with TCP
services and ports that HAProxy should listen to. Use the HAProxy’s port number as the key of the
The value of the ConfigMap entry is a colon separated list of the following arguments:
<namespace>/<service-name>, mandatory, is the well known notation of the service that will receive incoming connections.
<portnumber>, mandatory, is the port number the upstream service is listening - this is not related to the listening port of HAProxy.
<in-proxy>, optional, should be defined as
PROXYif HAProxy should expect requests using the PROXY protocol. Leave empty to not use PROXY protocol. This is usually used only if there is another load balancer in front of HAProxy which supports the PROXY protocol. PROXY protocol v1 and v2 are supported.
<out-proxy>, optional, should be defined as
PROXY-V2if the upstream service expect connections using the PROXY protocol v2. Use
PROXY-V1instead if the upstream service only support v1 protocol. Leave empty to connect without using the PROXY protocol.
<namespace/secret-name>, optional, used to configure SSL/TLS over the TCP connection. Secret should have
tls.keypair used on TLS handshake. Leave empty to not use ssl-offload.
<check-interval>, added in v0.10, optional and defaults to
2s, configures a TCP check interval. Declare
-(one single dash) as the time to disable it. Valid time is a number and a mandatory suffix:
<namespace/secret-name>, added in v0.10, optional, used to configure SSL/TLS client verification over the TCP connection. Secret should have
ca.crl. Leave empty to not use ssl client verification.
Optional fields can be skipped using consecutive colons.
In the example below:
... data: "3306": "default/mysql:3306::::-" "5432": "default/pgsql:5432::::1s" "8000": "system-prod/http:8000::PROXY-V1" "9900": "system-prod/admin:9900:PROXY::system-prod/tcp-9900" "9990": "system-prod/admin:9999::PROXY-V2" "9995": "system-prod/admin:9900:::system-prod/tcp-9995::system-prod/tcp-9995-ca" "9999": "system-prod/admin:9999:PROXY:PROXY"
HAProxy will listen 7 new ports:
3306will proxy to a
defaultnamespace. Check interval is disabled.
5432will proxy to a
defaultnamespace. Check interval is defined to run on every second.
8000will proxy to
8000, on the
system-prodnamespace. The upstream service will expect connections using the PROXY protocol but it only supports v1.
9900will proxy to
9900, on the
system-prodnamespace. Clients should connect using the PROXY protocol v1 or v2. Upcoming connections should be encrypted, HAProxy will ssl-offload data using crt/key provided by
9999will proxy to the same
9999port and the upstream service will expect connections using the PROXY protocol v2. The HAProxy frontend, however, will only expect PROXY protocol v1 or v2 on it’s port
9995will proxy to
9900, on the
system-prodnamespace. Upcoming connections should be encrypted, HAProxy will ssl-offload data using crt/key provided by
system-prod/tcp-9995secret. Furthermore, clients must present a certificate that will be valid under the certificate authority (and optional certificate revocation list) provded in the
Note: Check interval was added in v0.10 and defaults to
2s. All declared services has check interval enabled, except
3306 which disabled it.
Ingress resources has
spec/tls/secretName attribute to override the default X509 certificate.
As a default behavior the certificates are validated against the hostname in order to match the
SAN extension or CN (CN only up to
v0.4). Invalid certificates, ie certificates which doesn’t
match the hostname are discarded and a warning is logged into the ingress controller logging.
--verify-hostname=false argument to bypass this validation. If used, HAProxy will provide
the certificate declared in the
secretName ignoring if the certificate is or is not valid.
--wait-before-shutdown is defined, controller will wait defined time in seconds
before it starts shutting down components when SIGTERM was received. By default, it’s 0, which means
the controller starts shutting down itself right after signal was sent.
By default the proxy will be configured using all namespaces from the Kubernetes cluster. Use
--watch-namespace with the name of a namespace to watch and build the configuration of a