Custom Resources With HAProxy Kubernetes Ingress Controller

HAProxy Kubernetes Ingress Controller provides custom resources named Backend, Defaults, and Global that let you manage ingress controller settings more efficiently. To start using them right away, check the documentation for steps and examples. In this blog post, you’ll learn why custom resources are such a powerful feature and see tips for getting the most out of them.

Custom Resources Explained

Every Kubernetes cluster comes with a set of standard resource types like pods, services, and deployments. If you wanted to see a list of them, you could connect to your Kubernetes cluster and run the command kubectl api-resources:

$ kubectl api-resources
bindings v1 true Binding
componentstatuses cs v1 false ComponentStatus
configmaps cm v1 true ConfigMap
endpoints ep v1 true Endpoints
events ev v1 true Event
limitranges limits v1 true LimitRange
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolumeClaim

Kubernetes can be extended with new types, called custom resources. To install the HAProxy Kubernetes Ingress Controller custom resources, you would call kubectl apply with the URL of each resource’s definition:

$ kubectl apply -f
$ kubectl apply -f
$ kubectl apply -f

Afterward, you’ll see them as new entries in the list of resource types:

$ kubectl api-resources
backends true Backend
defaults true Defaults
globals true Global

Or to list only resources that are custom, call kubectl get crd:

$ kubectl get crd
NAME CREATED AT 2022-06-01T16:09:57Z 2022-06-01T16:56:57Z 2022-06-01T16:56:57Z

With the resource definitions added to your cluster, you can then create instances of those types. For example, to create a new Global resource, you would first create a YAML file for it:


apiVersion: ""
kind: Global
name: example-global
namespace: default
maxconn: 60000

Then apply it with kubectl:

$ kubectl apply -f example-global.yaml

The Global resource controls process-level settings for the ingress controller, such as the maximum number of concurrent connections it will accept, here set to 60,000.

Custom resources can be listed, described, applied and deleted using Kubernetes tools like kubectl, just like standard resources. Below, we list Global resources and then describe, or in other words display the attributes of, the example-global Global resource:

$ kubectl get globals
example-global 6d17h
$ kubectl describe global example-global
Name: example-global
Namespace: default
Labels: <none>
Annotations: <none>
API Version:
Kind: Global

To apply the settings contained within the Global resource to your HAProxy Kubernetes Ingress Controller, overwrite the kubernetes-ingress ConfigMap resource and set its cr-global key to the namespace and name of your custom resource:

apiVersion: v1
kind: ConfigMap
name: kubernetes-ingress
namespace: haproxy-controller
cr-global: default/example-global

Then apply it with kubectl

$ kubectl apply -f myconfigmap.yaml

The Benefits of Custom Resources

As you’ve seen, by installing custom resource definitions like Global, you implement new types in your Kubernetes cluster. Custom resources offer a number of benefits.

For one, they promote a clearer mental model by grouping related properties into an object. In other words, rather than putting an ingress controller’s global settings into a ConfigMap—after all, ConfigMap is a very generic type of thing - you put them into a resource named Global. With such a name, it becomes much easier to reason about where these settings fit in the overall scheme of your cluster.

As a Kubernetes resource, cluster administrators can control who can create them, such as to give only other cluster administrators permission through the use of Kubernetes’s role-based access control (RBAC). You could define Role or ClusterRole objects to determine which users can create Global objects, for example. This promotes separation of concerns between cluster administrators and other users.

As mentioned, you can use familiar Kubernetes tools like kubectl to manage custom resources. This makes it simple to control their lifecycle. When you no longer need a group of global settings, simply call kubectl delete to remove it. The HAProxy Kubernetes Ingress Controller is notified of such events and will update its underlying HAProxy configuration automatically.

Finally, a custom resource allows for a more expressive syntax than run-of-the-mill annotations. That’s because, while annotations are only key-value pairs, properties inside a custom resource can be arrays or objects. So, you can have lists of properties or nested properties to express complex settings. The resource is validated as a whole, to make sure that all properties make sense together.


In this article, you learned that the HAProxy Kubernetes Ingress Controller provides a set of custom resources that includes Global, Defaults, and Backend, which you can use to manage ingress controller settings. After installing the resource definitions, you can create any number of these types of objects, and they behave just like the standard resource types.

Custom resources have a number of benefits, including an easier mental model, simpler reusability and access control, better property validation, and support for Kubernetes-native tools like kubectl. Check out the documentation to learn more!

Interested to know when we publish content like this? Subscribe to our blog! You can also follow us on Twitter and join the conversation on Slack.

Subscribe to our blog. Get the latest release updates, tutorials, and deep-dives from HAProxy experts.