HAProxy Enterprise Documentation 1.7

Controllers Arguments

You can customize the ingress controller by passing these arguments at startup.


--configmap

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

--configmap-tcp-services

Sets the ConfigMap that contains mappings for TCP services to proxy through the ingress controller. This ConfigMap contains mappings like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tcp
  namespace: default
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

--configmap-errorfiles

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:

apiVersion: v1
kind: ConfigMap
metadata:
  name: errorfile
  namespace: default
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

--configmap-patternfiles

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/names
foo
bar
toto
bidule
kubectl create -n default configmap acl-patterns --from-file=/tmp/ips --from-file=/tmp/names

The resulting configmap will be:

apiVersion: v1
kind: ConfigMap
metadata:
  name: acls-patterns
  namespace: default
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 }
  • 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-backend-service

The name of the Kubernetes service to send requests to when no Ingress rules match.

Values

  • The name of the backend service

--default-ssl-certificate

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

--ingress.class

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

Helm

helm install intranet haproxytech/kubernetes-ingress \
  --set controller.ingressClass=haproxy

--empty-ingress-class

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.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--empty-ingress-class}"

--namespace-blacklist

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

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--namespace-blacklist=foo}"

--namespace-whitelist

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

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--namespace-whitelist=foo}"

--publish-service

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

--disable-ipv4

Disabling the IPv4 bind support.

Values

  • Boolean value, just need to declare the flag to disable the IPv4.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--disable-ipv4}"

--disable-ipv6

Disabling the IPv6 bind support.

Values

  • Boolean value, just need to declare the flag to disable the IPv6.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--disable-ipv6}"

--ipv4-bind-address

Customize the IPv4 binding address.

Values

  • A valid IPv4 addresses. Default: 0.0.0.0

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--ipv4-bind-address=10.0.0.1}"

--ipv6-bind-address

Customize the IPv6 binding address.

Values

  • A valid IPv6 addresses. Default: ::

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--ipv6-bind-address=::ffff:c0a8:5909}"

--http-bind-port

Customize the HTTP frontend binding port.

Values

  • A valid port in the range. Default: 80

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--http-bind-port=8080}"

--https-bind-port

Customize the HTTPS frontend binding port.

Values

  • A valid port in the range. Default: 443

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--http-bind-port=8443}"

--disable-http

Disabling the HTTP frontend.

Values

  • Boolean value, just need to declare the flag to disable the HTTP frontend.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--disable-http}"

--disable-https

Disabling the HTTPS frontend.

Values

  • Boolean value, just need to declare the flag to disable the HTTPS frontend.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--disable-https}"

--sync-period

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

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--sync-period=10s}"

--cache-resync-period

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

--log

The level of logging to perform; Defaults to info

Values

  • error

  • warning

  • info (default)

  • debug

  • trace

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set controller.logging.level=debug

--external

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.

--program

Path to HAProxy binary to use when running controller in external mode.

Values

  • Path to HAProxy binary

--config-dir

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

--runtime-dir

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

--disable-service-external-name

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.

Helm

helm install haproxy haproxytech/kubernetes-ingress \
  --set-string "controller.extraArgs={--disable-service-external-name}"

Next up

ConfigMap Options