haptic

module
v0.2.0-alpha.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2026 License: Apache-2.0

README

HAPTIC

HAPTIC Logo

License Build Status Coverage

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.cfg but 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.2.0-alpha.1

The chart ships with template libraries for Kubernetes Ingress and Gateway API enabled by default — standard routing works immediately without any template configuration.

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 upstream Gateway API conformance suite (requires `make test-e2e` cluster).
# Imports sigs.k8s.io/gateway-api/conformance as a Go library.
make test-gateway-conformance

# Run upstream Kubernetes Ingress conformance suite (requires `make test-e2e` cluster).
# Builds the upstream binary from a pinned `git clone` of
# kubernetes-sigs/ingress-controller-conformance. Note: upstream is
# dormant (last commit 2023-08-28); we pin the SHA and do not auto-follow.
make test-ingress-conformance

# 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-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.

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:

  1. Run make check-all to verify code quality
  2. Add tests for new functionality
  3. Update documentation as needed
  4. 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:

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.
gen-validators command
gen-validators generates zero-allocation OpenAPI validators for HAProxy models.
 gen-validators generates zero-allocation OpenAPI validators for HAProxy models.
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.
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 a shared event-loop scaffold for controller components that subscribe on construction and dispatch one event at a time.
 Package component provides a shared event-loop scaffold for controller components that subscribe on construction and dispatch one event at a time.
controller/configchange
controller/configloader
controller/configpublisher
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/conversion
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/credentialsloader
controller/currentconfigstore
Package currentconfigstore provides a utility component for caching the parsed current HAProxy configuration from the HAProxyCfg CRD.
 Package currentconfigstore provides a utility component for caching the parsed current HAProxy configuration from the HAProxyCfg CRD.
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 that performs dry-run reconciliation for webhook validation.
 Package dryrunvalidator implements the DryRunValidator 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/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/leaderelection
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/metrics
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 provides validation of hypothetical configuration changes.
 Package proposalvalidator provides validation of 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/renderer
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/resourceloader
Package resourceloader provides shared event loop infrastructure for loader components that watch a single resource type and parse/transform its data.
 Package resourceloader provides shared event loop infrastructure for loader components that watch a single resource type and parse/transform its data.
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/validator
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/testutil
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/dataplanetest
Package dataplanetest provides test doubles for pkg/dataplane.
 Package dataplanetest provides test doubles for pkg/dataplane.
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/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/parser/sectionextract
Package sectionextract extracts standard (Community Edition) HAProxy sections from a client-native config-parser into a parserconfig.StructuredConfig.
 Package sectionextract extracts standard (Community Edition) HAProxy sections from a client-native config-parser into a parserconfig.StructuredConfig.
dataplane/validators
Package validators provides zero-allocation OpenAPI validation for HAProxy models.
 Package validators provides zero-allocation OpenAPI validation for HAProxy models.
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
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.
generated/dataplaneapi/v33
Package v33 provides primitives to interact with the openapi HTTP API.
 Package v33 provides primitives to interact with the openapi HTTP API.
generated/informers/externalversions
generated/informers/externalversions/haproxytemplate
generated/informers/externalversions/haproxytemplate/v1alpha1
generated/informers/externalversions/internalinterfaces
generated/listers/haproxytemplate/v1alpha1
generated/validators
Package genvalidators holds the machine-generated zero-allocation OpenAPI validators and hashers for every supported HAProxy DataPlane API version.
 Package genvalidators holds the machine-generated zero-allocation OpenAPI validators and hashers for every supported HAProxy DataPlane API version.
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/configpublisher
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/leaderelection
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.
metrics
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.
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.
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
conformance
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.
tools
linters/eventimmutability module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.