HAProxy Enterprise Documentation 1.6

Auxiliary Config File

For the most part, the ingress controller will handle the underlying HAProxy configuration file and you only need to set annotations on your Ingress, Service and ConfigMap resources. However, it’s still possible to write raw HAProxy configuration directives for features not yet covered by annotations.

One option is to use the following annotations:

  • backend-config-snippet
  • frontend-config-snippet
  • global-config-snippet
  • stats-config-snippet

You can also provide an auxiliary configuration file that defines entirely new config sections, such as to define cache, mailers, or ring sections. This file will be loaded when the ingress controller starts up.

You can thus:

  • Configure anything not supported by Ingress Controller annotations.
  • Migrate a legacy HAProxy Enterprise configuration to the HAProxy Enterprise Kubernetes Ingress Controller.

Primary and auxiliary configuration files

Here are the differences between the two types of configuration files:

Filename Description Controlled by
hapee-lb.cfg Reflects the state of pods and services in your Kubernetes cluster. HAProxy Kubernetes Ingress controller
hapee-lb-aux.cfg Supports additional HAProxy Enterprise directives. Kubernetes administrator

Deploy the Ingress controller

  1. Add the HAProxy configuration directives that you want to use to a new .cfg file. Below, we define a cache section in a file named haproxy-auxiliary.cfg:

    cache mycache
      total-max-size 4095
      max-object-size 10000
      max-age 30
    
  2. Load the file into your Kubernetes cluster as a ConfigMap resource.

    $ kubectl create configmap haproxy-auxiliary-configmap --from-file haproxy-auxiliary.cfg
    • A ConfigMap is an API object for storing non-confidential information in key-value pairs that makes your applications easily portable.
    • Kubernetes automatically updates the mounted volume when you update the ConfigMap.
  3. Deploy the Ingress controller again with the ConfigMap attached as a ConfigMap volume. Below we show an example using Helm.

    a. Create a file named values.yaml that contains the following:

    controller:
      extraVolumes:
      - name: haproxy-auxiliary-volume
        configMap:
          name: haproxy-auxiliary-configmap
      extraVolumeMounts:
      - name: haproxy-auxiliary-volume
        mountPath: /etc/haproxy/haproxy-aux.cfg
        subPath: haproxy-auxiliary.cfg
    • Note: The mountPath field must be set to /etc/haproxy/haproxy-aux.cfg for both the Community and Enterprise versions.

    b. Uninstall the Helm chart if you installed it previously.

    $ helm uninstall kubernetes-ingress

    c. Install the Helm chart, referencing the values.yaml file with the -f flag.

    $ helm install kubernetes-ingress haproxytech/kubernetes-ingress -f values.yaml
  4. To make use of the cache section, you could add a backend-config-snippet annotation to a Service resource:

    apiVersion: v1
    kind: Service
    metadata:
      labels:
        run: api
      name: api
      annotations:
        haproxy.org/backend-config-snippet: |
          http-request cache-use mycache
          http-response cache-store mycache

See also

Update the configuration file

Follow these steps to update the auxiliary configuration file later.

  1. Call kubectl edit to edit the ConfigMap.

    $ kubectl edit configmap haproxy-auxiliary-configmap
  2. The file opens in your text editor. Make changes to the file and then save and close it. The Ingress controller will detect the change and reload the file.


Next up

Logging