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 via the HAProxy Dataplane API.
Documentation: https://haproxy-haptic.org/
Key Features
Template-Driven Flexibility
Traditional ingress controllers embed configuration logic in code. HAPTIC inverts this:
- Full HAProxy access - Write any HAProxy directive using the configuration language
- Add features without code changes - New directives are template updates, not controller releases
- Iterate rapidly - Deploy configuration changes in minutes, not release cycles
- 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
Production Ready
- High availability - Leader election with automatic failover
- Comprehensive validation - Validating webhook, template validation, and CI/CD-runnable tests
- Observability - Prometheus metrics, structured logging, and debug endpoints
- HTTP resource access - Fetch external data for use in templates
Quick Start
helm install my-controller oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic --version 0.1.0-alpha.1
For complete setup instructions including HAProxy pod deployment, see the Getting Started guide.
Development
Build and Test
# Build the controller binary
make build
# Run unit tests
make test
# Run integration tests (requires kind cluster)
make test-integration
# Run linting checks
make lint
# Run all checks (tests + linting)
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
git commit -m "my changes" # Runs make lint && make audit
# Skip hooks if needed (for WIP commits)
git commit --no-verify -m "WIP"
# Run hooks manually on all files
pre-commit run --all-files
The hooks run make lint and make audit before each commit to catch issues early.
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 CLAUDE.md for detailed development context 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 Dataplane API client
- Scriggo - Go-native templating engine
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
controller
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. |
|
examples
|
|
|
basic-sync
command
Basic example demonstrating the dataplane Client API
|
Basic example demonstrating the dataplane Client API |
|
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. |
|
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/commentator
Package commentator provides the Event Commentator pattern for domain-aware logging.
|
Package commentator provides the Event Commentator pattern for domain-aware logging. |
|
controller/debug
Package debug provides controller-specific debug variable implementations.
|
Package debug provides controller-specific debug variable implementations. |
|
controller/deployer
Package deployer implements the Deployer component that deploys validated HAProxy configurations to discovered HAProxy pod endpoints.
|
Package deployer implements the Deployer component that deploys validated HAProxy configurations to discovered HAProxy pod endpoints. |
|
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 component that performs dry-run reconciliation for webhook validation.
|
Package dryrunvalidator implements the DryRunValidator component that performs dry-run reconciliation for webhook validation. |
|
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/executor
Package executor implements the Executor component that orchestrates reconciliation cycles by coordinating pure components.
|
Package executor implements the Executor component that orchestrates reconciliation cycles by coordinating pure components. |
|
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/reconciler
Package reconciler implements the Reconciler component that debounces resource changes and triggers reconciliation events.
|
Package reconciler implements the Reconciler component that debounces resource changes and triggers reconciliation events. |
|
controller/rendercontext
Package rendercontext provides a centralized builder for template rendering contexts.
|
Package rendercontext provides a centralized builder for template rendering contexts. |
|
controller/renderer
Package renderer implements the Renderer component that renders HAProxy configuration and auxiliary files from templates.
|
Package renderer implements the Renderer component that renders HAProxy configuration and auxiliary files from templates. |
|
controller/resourcestore
Package resourcestore provides centralized management of resource stores with memory-efficient overlay support for dry-run validation.
|
Package resourcestore provides centralized management of resource stores with memory-efficient overlay support for dry-run validation. |
|
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/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/validator
Package validator implements validation components for HAProxy configuration.
|
Package validator implements validation components for HAProxy configuration. |
|
controller/webhook
Package webhook provides the webhook adapter component that bridges the pure webhook library to the event-driven controller architecture.
|
Package webhook provides the webhook adapter component that bridges the pure webhook library to the event-driven controller architecture. |
|
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
Package dataplane provides a simple, high-level API for synchronizing HAProxy configurations via the Dataplane API.
|
Package dataplane provides a simple, high-level API for synchronizing HAProxy configurations via the Dataplane API. |
|
dataplane/auxiliaryfiles
Package auxiliaryfiles provides functionality for synchronizing auxiliary files (general files, SSL certificates, map files, crt-lists) with the HAProxy Dataplane API.
|
Package auxiliaryfiles provides functionality for synchronizing auxiliary files (general files, SSL certificates, map files, crt-lists) with the HAProxy Dataplane API. |
|
dataplane/client
Package client provides a high-level wrapper around the generated HAProxy Dataplane API client.
|
Package client provides a high-level wrapper around the generated HAProxy Dataplane API client. |
|
dataplane/client/enterprise
Package enterprise provides client operations for HAProxy Enterprise-only DataPlane API endpoints.
|
Package enterprise provides client operations for HAProxy Enterprise-only DataPlane API endpoints. |
|
dataplane/comparator
Package comparator provides comparison functions for HAProxy Enterprise Edition sections.
|
Package comparator provides comparison functions for HAProxy Enterprise Edition sections. |
|
dataplane/comparator/sections
Package sections provides factory functions for creating HAProxy configuration operations.
|
Package sections provides factory functions for creating HAProxy configuration operations. |
|
dataplane/comparator/sections/executors
Package executors provides pre-built executor functions for HAProxy configuration operations.
|
Package executors provides pre-built executor functions for HAProxy configuration operations. |
|
dataplane/parser
Package parser provides HAProxy configuration parsing using client-native library.
|
Package parser provides HAProxy configuration parsing using client-native library. |
|
dataplane/parser/enterprise
Package enterprise provides HAProxy Enterprise Edition configuration parsing.
|
Package enterprise provides HAProxy Enterprise Edition configuration parsing. |
|
dataplane/parser/enterprise/directives
Package types provides parser implementations for HAProxy Enterprise Edition section-specific directives.
|
Package types provides parser implementations for HAProxy Enterprise Edition section-specific directives. |
|
dataplane/parser/enterprise/parsers
Package parsers provides wrapper parsers for HAProxy Enterprise Edition directives.
|
Package parsers provides wrapper parsers for HAProxy Enterprise Edition directives. |
|
dataplane/parser/parserconfig
Package parserconfig provides canonical configuration types for HAProxy parsing.
|
Package parserconfig provides canonical configuration types for HAProxy parsing. |
|
dataplane/synchronizer
Package synchronizer provides configuration synchronization between desired state and HAProxy via the Dataplane API.
|
Package synchronizer provides configuration synchronization between desired state and HAProxy via the Dataplane API. |
|
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. |
|
generated/dataplaneapi/v30
Package v30 provides primitives to interact with the openapi HTTP API.
|
Package v30 provides primitives to interact with the openapi HTTP API. |
|
generated/dataplaneapi/v30ee
Package v30ee provides primitives to interact with the openapi HTTP API.
|
Package v30ee provides primitives to interact with the openapi HTTP API. |
|
generated/dataplaneapi/v31
Package v31 provides primitives to interact with the openapi HTTP API.
|
Package v31 provides primitives to interact with the openapi HTTP API. |
|
generated/dataplaneapi/v31ee
Package v31ee provides primitives to interact with the openapi HTTP API.
|
Package v31ee provides primitives to interact with the openapi HTTP API. |
|
generated/dataplaneapi/v32
Package v32 provides primitives to interact with the openapi HTTP API.
|
Package v32 provides primitives to interact with the openapi HTTP API. |
|
generated/dataplaneapi/v32ee
Package v32ee provides primitives to interact with the openapi HTTP API.
|
Package v32ee provides primitives to interact with the openapi HTTP API. |
|
httpstore
Package httpstore provides HTTP resource fetching with caching and validation.
|
Package httpstore provides HTTP resource fetching with caching and validation. |
|
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/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/store
Package store provides storage implementations for indexed Kubernetes resources.
|
Package store provides storage implementations for indexed Kubernetes resources. |
|
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. |
|
templating
Package templating provides template rendering capabilities using the Scriggo template engine.
|
Package templating provides template rendering capabilities using the Scriggo template engine. |
|
webhook
Package webhook provides a pure library for Kubernetes admission webhooks.
|
Package webhook provides a pure library for Kubernetes admission webhooks. |
|
tests
|
|
|
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. |
|
testutil
Package testutil provides shared testing utilities for integration and acceptance tests.
|
Package testutil provides shared testing utilities for integration and acceptance tests. |
Click to show internal directories.
Click to hide internal directories.