Skip to content

Latest commit

 

History

History
887 lines (540 loc) · 20.6 KB

controller.md

File metadata and controls

887 lines (540 loc) · 20.6 KB

HAProxy

HAProxy kubernetes ingress controller

This is autogenerated from doc.yaml. Description can be found in generator readme

Image can be run with arguments:

Argument Default
--configmap default/haproxy-configmap
--job-check-crd false
--configmap-tcp-services
--configmap-errorfiles
--configmap-patternfiles
--default-backend-service
--default-backend-port
--pprof
--prometheus
--default-ssl-certificate
--ingress.class
--empty-ingress-class false
--gateway-controller-name
--namespace-blacklist
--namespace-whitelist
--publish-service
--disable-ipv4 false
--disable-ipv6 false
--ipv4-bind-address 0.0.0.0
--ipv6-bind-address ::
--http-bind-port 8080
--https-bind-port 8443
--disable-http false
--disable-https false
--sync-period 5s
--cache-resync-period 10m
--log info
--external false
--program haproxy in PATH location
--config-dir /tmp/haproxy-ingress/etc
--runtime-dir /tmp/haproxy-ingress/run
--disable-service-external-name false
--channel-size 600
--disable-config-snippets
--disable-quic false
--quic-announce-port
--quic-bind-port
--disable-writing-only-if-reload 🚧(dev) false
--input-file 🚧(dev)
--output-file 🚧(dev)

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

Possible values:

  • The name of the ConfigMap that contains global settings. Defaults to default/haproxy-configmap

Example:

--configmap=default/my-configmap

🔼 back to top

--job-check-crd

Special mode for controller that checks if the CRDs are installed and are on latest version. Note that this will not run ingress controller, it just checks if CRDs are OK and exits

Possible values:

  • this is boolean flag

Example:

--job-check-crd

🔼 back to top

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

Possible values:

  • The name of the ConfigMap that contains mappings for TCP services

Example:

--configmap-tcp-services=default/my-tcpservices-configmap

🔼 back to top

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

Possible values:

  • The name of the ConfigMap containing errorfile content

Example:

--configmap-errorfiles=default/errorfile

🔼 back to top

--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: 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 }

ℹ️ In order to use pattern files, the target file should be prefixed with "patterns/"

Possible values:

  • The name of the ConfigMap in format NS/ConfigMapName

Example:

--configmap-patternfiles=default/acl-patterns

🔼 back to top

--default-backend-service

The name of the Kubernetes service to send requests to when no Ingress rules match. By default, it uses the builtin HTTP backend.

Possible values:

  • The name of the backend service

Example:

--default-backend-service=default/my-default-service

🔼 back to top

--default-backend-port

if default-backend-service is not used with this you can set default port used for same purpose

Possible values:

  • port that will be used for default service within controller pod

Example:

--default-backend-port=6060

🔼 back to top

--pprof

enable pprof endpoint, if default-backend-port is not used 6060 will be used

Possible values:

  • this is boolean flag

Example:

--pprof

🔼 back to top

--prometheus

enable prometheus endpoint, if default-backend-port is not used 6060 will be used

Possible values:

  • this is boolean flag

Example:

--prometheus

🔼 back to top

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

Possible values:

  • The name of the TLS Secret

Example:

--default-ssl-certificate=default/my-tls

🔼 back to top

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

Possible values:

  • The name of the ingress class

Example:

--ingress.class=haproxy

🔼 back to top

--empty-ingress-class

A flag to indicate the controller should process ingresses with empty ingress.class annotation.

Possible values:

  • No value.Being a flag you add it or not.

Example:

--empty-ingress-class

🔼 back to top

--gateway-controller-name

identifier of your controller to know which gatewayclass it will handle

Possible values:

  • The name of the controllerName in GatewayClass

Example:

--gateway-controller-name=haproxy.org/gateway-controller

🔼 back to top

--namespace-blacklist

Namespaces that the ingress controller should not monitor for changes to pods and services.

Possible values:

  • The namespace to exclude from monitoring; You can specify this argument multiple times

Example:

--namespace-blacklist=foo --namespace-blacklist=bar

🔼 back to top

--namespace-whitelist

Namespaces that the ingress controller should monitor for changes to pods and service.

Possible values:

  • The namespace to monitor; You can specify this argument multiple times

Example:

--namespace-whitelist=foo --namespace-whitelist=bar

🔼 back to top

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

Possible values:

  • Name of the ingress controller's service, e.g. default/kubernetes-ingress

Example:

--publish-service=default/kubernetes-ingress

🔼 back to top

--disable-ipv4

