Configuration reference
Startup arguments
You can customize the HAProxy Kubernetes Ingress Controller by passing these arguments at startup. These affect the lifetime of the process.
–configmap Jump to heading
Available since
version 1.4
Sets the ConfigMap object that defines global settings for the ingress controller. An empty ConfigMap is deployed by default and you can see its name by calling kubectl get configmaps
. You can either override the default ConfigMap with your own object that uses the same name, or you can set this argument to point to a different ConfigMap. See the ConfigMap Options to learn which values you can store in the ConfigMap.
Values
- The name of the ConfigMap that contains global settings. Defaults to
default/haproxy-configmap
Default
- default/haproxy-configmap
Example
bash
haproxy-ingress-controller --configmap=default/my-configmap
bash
haproxy-ingress-controller --configmap=default/my-configmap
–configmap-tcp-services Jump to heading
Available since
version 1.4
Sets the ConfigMap that contains mappings for TCP services to proxy through the ingress controller. This ConfigMap contains mappings like this:
yaml
apiVersion: v1kind: ConfigMapmetadata:name: tcpnamespace: haproxy-controllerdata:3306: # Port where the frontend is going to listen to.mysql-ns/mysql:3306 # Kubernetes service in the format NS/ServiceName:ServicePort389:ldap-ns/ldap:389:ssl # ssl option will enable ssl offloading for target service.6379:redis-ns/redis:6379
yaml
apiVersion: v1kind: ConfigMapmetadata:name: tcpnamespace: haproxy-controllerdata:3306: # Port where the frontend is going to listen to.mysql-ns/mysql:3306 # Kubernetes service in the format NS/ServiceName:ServicePort389:ldap-ns/ldap:389:ssl # ssl option will enable ssl offloading for target service.6379:redis-ns/redis:6379
- Ports of TCP services should be exposed on the controller’s Kubernetes service
Values
- The name of the ConfigMap that contains mappings for TCP services
Default
- No default value
Example
bash
haproxy-ingress-controller --configmap-tcp-services=default/my-tcpservices-configmap
bash
haproxy-ingress-controller --configmap-tcp-services=default/my-tcpservices-configmap
–configmap-errorfiles Jump to heading
Available since
version 1.5
Sets the ConfigMap object that defines contents to serve instead of HAProxy errors. As explained in the haproxy documentation it is important to understand that errorfile content is not meant to rewrite errors returned by the server, but rather errors detected and returned by HAProxy. In the following example, instead of HAProxy returning a 503 error, it will return the corresponding content in the ConfigMap:
yaml
apiVersion: v1kind: ConfigMapmetadata:name: errorfilenamespace: haproxy-controllerdata:503: |-HTTP/1.0 503 Service UnavailableCache-Control: no-cacheConnection: closeContent-Type: text/html<html><body><h1>Oops, that's embarrassing!</h1>There are no servers available to handle your request.</body></html>
yaml
apiVersion: v1kind: ConfigMapmetadata:name: errorfilenamespace: haproxy-controllerdata:503: |-HTTP/1.0 503 Service UnavailableCache-Control: no-cacheConnection: closeContent-Type: text/html<html><body><h1>Oops, that's embarrassing!</h1>There are no servers available to handle your request.</body></html>
Values
- The name of the ConfigMap containing errorfile content
Default
- No default value
Example
bash
haproxy-ingress-controller --configmap-errorfiles=default/errorfile
bash
haproxy-ingress-controller --configmap-errorfiles=default/errorfile
–configmap-patternfiles Jump to heading
Available since
version 1.8
Sets the ConfigMap object that defines pattern files to be used in HAProxy configuration. Controller will create corresponding files and update them when ConfigMap is updated. Pattern files are particularly useful for HAProxy ACLs where we can load patterns from file. The following example will load two pattern files:
% cat /tmp/ips127.0.0.110.0.0.0/81.2.3.4/24
% cat /tmp/ips127.0.0.110.0.0.0/81.2.3.4/24
% cat /tmp/namesfoobartotobidule
% cat /tmp/namesfoobartotobidule
kubectl create -n default configmap acl-patterns --from-file=/tmp/ips --from-file=/tmp/names
kubectl create -n default configmap acl-patterns --from-file=/tmp/ips --from-file=/tmp/names
The resulting configmap will be:
yaml
apiVersion: v1kind: ConfigMapmetadata:name: acls-patternsnamespace: haproxy-controllerdata:ips: |127.0.0.110.0.0.0/81.2.3.4/24names: |foobartotobidule
yaml
apiVersion: v1kind: ConfigMapmetadata:name: acls-patternsnamespace: haproxy-controllerdata:ips: |127.0.0.110.0.0.0/81.2.3.4/24names: |foobartotobidule
Pattern files are useful in config-snippets. Example:
backend-config-snippet: |http-request deny if !{ src -f patterns/ips }
backend-config-snippet: |http-request deny if !{ src -f patterns/ips }
- In order to use pattern files, the target file should be prefixed with “patterns/”
Values
- The name of the ConfigMap in format NS/ConfigMapName
Default
- No default value
Example
bash
haproxy-ingress-controller --configmap-patternfiles=default/acl-patterns
bash
haproxy-ingress-controller --configmap-patternfiles=default/acl-patterns
–default-backend-service Jump to heading
Available since
version 1.4
The name of the Kubernetes service to send requests to when no Ingress rules match. By default, it uses the builtin HTTP backend.
Values
- The name of the backend service
Default
- No default value
Example
bash
haproxy-ingress-controller --default-backend-service=default/my-default-service
bash
haproxy-ingress-controller --default-backend-service=default/my-default-service
–default-backend-port Jump to heading
Available since
version 1.8
if default-backend-service is not used with this you can set default port used for same purpose
Values
- port that will be used for default service within controller pod
Default
- No default value
Example
bash
haproxy-ingress-controller --default-backend-port=6060
bash
haproxy-ingress-controller --default-backend-port=6060
–pprof Jump to heading
Available since
version 1.4
enable pprof endpoint, if default-backend-port is not used 6060 will be used
Values
- this is boolean flag
Default
- No default value
Example
bash
haproxy-ingress-controller --pprof
bash
haproxy-ingress-controller --pprof
–prometheus Jump to heading
Available since
version 1.8
enable prometheus endpoint, if default-backend-port is not used 6060 will be used
Values
- this is boolean flag
Default
- No default value
Example
bash
haproxy-ingress-controller --prometheus
bash
haproxy-ingress-controller --prometheus
–default-ssl-certificate Jump to heading
Available since
version 1.4
The name of a TLS Secret that contains the certificate to use for SSL/TLS traffic. This can be overridden with the ssl-certificate
setting.
Values
- The name of the TLS Secret
Default
- No default value
Example
bash
haproxy-ingress-controller --default-ssl-certificate=default/my-tls
bash
haproxy-ingress-controller --default-ssl-certificate=default/my-tls
–ingress.class Jump to heading
Available since
version 1.4
A name to assign to the ingress controller so that Ingress objects can target it apart from other running ingress controllers.
- 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.
Values
- The name of the ingress class
Default
- No default value
Example
bash
haproxy-ingress-controller --ingress.class=haproxy
bash
haproxy-ingress-controller --ingress.class=haproxy
Helm example
helm install intranet haproxytech/kubernetes-ingress \--set controller.ingressClass=haproxy
helm install intranet haproxytech/kubernetes-ingress \--set controller.ingressClass=haproxy
–empty-ingress-class Jump to heading
Available since
version 1.6
A flag to indicate the controller should process ingresses with empty ingress.class annotation.
Values
- No value.Being a flag you add it or not.
Default
- No default value
Example
bash
haproxy-ingress-controller --empty-ingress-class
bash
haproxy-ingress-controller --empty-ingress-class
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--empty-ingress-class}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--empty-ingress-class}"
–gateway-controller-name Jump to heading
Available since
version 1.10
identifier of your controller to know which gatewayclass it will handle
Values
- The name of the controllerName in GatewayClass
Default
- No default value
Example
bash
haproxy-ingress-controller --gateway-controller-name=haproxy.org/gateway-controller
bash
haproxy-ingress-controller --gateway-controller-name=haproxy.org/gateway-controller
Helm example
helm install intranet haproxytech/kubernetes-ingress \--set controller.gatewayControllerName=haproxy.org/gateway-controller
helm install intranet haproxytech/kubernetes-ingress \--set controller.gatewayControllerName=haproxy.org/gateway-controller
–namespace-blacklist Jump to heading
Available since
version 1.4
Namespaces that the ingress controller should not monitor for changes to pods and services.
Values
- The namespace to exclude from monitoring; You can specify this argument multiple times
Default
- No default value
Example
bash
haproxy-ingress-controller --namespace-blacklist=foo --namespace-blacklist=bar
bash
haproxy-ingress-controller --namespace-blacklist=foo --namespace-blacklist=bar
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--namespace-blacklist=foo}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--namespace-blacklist=foo}"
–namespace-whitelist Jump to heading
Available since
version 1.4
Namespaces that the ingress controller should monitor for changes to pods and service.
Values
- The namespace to monitor; You can specify this argument multiple times
Default
- No default value
Example
bash
haproxy-ingress-controller --namespace-whitelist=foo --namespace-whitelist=bar
bash
haproxy-ingress-controller --namespace-whitelist=foo --namespace-whitelist=bar
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--namespace-whitelist=foo}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--namespace-whitelist=foo}"
–publish-service Jump to heading
Available since
version 1.4
Copies the ingress controller’s IP address to the ‘Address’ field in all Ingress objects that the controller manages. This is useful for tools like external-dns, which use this information to create DNS records.
Values
- Name of the ingress controller’s service, e.g. default/kubernetes-ingress
Default
- No default value
Example
bash
haproxy-ingress-controller --publish-service=default/kubernetes-ingress
bash
haproxy-ingress-controller --publish-service=default/kubernetes-ingress
–disable-ipv4 Jump to heading
Available since
version 1.5
Disabling the IPv4 bind support.
Values
- Boolean value, just need to declare the flag to disable the IPv4.
Default
- No default value
Example
bash
haproxy-ingress-controller --disable-ipv4
bash
haproxy-ingress-controller --disable-ipv4
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-ipv4}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-ipv4}"
–disable-ipv6 Jump to heading
Available since
version 1.5
Disabling the IPv6 bind support.
Values
- Boolean value, just need to declare the flag to disable the IPv6.
Default
- No default value
Example
bash
haproxy-ingress-controller --disable-ipv6
bash
haproxy-ingress-controller --disable-ipv6
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-ipv6}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-ipv6}"
–ipv4-bind-address Jump to heading
Available since
version 1.5
Customize the IPv4 binding address.
Values
- A valid IPv4 addresses. Default: 0.0.0.0
Default
- 0.0.0.0
Example
bash
haproxy-ingress-controller --ipv4-bind-address=10.0.0.1
bash
haproxy-ingress-controller --ipv4-bind-address=10.0.0.1
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--ipv4-bind-address=10.0.0.1}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--ipv4-bind-address=10.0.0.1}"
–ipv6-bind-address Jump to heading
Available since
version 1.5
Customize the IPv6 binding address.
Values
- A valid IPv6 addresses. Default: ::
Default
- ::
Example
bash
haproxy-ingress-controller --ipv6-bind-address=::ffff:c0a8:5909
bash
haproxy-ingress-controller --ipv6-bind-address=::ffff:c0a8:5909
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--ipv6-bind-address=::ffff:c0a8:5909}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--ipv6-bind-address=::ffff:c0a8:5909}"
–http-bind-port Jump to heading
Available since
version 1.5
Customize the HTTP frontend binding port.
Values
- A valid port in the range. Default: 80
Default
- 80
Example
bash
haproxy-ingress-controller --http-bind-port=8080
bash
haproxy-ingress-controller --http-bind-port=8080
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--http-bind-port=8080}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--http-bind-port=8080}"
–https-bind-port Jump to heading
Available since
version 1.5
Customize the HTTPS frontend binding port.
Values
- A valid port in the range. Default: 443
Default
- 443
Example
bash
haproxy-ingress-controller --http-bind-port=8443
bash
haproxy-ingress-controller --http-bind-port=8443
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--http-bind-port=8443}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--http-bind-port=8443}"
–disable-http Jump to heading
Available since
version 1.5
Disabling the HTTP frontend.
Values
- Boolean value, just need to declare the flag to disable the HTTP frontend.
Default
- No default value
Example
bash
haproxy-ingress-controller --disable-http
bash
haproxy-ingress-controller --disable-http
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-http}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-http}"
–disable-https Jump to heading
Available since
version 1.5
Disabling the HTTPS frontend.
Values
- Boolean value, just need to declare the flag to disable the HTTPS frontend.
Default
- No default value
Example
bash
haproxy-ingress-controller --disable-https
bash
haproxy-ingress-controller --disable-https
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-https}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-https}"
–sync-period Jump to heading
Available since
version 1.4
The interval at which the controller syncs its configuration with updated Kubernetes objects.
Values
- An integer with unit of time (1s = 1 second, 1m = 1 minute, 1h = 1 hour); Defaults to 5s
Default
- 5s
Example
bash
haproxy-ingress-controller --sync-period=10s
bash
haproxy-ingress-controller --sync-period=10s
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--sync-period=10s}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--sync-period=10s}"
–cache-resync-period Jump to heading
Available since
version 1.5
Sets the default re-synchronization period at which the controller will re-apply the desired state.
Values
- The duration in
time.Duration
format; Defaults to 10m (10 minutes).
Default
- 10m
Example
bash
haproxy-ingress-controller --cache-resync-period=30m
bash
haproxy-ingress-controller --cache-resync-period=30m
–log Jump to heading
Available since
version 1.4
The level of logging to perform; Defaults to info
Values
- error
- warning
- info (default)
- debug
- trace
Default
- info
Example
bash
haproxy-ingress-controller --log=debug
bash
haproxy-ingress-controller --log=debug
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set controller.logging.level=debug
helm install haproxy haproxytech/kubernetes-ingress \--set controller.logging.level=debug
–external Jump to heading
Available since
version 1.5
Run as external Ingress Controller (out of kubernetes cluster). This can be done by cloning Ingress Controller project and building Controller with go build
. Or using export GO111MODULE=on; go get github.com/haproxytech/kubernetes-ingress
. More information about external mode can be found in this announcement blog post
Values
- Boolean value.
Default
- No default value
Example
bash
haproxy-ingress-controller --external
bash
haproxy-ingress-controller --external
–program Jump to heading
Available since
version 1.5
Path to HAProxy binary to use when running controller in external mode.
Values
- Path to HAProxy binary
Default
- haproxy in PATH location
Example
bash
haproxy-ingress-controller --external --program=/usr/bin/haproxy
bash
haproxy-ingress-controller --external --program=/usr/bin/haproxy
–config-dir Jump to heading
Available since
version 1.5
Path to HAProxy configuration directory when running controller in external mode. Configuration directory is where resources like configuration file, certificates, haproxy map files, are located.
Values
- Path to configuration directory
Default
- /tmp/haproxy-ingress/etc
Example
bash
haproxy-ingress-controller --external --config-dir=/haproxy-ingress/etc
bash
haproxy-ingress-controller --external --config-dir=/haproxy-ingress/etc
–runtime-dir Jump to heading
Available since
version 1.5
Path to HAProxy runtime directory when running controller in external mode. Runtime directory is where resources like PID file, runtime socket, etc are located.
Values
- Path to runtime directory
Default
- /tmp/haproxy-ingress/run
Example
bash
haproxy-ingress-controller --external --runtime-dir=/haproxy-ingress/run
bash
haproxy-ingress-controller --external --runtime-dir=/haproxy-ingress/run
–disable-service-external-name Jump to heading
Available since
version 1.6
Disable forwarding to ExternalName Services due to CVE-2021-25740
Values
- Boolean value, just need to declare the flag to disable forwarding to ExternalName Services.
Default
- false
Example
bash
haproxy-ingress-controller --disable-service-external-name
bash
haproxy-ingress-controller --disable-service-external-name
Helm example
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-service-external-name}"
helm install haproxy haproxytech/kubernetes-ingress \--set-string "controller.extraArgs={--disable-service-external-name}"
–channel-size Jump to heading
Available since
version 1.7
Sets the size of controller buffers used to receive and send k8s events. This parameter is a cursor to adapt to the number of resources inside your clusters and that generate a lot of events. Rule of thumb: the more resources the higher the value.
Values
- Size of channels used for k8s resources events with regards to ingresses, etc.
Default
- 600
Example
bash
haproxy-ingress-controller --channel-size=10000
bash
haproxy-ingress-controller --channel-size=10000
–disable-config-snippets Jump to heading
Available since
version 1.11
Allow to disable one or several of the following config snippets: backend, frontend, global.
Values
- Comma separated list of the kind of config snippets to disable. Possible values in the list are
- backend,frontend,global,all
- If ‘all’ is present then all (backend, frontend, global) config snippets are disabled.
Default
- No default value
Example
bash
haproxy-ingress-controller --disable-config-snippets=backend,frontend
bash
haproxy-ingress-controller --disable-config-snippets=backend,frontend
If this page was useful, please, Leave the feedback.