Ingress tutorials

Add an auxiliary configuration

Available since

version 1.6

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 for setting small amounts of raw configuration:

  • 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 Jump to heading

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

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

Deploy the Ingress controller Jump to heading

  1. Create a file named haproxy-auxiliary.cfg.

  2. Add the HAProxy configuration directives that you want to use to the file.

    For example, let’s add an entirely new section to the file. We’ll use the cache section:

    haproxy-auxiliary.cfg
    haproxy
    cache mycache
    total-max-size 4095
    max-object-size 10000
    max-age 30
    haproxy-auxiliary.cfg
    haproxy
    cache mycache
    total-max-size 4095
    max-object-size 10000
    max-age 30

    Be sure to add a blank line at the end of the file, otherwise HAProxy will get the error Missing LF on last line, file might have been truncated and fail to load the file.

  3. Load the file into your Kubernetes cluster as a ConfigMap resource.

    nix
    kubectl create configmap haproxy-auxiliary-configmap --from-file haproxy-auxiliary.cfg --namespace haproxy-controller
    nix
    kubectl create configmap haproxy-auxiliary-configmap --from-file haproxy-auxiliary.cfg --namespace haproxy-controller

    In this example:

    • 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.
  4. 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:

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

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

    nix
    helm uninstall haproxy-kubernetes-ingress --namespace haproxy-controller
    nix
    helm uninstall haproxy-kubernetes-ingress --namespace haproxy-controller

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

    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
    -f values.yaml \
    --namespace haproxy-controller
    nix
    helm install haproxy-kubernetes-ingress haproxytech/kubernetes-ingress \
    -f values.yaml \
    --namespace haproxy-controller
  5. To make use of the cache section, you could add a backend-config-snippet annotation to a Service resource:

    example-service.yaml
    yaml
    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
    example-service.yaml
    yaml
    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

Update the configuration file Jump to heading

Follow these steps to update the auxiliary configuration file later.

  1. Call kubectl edit to edit the ConfigMap.

    nix
    kubectl edit configmap haproxy-auxiliary-configmap --namespace haproxy-controller
    nix
    kubectl edit configmap haproxy-auxiliary-configmap --namespace haproxy-controller
  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.

See also Jump to heading

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