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/
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
- 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
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.0The 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.
For AI-assisted configuration, see the agent skill guide.
# 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-coverageThe 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 downWarning
Always use the kind-haptic-dev cluster context for development work. The kind-haproxy-test context is reserved for integration tests and will be automatically created and destroyed by test runs.
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-filesDo not bypass the hooks with --no-verify; CI runs the same checks, so skipping them only defers the failure.
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.
Licensed under the Apache License 2.0 - see LICENSE file for details.
Copyright 2025 Philipp Hossner
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