README
¶
HAPTIC
HAPTIC (HAProxy Template Ingress Controller) is a template-driven HAProxy Ingress Controller for Kubernetes that generates HAProxy configurations using Scriggo templates and deploys them through the HAPTIC agent in each HAProxy pod.
Documentation: https://haproxy-haptic.org/
Key Features
Template-Driven Flexibility
Traditional ingress controllers embed configuration logic in code. HAPTIC inverts this:
- Full HAProxy access - If HAProxy supports it, your templates can emit it — every section, every directive in the configuration manual
- Add features without code changes - New directives are template updates, not controller releases
- Rich template context - Access any Kubernetes resource, fetch external data via HTTP, and use controller state in your templates
- Everything is templatable - Generate not just
haproxy.cfgbut also map files, SSL certificates, CRT-lists, and custom auxiliary files
Validation and operations
- High availability - Leader election with automatic failover
- Layered validation - Admission webhook, template validation, and tests you can run in CI before anything reaches a cluster
- Observability - Prometheus metrics, structured logging, and debug endpoints
Quick Start
Features described on main can include unreleased changes. Select your installed
release in the versioned documentation before
following setup instructions.
helm install my-controller oci://ghcr.io/haproxy-haptic/haptic/charts/haptic --version 0.7.0
The chart ships with template libraries for Kubernetes Ingress and Gateway API enabled by default. Use them for standard routing, or extend them with your own templates.
For complete setup instructions including HAProxy pod deployment, see the Getting Started guide.
Development
For AI-assisted configuration, see the agent skill guide.
Build and Test
# Build the controller binary
make build
# Run unit tests
make test
# Run integration tests (requires kind cluster)
make test-integration
# Run Gateway API conformance (requires the test-e2e cluster)
make test-gateway-conformance
# Run Ingress conformance (requires the test-e2e cluster)
make test-ingress-conformance
# Run linting checks
make lint
# Run tests, linting, and security checks
make check-all
# Build Docker image
make docker-build
# Generate coverage report
make test-coverage
Local Development Environment
The project includes scripts for local development with kind:
# Start development cluster with controller
./scripts/start-dev-env.sh
# Rebuild and restart controller after code changes
./scripts/start-dev-env.sh restart
# View controller logs
./scripts/start-dev-env.sh logs
# Check deployment status
./scripts/start-dev-env.sh status
# Test ingress functionality
./scripts/start-dev-env.sh test
# Clean up development environment
./scripts/start-dev-env.sh down
[!WARNING] Always use the
kind-haptic-devcluster context for development work. Thekind-haproxy-testcontext is reserved for integration tests and will be automatically created and destroyed by test runs.
Pre-commit Hooks
Set up automatic code quality checks using pre-commit:
# Install pre-commit (one-time setup)
pip install pre-commit
# or: brew install pre-commit
# Install git hooks (one-time per repository clone)
pre-commit install
# Hooks now run automatically on git commit (run `make lint` and `make audit`)
git commit -m "my changes"
# Run hooks manually on all files
pre-commit run --all-files
Do not bypass the hooks with --no-verify; CI runs the same checks, so skipping them only defers the failure.
Contributing
Contributions are welcome. Before submitting pull requests:
- Run
make check-allto verify code quality - Add tests for new functionality
- Update documentation as needed
- Follow existing code style and patterns
See the development documentation for architecture and patterns.
License
Licensed under the Apache License 2.0 - see LICENSE file for details.
Copyright 2025 Philipp Hossner
Acknowledgments
This project builds on open source software:
- Kubernetes client-go - Kubernetes API client library
- HAProxy client-native - HAProxy models and parsing used by the playground and test oracles
- Scriggo - Go-native templating engine
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
check-map-identities
command
Command check-map-identities verifies benchmark snapshots against ADR-0031.
|
Command check-map-identities verifies benchmark snapshots against ADR-0031. |
|
gen-validators
command
gen-validators generates zero-allocation OpenAPI validators for HAProxy models.
|
gen-validators generates zero-allocation OpenAPI validators for HAProxy models. |
|
haptic
command
Package main provides the CLI entrypoint for the HAProxy template ingress controller.
|
Package main provides the CLI entrypoint for the HAProxy template ingress controller. |
|
playground
command
This file is intentionally NOT build-tagged for wasm: the resource-bucketing logic is pure Go (no syscall/js) so it compiles — and is unit-tested — on the normal `go test` path, while main.go (js && wasm) consumes it.
|
This file is intentionally NOT build-tagged for wasm: the resource-bucketing logic is pure Go (no syscall/js) so it compiles — and is unit-tested — on the normal `go test` path, while main.go (js && wasm) consumes it. |
|
playground/internal/migratecheck
Package migratecheck classifies Ingress annotations and source-controller ConfigMap keys against the migration-coverage data the template libraries declare for the browser playground's migration report.
|
Package migratecheck classifies Ingress annotations and source-controller ConfigMap keys against the migration-coverage data the template libraries declare for the browser playground's migration report. |
|
playground/migrationassetcheck
command
|
|
|
examples
|
|
|
basic-apply
command
Basic example demonstrating the HAPTIC agent contract end to end.
|
Basic example demonstrating the HAPTIC agent contract end to end. |
|
pkg
|
|
|
apis/haproxytemplate/v1alpha1
Package v1alpha1 contains API Schema definitions for the haproxytemplate v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the haproxytemplate v1alpha1 API group. |
|
compression
Package compression provides zstd compression utilities for large configurations.
|
Package compression provides zstd compression utilities for large configurations. |
|
controller
Package controller provides the main controller orchestration for the HAProxy template ingress controller.
|
Package controller provides the main controller orchestration for the HAProxy template ingress controller. |
|
controller/buffers
Package buffers provides fixed buffer sizes for event subscriptions.
|
Package buffers provides fixed buffer sizes for event subscriptions. |
|
controller/coalesce
Package coalesce provides utilities for event coalescing in controller components.
|
Package coalesce provides utilities for event coalescing in controller components. |
|
controller/commentator
Package commentator provides the Event Commentator pattern for domain-aware logging.
|
Package commentator provides the Event Commentator pattern for domain-aware logging. |
|
controller/component
Package component provides event subscription, dispatch, panic recovery, and shutdown.
|
Package component provides event subscription, dispatch, panic recovery, and shutdown. |
|
controller/configtest
Package configtest runs a HAProxyTemplateConfig's embedded validationTests against an already-built engine, bounded by a timeout.
|
Package configtest runs a HAProxyTemplateConfig's embedded validationTests against an already-built engine, bounded by a timeout. |
|
controller/crdwatch
Package crdwatch reinitializes the controller when the CustomResourceDefinitions backing watched resources change.
|
Package crdwatch reinitializes the controller when the CustomResourceDefinitions backing watched resources change. |
|
controller/debug
Package debug provides controller-specific debug variable implementations.
|
Package debug provides controller-specific debug variable implementations. |
|
controller/deployer
Package deployer applies a validated render to the HAProxy fleet through the HAPTIC agent that owns each pod's file tree.
|
Package deployer applies a validated render to the HAProxy fleet through the HAPTIC agent that owns each pod's file tree. |
|
controller/diagnostics
Package diagnostics collects content-free evidence about a HAPTIC fleet.
|
Package diagnostics collects content-free evidence about a HAPTIC fleet. |
|
controller/discovery
Package discovery provides the Discovery event adapter component.
|
Package discovery provides the Discovery event adapter component. |
|
controller/dryrunvalidator
Package dryrunvalidator implements the DryRunValidator that performs dry-run reconciliation for webhook validation.
|
Package dryrunvalidator implements the DryRunValidator that performs dry-run reconciliation for webhook validation. |
|
controller/eventemitter
Package eventemitter publishes Kubernetes Events for rendered configuration, deployment failures, and rejected watched inputs.
|
Package eventemitter publishes Kubernetes Events for rendered configuration, deployment failures, and rejected watched inputs. |
|
controller/events
Package events contains all domain event type definitions for the HAPTIC controller.
|
Package events contains all domain event type definitions for the HAPTIC controller. |
|
controller/helpers
Package helpers provides shared utility functions for the controller layer.
|
Package helpers provides shared utility functions for the controller layer. |
|
controller/httpstore
Package httpstore provides the event adapter for HTTP resource fetching.
|
Package httpstore provides the event adapter for HTTP resource fetching. |
|
controller/indextracker
Package indextracker provides the IndexSynchronizationTracker that monitors resource watcher synchronization and publishes an event when all are synced.
|
Package indextracker provides the IndexSynchronizationTracker that monitors resource watcher synchronization and publishes an event when all are synced. |
|
controller/inputisolation
Package inputisolation selects independently valid watched-resource updates.
|
Package inputisolation selects independently valid watched-resource updates. |
|
controller/leadership
Package leadership provides utilities for handling leadership transitions in event-driven components.
|
Package leadership provides utilities for handling leadership transitions in event-driven components. |
|
controller/names
Package names provides well-known string constants used across the controller layer.
|
Package names provides well-known string constants used across the controller layer. |
|
controller/pipeline
Package pipeline provides the render-validate pipeline for HAProxy configuration.
|
Package pipeline provides the render-validate pipeline for HAProxy configuration. |
|
controller/pluggablevalidator
Package pluggablevalidator implements the controller-side client for the pluggable-validator-sidecar wire protocol.
|
Package pluggablevalidator implements the controller-side client for the pluggable-validator-sidecar wire protocol. |
|
controller/pluggablevalidator/testutil
Package testutil provides a fixture unix-socket server for exercising the pluggablevalidator client without spinning up a real haproxy-spoa-hub sidecar.
|
Package testutil provides a fixture unix-socket server for exercising the pluggablevalidator client without spinning up a real haproxy-spoa-hub sidecar. |
|
controller/proposalvalidator
Package proposalvalidator validates hypothetical configuration changes.
|
Package proposalvalidator validates hypothetical configuration changes. |
|
controller/reconciler
Package reconciler implements the Reconciler component that triggers reconciliation events on resource changes.
|
Package reconciler implements the Reconciler component that triggers reconciliation events on resource changes. |
|
controller/rendercontext
Package rendercontext provides a centralized builder for template rendering contexts.
|
Package rendercontext provides a centralized builder for template rendering contexts. |
|
controller/rendercycle
Package rendercycle binds one rendered output to every effect produced by the same controller reconciliation under an authenticated immutable root.
|
Package rendercycle binds one rendered output to every effect produced by the same controller reconciliation under an authenticated immutable root. |
|
controller/rendergate
Package rendergate runs the controller's own `haproxy -c` over each render, off the reconcile wall clock.
|
Package rendergate runs the controller's own `haproxy -c` over each render, off the reconcile wall clock. |
|
controller/resourceapplier
Package resourceapplier reconciles template-declared Kubernetes resources via Server-Side Apply (SSA).
|
Package resourceapplier reconciles template-declared Kubernetes resources via Server-Side Apply (SSA). |
|
controller/resourcewatcher
Package resourcewatcher provides the ResourceWatcherComponent that creates and manages watchers for all Kubernetes resources defined in the controller configuration.
|
Package resourcewatcher provides the ResourceWatcherComponent that creates and manages watchers for all Kubernetes resources defined in the controller configuration. |
|
controller/statusapplier
Package statusapplier applies template-driven status patches to Kubernetes resources.
|
Package statusapplier applies template-driven status patches to Kubernetes resources. |
|
controller/testrunner
Package testrunner implements validation test execution for HAProxyTemplateConfig.
|
Package testrunner implements validation test execution for HAProxyTemplateConfig. |
|
controller/testutil
Package testutil provides shared test helpers for controller package tests.
|
Package testutil provides shared test helpers for controller package tests. |
|
controller/throttle
Package throttle provides leading-edge refractory throttle helpers used by controller components that bound their write rate to slow downstream systems (e.g.
|
Package throttle provides leading-edge refractory throttle helpers used by controller components that bound their write rate to slow downstream systems (e.g. |
|
controller/timeouts
Package timeouts provides shared timeout constants used across controller sub-packages.
|
Package timeouts provides shared timeout constants used across controller sub-packages. |
|
controller/timers
Package timers provides safe timer management for event-driven controller components.
|
Package timers provides safe timer management for event-driven controller components. |
|
controller/typebootstrap
Package typebootstrap orchestrates the typed-watched-resources pipeline at controller startup.
|
Package typebootstrap orchestrates the typed-watched-resources pipeline at controller startup. |
|
controller/validation
Package validation provides pure validation services for HAProxy configuration.
|
Package validation provides pure validation services for HAProxy configuration. |
|
controller/warmer
Package warmer keeps a follower's incremental render graph warm.
|
Package warmer keeps a follower's incremental render graph warm. |
|
controller/webhook
Package webhook connects the admission server to controller validation.
|
Package webhook connects the admission server to controller validation. |
|
core/config
Package config provides configuration loading and validation.
|
Package config provides configuration loading and validation. |
|
core/logging
Package logging provides structured logging setup using Go's standard library log/slog package.
|
Package logging provides structured logging setup using Go's standard library log/slog package. |
|
dataplane/agent/agenttest
Package agenttest is an in-process HAPTIC agent: an httptest server that speaks pkg/dataplane/agent/api well enough to drive the controller's deployer without a container.
|
Package agenttest is an in-process HAPTIC agent: an httptest server that speaks pkg/dataplane/agent/api well enough to drive the controller's deployer without a container. |
|
dataplane/agent/api
Package api is the wire contract between the controller and the HAPTIC agent (the container that owns an HAProxy pod's file tree and runtime socket).
|
Package api is the wire contract between the controller and the HAPTIC agent (the container that owns an HAProxy pod's file tree and runtime socket). |
|
dataplane/agent/cli
Package cli turns the agent's typed ops into HAProxy runtime commands and runs them against the worker stats socket.
|
Package cli turns the agent's typed ops into HAProxy runtime commands and runs them against the worker stats socket. |
|
dataplane/agent/client
Package client is the controller's end of the HAPTIC agent wire contract (pkg/dataplane/agent/api): one pooled keep-alive HTTP client per pod, a state read and a streaming multipart apply.
|
Package client is the controller's end of the HAPTIC agent wire contract (pkg/dataplane/agent/api): one pooled keep-alive HTTP client per pod, a state read and a streaming multipart apply. |
|
dataplane/agent/files
Package files owns the manifest-managed file tree of an HAProxy pod: the mount probe, tree hashing, part verification, the backup journal and the transactional write.
|
Package files owns the manifest-managed file tree of an HAProxy pod: the mount probe, tree hashing, part verification, the backup journal and the transactional write. |
|
dataplane/agent/haproxytest
Package haproxytest serves an in-memory model of the HAProxy runtime over a worker stats socket and a master socket.
|
Package haproxytest serves an in-memory model of the HAProxy runtime over a worker stats socket and a master socket. |
|
dataplane/agent/server
Package server is the HAPTIC agent: an HTTP endpoint that owns one HAProxy pod's file tree and its runtime socket.
|
Package server is the HAPTIC agent: an HTTP endpoint that owns one HAProxy pod's file tree and its runtime socket. |
|
dataplane/auxiliaryfiles
Package auxiliaryfiles holds the file types a render produces next to haproxy.cfg: general files (error pages, ACL files), SSL certificates, map files, crt-lists and CA files.
|
Package auxiliaryfiles holds the file types a render produces next to haproxy.cfg: general files (error pages, ACL files), SSL certificates, map files, crt-lists and CA files. |
|
dataplane/dataplanetest
Package dataplanetest provides test doubles for pkg/dataplane.
|
Package dataplanetest provides test doubles for pkg/dataplane. |
|
dataplane/deployplan
Package deployplan decides what one pod has to do to reach a render: run runtime ops, write files only, or reload.
|
Package deployplan decides what one pod has to do to reach a render: run runtime ops, write files only, or reload. |
|
dataplane/planblob
Package planblob is the encoding of the opaque plan a pod stores and hands back on /v1/state: zstd over the plan's JSON, raw bytes on the wire.
|
Package planblob is the encoding of the opaque plan a pod stores and hands back on /v1/state: zstd over the plan's JSON, raw bytes on the wire. |
|
dataplane/renderartifact
Package renderartifact holds authenticated immutable auxiliary render output.
|
Package renderartifact holds authenticated immutable auxiliary render output. |
|
dataplane/renderoutput
Package renderoutput binds one rendered configuration to its exact plan and auxiliary artifacts under an authenticated immutable root.
|
Package renderoutput binds one rendered configuration to its exact plan and auxiliary artifacts under an authenticated immutable root. |
|
dataplane/renderplan
Package renderplan holds the structure a render declares about its own output: the ordered sections of haproxy.cfg, the backend records the generator emitted them from, the map entries, and the file set.
|
Package renderplan holds the structure a render declares about its own output: the ordered sections of haproxy.cfg, the backend records the generator emitted them from, the map entries, and the file set. |
|
events
Package events provides an event bus for component coordination in the HAPTIC controller.
|
Package events provides an event bus for component coordination in the HAPTIC controller. |
|
events/ringbuffer
Package ringbuffer provides a thread-safe generic ring buffer implementation.
|
Package ringbuffer provides a thread-safe generic ring buffer implementation. |
|
generated/clientset/versioned/fake
This package has the automatically generated fake clientset.
|
This package has the automatically generated fake clientset. |
|
generated/clientset/versioned/scheme
This package contains the scheme of the automatically generated clientset.
|
This package contains the scheme of the automatically generated clientset. |
|
generated/clientset/versioned/typed/haproxytemplate/v1alpha1
This package has the automatically generated typed clients.
|
This package has the automatically generated typed clients. |
|
generated/clientset/versioned/typed/haproxytemplate/v1alpha1/fake
Package fake has the automatically generated clients.
|
Package fake has the automatically generated clients. |
|
httpstore
Package httpstore provides HTTP resource fetching with caching and validation.
|
Package httpstore provides HTTP resource fetching with caching and validation. |
|
incremental
Package incremental is a generic incremental computation graph.
|
Package incremental is a generic incremental computation graph. |
|
incremental/internal/immutablevector
Package immutablevector owns compact immutable slices behind authenticated roots.
|
Package immutablevector owns compact immutable slices behind authenticated roots. |
|
introspection
Package introspection provides a generic debug variable registry and HTTP server for exposing application internal state over HTTP.
|
Package introspection provides a generic debug variable registry and HTTP server for exposing application internal state over HTTP. |
|
k8s/certificates
Package certificates renews certificate authorities and identity Secrets.
|
Package certificates renews certificate authorities and identity Secrets. |
|
k8s/client
Package client provides a wrapper around the Kubernetes client-go library.
|
Package client provides a wrapper around the Kubernetes client-go library. |
|
k8s/indexer
Package indexer provides functionality for extracting index keys from Kubernetes resources and filtering fields based on JSONPath expressions.
|
Package indexer provides functionality for extracting index keys from Kubernetes resources and filtering fields based on JSONPath expressions. |
|
k8s/schemafetcher
Package schemafetcher fetches OpenAPI v3 schemas for each watched Kubernetes resource and hands them to pkg/k8s/typegen for runtime type generation.
|
Package schemafetcher fetches OpenAPI v3 schemas for each watched Kubernetes resource and hands them to pkg/k8s/typegen for runtime type generation. |
|
k8s/store
Package store provides storage implementations for indexed Kubernetes resources.
|
Package store provides storage implementations for indexed Kubernetes resources. |
|
k8s/typegen
Package typegen translates OpenAPI v3 schemas into runtime reflect.Type values that Scriggo templates can consume with full compile-time field safety.
|
Package typegen translates OpenAPI v3 schemas into runtime reflect.Type values that Scriggo templates can consume with full compile-time field safety. |
|
k8s/types
Package types defines core interfaces and types for the k8s package.
|
Package types defines core interfaces and types for the k8s package. |
|
k8s/watcher
Package watcher provides Kubernetes resource watching with indexing, field filtering, and debounced callbacks.
|
Package watcher provides Kubernetes resource watching with indexing, field filtering, and debounced callbacks. |
|
lifecycle
Package lifecycle provides component lifecycle management for the controller.
|
Package lifecycle provides component lifecycle management for the controller. |
|
persistenttree
Package persistenttree provides an immutable ordered map with structural sharing: an update returns a new tree sharing every untouched subtree with the old one, so both remain valid and comparable.
|
Package persistenttree provides an immutable ordered map with structural sharing: an update returns a new tree sharing every untouched subtree with the old one, so both remain valid and comparable. |
|
rendercontent
Package rendercontent holds the value types a render produces — Output, TextFragment, Document — and the deltas between two of them.
|
Package rendercontent holds the value types a render produces — Output, TextFragment, Document — and the deltas between two of them. |
|
stores
Package stores provides abstractions for accessing and composing resource stores.
|
Package stores provides abstractions for accessing and composing resource stores. |
|
stores/storetest
Package storetest provides shared mock implementations of stores.Store for testing.
|
Package storetest provides shared mock implementations of stores.Store for testing. |
|
transportsecurity
Package transportsecurity provides reloadable mutual TLS for HTTP connections.
|
Package transportsecurity provides reloadable mutual TLS for HTTP connections. |
|
transportsecurity/issuance
Package issuance creates identities and bounded CA transition certificates.
|
Package issuance creates identities and bounded CA transition certificates. |
|
transportsecurity/tlstest
Package tlstest creates temporary certificate revisions for transport tests.
|
Package tlstest creates temporary certificate revisions for transport tests. |
|
webhook
Package webhook provides a pure library for Kubernetes admission webhooks.
|
Package webhook provides a pure library for Kubernetes admission webhooks. |
|
scripts
|
|
|
dev-env-assets
Package devassets exposes the dev-environment YAML manifests as embedded byte slices so they can be applied programmatically by Go test suites (notably tests/e2e) without relying on filesystem layout or external scripts.
|
Package devassets exposes the dev-environment YAML manifests as embedded byte slices so they can be applied programmatically by Go test suites (notably tests/e2e) without relying on filesystem layout or external scripts. |
|
tests
|
|
|
admission
Package admission probes real admission without storing a resource.
|
Package admission probes real admission without storing a resource. |
|
e2e/availability
Package availability holds the shell scripts the e2e suite runs inside an HAProxy pod to prove a route keeps answering while a test injects a fault.
|
Package availability holds the shell scripts the e2e suite runs inside an HAProxy pod to prove a route keeps answering while a test injects a fault. |
|
e2e/e2ecluster
Package e2ecluster resolves the isolated kind environment used by the e2e suite.
|
Package e2ecluster resolves the isolated kind environment used by the e2e suite. |
|
fixtures
Package fixtures owns reusable test assets and factories that return fresh data.
|
Package fixtures owns reusable test assets and factories that return fresh data. |
|
httpclient
Package httpclient provides HTTP, HTTPS, and mTLS assertions for explicit test endpoints.
|
Package httpclient provides HTTP, HTTPS, and mTLS assertions for explicit test endpoints. |
|
kindutil
Package kindutil provides shared utilities for creating and configuring Kind (Kubernetes in Docker) clusters in test environments.
|
Package kindutil provides shared utilities for creating and configuring Kind (Kubernetes in Docker) clusters in test environments. |
|
kubeexec
Package kubeexec scopes test kubectl commands to an explicit cluster.
|
Package kubeexec scopes test kubectl commands to an explicit cluster. |
|
process
Package process owns external processes used by test infrastructure.
|
Package process owns external processes used by test infrastructure. |
|
publication
Package publication checks observed output independently of publisher helpers.
|
Package publication checks observed output independently of publisher helpers. |
|
runner
command
|
|
|
scenarios
Package scenarios implements the cluster scenarios invoked by native Make targets.
|
Package scenarios implements the cluster scenarios invoked by native Make targets. |
|
testutil
Package testutil provides shared testing utilities for integration and acceptance tests.
|
Package testutil provides shared testing utilities for integration and acceptance tests. |
|
traffic
Package traffic checks routes through owned pod tunnels.
|
Package traffic checks routes through owned pod tunnels. |
|
tunnel
Package tunnel provides stall detection for kubectl port-forward tunnels.
|
Package tunnel provides stall detection for kubectl port-forward tunnels. |
Click to show internal directories.
Click to hide internal directories.