Configuration reference

Startup arguments

On this page

You can customize the HAProxy Kubernetes Ingress Controller by passing these arguments at startup. These affect the lifetime of the process.

–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

nix
haproxy-ingress-controller --cache-resync-period=30m
nix
haproxy-ingress-controller --cache-resync-period=30m

–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

nix
haproxy-ingress-controller --channel-size=10000
nix
haproxy-ingress-controller --channel-size=10000

–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

nix
haproxy-ingress-controller --external --config-dir=/haproxy-ingress/etc
nix
haproxy-ingress-controller --external --config-dir=/haproxy-ingress/etc

–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

nix
haproxy-ingress-controller --configmap=default/my-configmap
nix
haproxy-ingress-controller --configmap=default/my-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: v1
kind: ConfigMap
metadata:
  name: errorfile
  namespace: haproxy-controller
data:
  503: |-
    HTTP/1.0 503 Service Unavailable
    Cache-Control: no-cache
    Connection: close
    Content-Type: text/html
    <html><body><h1>Oops, that's embarrassing!</h1>
    There are no servers available to handle your request.
    </body></html>
yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: errorfile
  namespace: haproxy-controller
data:
  503: |-
    HTTP/1.0 503 Service Unavailable
    Cache-Control: no-cache
    Connection: close
    Content-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

nix
haproxy-ingress-controller --configmap-errorfiles=default/errorfile
nix
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/ips
127.0.0.1
10.0.0.0/8
1.2.3.4/24
% cat /tmp/ips
127.0.0.1
10.0.0.0/8
1.2.3.4/24
% cat /tmp/names
foo
bar
toto
bidule
% cat /tmp/names
foo
bar
toto
bidule
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: v1
kind: ConfigMap
metadata:
  name: acls-patterns
  namespace: haproxy-controller
data:
  ips: |
    127.0.0.1
    10.0.0.0/8
    1.2.3.4/24
  names: |
    foo
    bar
    toto
    bidule
yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: acls-patterns
  namespace: haproxy-controller
data:
  ips: |
    127.0.0.1
    10.0.0.0/8
    1.2.3.4/24
  names: |
    foo
    bar
    toto
    bidule

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

nix
haproxy-ingress-controller --configmap-patternfiles=default/acl-patterns
nix
haproxy-ingress-controller --configmap-patternfiles=default/acl-patterns

–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: v1
kind: ConfigMap
metadata:
  name: tcp
  namespace: haproxy-controller
data:
  3306:                    # Port where the frontend is going to listen to.
    mysql-ns/mysql:3306    # Kubernetes service in the format NS/ServiceName:ServicePort
  389:
    ldap-ns/ldap:389:ssl   # ssl option will enable ssl offloading for target service.
  6379:
    redis-ns/redis:6379
yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: tcp
  namespace: haproxy-controller
data:
  3306:                    # Port where the frontend is going to listen to.
    mysql-ns/mysql:3306    # Kubernetes service in the format NS/ServiceName:ServicePort
  389:
    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

nix
haproxy-ingress-controller --configmap-tcp-services=default/my-tcpservices-configmap
nix
haproxy-ingress-controller --configmap-tcp-services=default/my-tcpservices-configmap

–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

nix
haproxy-ingress-controller --default-backend-port=6060
nix
haproxy-ingress-controller --default-backend-port=6060

–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

nix
haproxy-ingress-controller --default-backend-service=default/my-default-service
nix
haproxy-ingress-controller --default-backend-service=default/my-default-service

–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

nix
haproxy-ingress-controller --default-ssl-certificate=default/my-tls
nix
haproxy-ingress-controller --default-ssl-certificate=default/my-tls

–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

nix
haproxy-ingress-controller --disable-config-snippets=backend,frontend
nix
haproxy-ingress-controller --disable-config-snippets=backend,frontend

–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

nix
haproxy-ingress-controller --disable-http
nix
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

nix
haproxy-ingress-controller --disable-https
nix
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}"

–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

nix
haproxy-ingress-controller --disable-ipv4
nix
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

nix
haproxy-ingress-controller --disable-ipv6
nix
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}"

–disable-quic Jump to heading

Available since

version 1.11

option to disable the quic binding used by default if a certificate is provided throug ssl-certificate annotation. Please be aware that the quic implementation is activated with the “limited-quic” global option. Please refer to the documentation for details.

Values

Default

  • No default value

Example

nix
haproxy-ingress-controller args:
  - --disable-quic
nix
haproxy-ingress-controller args:
  - --disable-quic

–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

nix
haproxy-ingress-controller --disable-service-external-name
nix
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}"

–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

nix
haproxy-ingress-controller --empty-ingress-class
nix
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}"

–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.

Values

  • Boolean value.

Default

  • No default value

Example

nix
haproxy-ingress-controller --external
nix
haproxy-ingress-controller --external

–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

nix
haproxy-ingress-controller --gateway-controller-name=haproxy.org/gateway-controller
nix
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

–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: 8080

Default

  • 8080

Example

nix
haproxy-ingress-controller --http-bind-port=8080
nix
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: 8443

Default

  • 8443

Example

nix
haproxy-ingress-controller --http-bind-port=8443
nix
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}"

–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

nix
haproxy-ingress-controller --ingress.class=haproxy
nix
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

–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

nix
haproxy-ingress-controller --ipv4-bind-address=10.0.0.1
nix
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

nix
haproxy-ingress-controller --ipv6-bind-address=::ffff:c0a8:5909
nix
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}"

–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

nix
haproxy-ingress-controller --log=debug
nix
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

–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

nix
haproxy-ingress-controller --namespace-blacklist=foo --namespace-blacklist=bar
nix
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

nix
haproxy-ingress-controller --namespace-whitelist=foo --namespace-whitelist=bar
nix
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}"

–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

nix
haproxy-ingress-controller --pprof
nix
haproxy-ingress-controller --pprof

–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

nix
haproxy-ingress-controller --external --program=/usr/bin/haproxy
nix
haproxy-ingress-controller --external --program=/usr/bin/haproxy

–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

nix
haproxy-ingress-controller --prometheus
nix
haproxy-ingress-controller --prometheus

–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

nix
haproxy-ingress-controller --publish-service=default/kubernetes-ingress
nix
haproxy-ingress-controller --publish-service=default/kubernetes-ingress

–quic-announce-port Jump to heading

Available since

version 1.11

adjust the port in the alt-svc header to redirect to the exposed port in case it differs from the quic binding port.

Values

Default

  • No default value

Example

nix
haproxy-ingress-controller args:
  - --quic-announce-port=10443
nix
haproxy-ingress-controller args:
  - --quic-announce-port=10443

–quic-bind-port Jump to heading

Available since

version 1.11

sets the binding port for quic in HTTPS frontend.

Values

Default

  • No default value

Example

nix
haproxy-ingress-controller args:
  - --quic-bind-port=4443        
nix
haproxy-ingress-controller args:
  - --quic-bind-port=4443

–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

nix
haproxy-ingress-controller --external --runtime-dir=/haproxy-ingress/run
nix
haproxy-ingress-controller --external --runtime-dir=/haproxy-ingress/run

–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

nix
haproxy-ingress-controller --sync-period=10s
nix
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}"

Do you have any suggestions on how we can improve the content of this page?

Previous page Service annotations Next page Administration
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences