Deploying with Helm¶

The Helm chart is the supported way to install HAPTIC. A default install deploys the controller, a 2-replica HAProxy Deployment, the CRDs, and a ready-to-use set of template libraries covering Ingress and Gateway API — so traffic routes without any template authoring. Cross-namespace HAProxy management, conditional resource watching, and which libraries load are all configured through Helm values.

Prerequisites¶

Kubernetes 1.21+ (the default PodDisruptionBudget uses policy/v1 and the controller watches discovery.k8s.io/v1 EndpointSlices)
Helm 3.8+ (the oci:// chart reference needs OCI registry support, generally available since Helm 3.8)

Note

The haproxyVersion value controls both the controller image tag and the HAProxy image tag, ensuring version compatibility between the two. Supported versions start at HAProxy 3.0 — the template libraries require 3.0+ for their SSL/TLS features. See the Chart Values Reference for details.

Installation¶

helm install my-controller oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic --version 0.2.0-alpha.1

With custom values:

helm install my-controller oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0-alpha.1 \
  -f my-values.yaml

What's in this chart¶

The chart deploys:

Controller Deployment -- the controller that watches resources and generates configurations
HAProxy Deployment (optional, on by default) -- the load balancers that serve your traffic, each with the HAPTIC agent alongside
CRDs -- six resource types under the haproxy-haptic.org API group: HAProxyTemplateConfig (input — the operator's own templates, watched resources, settings) and HAProxyTemplateLibrary (one object per enabled template library, referenced from the config), plus HAProxyCfg, HAProxyGeneralFile, HAProxyCRTListFile, and HAProxyMapFile (outputs the controller publishes for observability). Installed from charts/haptic/crds/; preserved across helm uninstall (delete them explicitly — see Uninstalling)
HAProxyTemplateConfig custom resource -- built from controller.config, listing the enabled libraries in merge order via spec.libraryRefs
HAProxyTemplateLibrary custom resources -- one per enabled controller.templateLibraries.* entry, each carrying that library's snippets, templating settings, maps, files, and tests
IngressClass and GatewayClass -- routing API integration for Ingress and Gateway API resources
RBAC, NetworkPolicy, and ServiceAccount -- permissions and network security
Vector sidecar (on by default) -- receives the HAProxy access log over a Unix datagram socket, derives per-request metrics from it, and re-exports the SPOA hub's Prometheus metrics with its own; HAProxy's exporter is scraped directly
Pre-rollout validation hook and CRD upgrade hook (both on by default) -- pre-install/pre-upgrade Jobs that run haptic preflight against your values and server-side apply the bundled CRDs, so a bad configuration or a stale CRD schema fails the release instead of the running fleet
Optional ServiceMonitor and PodMonitors -- Prometheus integration for the controller and the HAProxy pods
Optional admission webhook -- validates watched resources (Ingress, HTTPRoute, …) before they're admitted

New to HAPTIC? Getting Started walks through a first install and a sample app, end to end.

Where to go next¶

Jump to what you need:

Task	See
Configure or filter the ingress class	IngressClass
Set up TLS/HTTPS	SSL Certificates
Use Ingress annotations (auth, rate limiting, etc.)	Annotations
Tune HAProxy resource limits or service type	HAProxy Deployment
Enable or disable template libraries	Template Libraries
Run multiple controller replicas	High Availability
Set up Prometheus scraping	Monitoring
Restrict network access with NetworkPolicy	Networking
Diagnose problems	Troubleshooting

Running multiple HAPTIC instances in one cluster¶

Running more than one HAPTIC release in the same cluster is supported — for example, one release per team, or one handling Ingress while another handles a custom resource. The releases stay independent as long as a few identifiers don't overlap. Give each additional release its own values for all of these:

Setting	Values key	Why it must differ
Release name and namespace	`helm install <name> --namespace <ns>`	Scopes every Kubernetes object the chart creates, and the leader-election lease
Ingress class	`ingressClass.name`	The controller watches only Ingresses whose `spec.ingressClassName` equals this value. Two releases sharing it would both process the same Ingresses
Gateway class	`gatewayClass.name`	The controller watches only Gateways whose `spec.gatewayClassName` equals this value
Controller identifier	`ingressClass.controllerName` and `gatewayClass.controllerName`	The `GatewayClass` watch is filtered to `spec.controllerName`; two releases sharing it would fight over the same GatewayClasses' status. Default: `haproxy-haptic.org/controller`

You don't edit any watch fieldSelector by hand — the chart derives each resource's fieldSelector from the class names above, so a unique ingressClass.name and gatewayClass.name is enough to scope a release's watches.

The leader-election lease name (controller.config.controller.leaderElection.leaseName) defaults to the release's full name, so distinct release names already produce distinct leases. Set it explicitly only if you deliberately reuse a name.

Example values for a second release with its own classes:

# team-b-values.yaml
ingressClass:
  name: haptic-team-b
  controllerName: haproxy-haptic.org/team-b
gatewayClass:
  name: haptic-team-b
  controllerName: haproxy-haptic.org/team-b

helm install haptic-team-b oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0-alpha.1 \
  --namespace haptic-team-b --create-namespace \
  -f team-b-values.yaml

Ingress and Gateway authors then select this release with ingressClassName: haptic-team-b or gatewayClassName: haptic-team-b.

Upgrading¶

If you installed with a values file, re-pass it so your custom values survive the upgrade:

helm upgrade my-controller oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0-alpha.1 \
  -f my-values.yaml

Otherwise, upgrade without it:

helm upgrade my-controller oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
  --version 0.2.0-alpha.1

The chart owns the HAProxyTemplateConfig

The chart renders the HAProxyTemplateConfig from controller.config plus one HAProxyTemplateLibrary per enabled template library, so it owns all of those resources. Every helm upgrade re-applies the values-derived spec and reverts any change you made with kubectl edit htplcfg or kubectl patch. A manual edit is live and drives the controller immediately, but it only lasts until the next helm operation. To make a change durable, put it under controller.config in your values file instead of editing the CRD directly.

Uninstalling¶

helm uninstall my-controller

Replace my-controller with whatever release name you used at install time. helm uninstall removes all resources created by the chart; the chart's CRDs are preserved so a reinstall picks up existing custom resources. To remove the CRDs as well, delete the whole haproxy-haptic.org API group explicitly:

kubectl delete crd \
  haproxytemplateconfigs.haproxy-haptic.org \
  haproxytemplatelibraries.haproxy-haptic.org \
  haproxycfgs.haproxy-haptic.org \
  haproxygeneralfiles.haproxy-haptic.org \
  haproxycrtlistfiles.haproxy-haptic.org \
  haproxymapfiles.haproxy-haptic.org

Found a problem on this page? Report it or edit the page with the pencil icon above the title.