Disabling the IPv4 bind support.

Possible values:

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

Example:

--disable-ipv4

🔼 back to top

--disable-ipv6

Disabling the IPv6 bind support.

Possible values:

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

Example:

--disable-ipv6

🔼 back to top

--ipv4-bind-address

Customize the IPv4 binding address.

Possible values:

  • A valid IPv4 addresses. Default: 0.0.0.0

Example:

--ipv4-bind-address=10.0.0.1

🔼 back to top

--ipv6-bind-address

Customize the IPv6 binding address.

Possible values:

  • A valid IPv6 addresses. Default: ::

Example:

--ipv6-bind-address=::ffff:c0a8:5909

🔼 back to top

--http-bind-port

Customize the HTTP frontend binding port.

Possible values:

  • A valid port in the range. Default: 8080

Example:

--http-bind-port=8080

🔼 back to top

--https-bind-port

Customize the HTTPS frontend binding port.

Possible values:

  • A valid port in the range. Default: 8443

Example:

--https-bind-port=8443

🔼 back to top

--disable-http

Disabling the HTTP frontend.

Possible values:

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

Example:

--disable-http

🔼 back to top

--disable-https

Disabling the HTTPS frontend.

Possible values:

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

Example:

--disable-https

🔼 back to top

--sync-period

The interval at which the controller syncs its configuration with updated Kubernetes objects. In the case where the ingress controller is reloading too frequently, a higher value may be required. Note, if using helm charts you must also adjust the startupProbe's initialDelaySeconds value. Its value must be higher than the --sync-period value.

Possible values:

  • An integer with unit of time (1s = 1 second, 1m = 1 minute, 1h = 1 hour); Defaults to 5s

Example:

--sync-period=10s

🔼 back to top

--cache-resync-period

Sets the default re-synchronization period at which the controller will re-apply the desired state.

Possible values:

  • The duration in time.Duration format; Defaults to 10m (10 minutes).

Example:

--cache-resync-period=30m

🔼 back to top

--log

The level of logging to perform; Defaults to info

Possible values:

  • error
  • warning
  • info (default)
  • debug
  • trace

Example:

--log=debug

🔼 back to top

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

Possible values:

  • Boolean value.

Example:

--external

🔼 back to top

--program

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

⚠️ this is only available in external mode

Possible values:

  • Path to HAProxy binary

Example:

--external --program=/usr/bin/haproxy

🔼 back to top

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

⚠️ this is only available in external mode

Possible values:

  • Path to configuration directory

Example:

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

🔼 back to top

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

⚠️ this is only available in external mode

Possible values:

  • Path to runtime directory

Example:

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

🔼 back to top

--disable-service-external-name

Disable forwarding to ExternalName Services due to CVE-2021-25740

Possible values:

  • Boolean value, just need to declare the flag to disable forwarding to ExternalName Services.

Example:

--disable-service-external-name

🔼 back to top

--channel-size

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.

Possible values:

  • Size of channels used for k8s resources events with regards to ingresses, etc.

Example:

--channel-size=10000

🔼 back to top

--disable-config-snippets

Allow to disable one or several of the following config snippets: backend, frontend, global.

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

Example:

--disable-config-snippets=backend,frontend

🔼 back to top

--disable-quic

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.

Possible values:

Example:

args:
  - --disable-quic

🔼 back to top

--quic-announce-port

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

Possible values:

Example:

args:
  - --quic-announce-port=10443

🔼 back to top

--quic-bind-port

sets the binding port for quic in HTTPS frontend.

Possible values:

Example:

args:
  - --quic-bind-port=4443

🔼 back to top

--disable-writing-only-if-reload

🚧 this is only available from next version, currently available in dev build

Disable the delayed writing of files to disk ONLY in case of haproxy reload (= write files to disk even if no reload)

Possible values:

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

Example:

--disable-writing-only-if-reload

🔼 back to top

--input-file

🚧 this is only available from next version, currently available in dev build

This is the path to a manifest (yaml) of a v1 version to the CRDs to convert to v3. Goes with --output-file for the result

Possible values:

  • Path a to a CRD manifest you want to convert to the latest version

Example:

--input-file=/home/xxx/convert/v1/global-full.yaml

🔼 back to top

--output-file

🚧 this is only available from next version, currently available in dev build

This is the path to a manifest (yaml) where to write to the converted v3 CRD from a v1 manifest (see --input-file). Goes with --input-file

Possible values:

  • Path a to a CRD manifest where the converted v3 CRDs will be written

Example:

--output-file=/home/xxx/convert/v3/global-full.yaml

🔼 back to top