# HAPTIC - HAProxy Ingress Controller

> Documentation for HAPTIC, a template-driven HAProxy ingress controller for Kubernetes with Ingress and Gateway API support.

Every page below is also served as raw Markdown at its URL plus `index.md`.

## Agent skill

- [HAPTIC skill](https://haproxy-haptic.org/docs/dev/agent-skills/haptic/SKILL.md): Workflow for Scriggo customization, resource access, and validation.
- [Install the skill](https://haproxy-haptic.org/docs/dev/agent-skill/index.md): Installation, downloads, and example prompts.

## Documentation

- [Home](https://haproxy-haptic.org/docs/dev/index.md): HAPTIC (HAProxy Template Ingress Controller) routes Kubernetes traffic through
- [Customize with an AI agent](https://haproxy-haptic.org/docs/dev/agent-skill/index.md): Install the HAPTIC skill to give your coding agent instructions for Scriggo
- [Annotations](https://haproxy-haptic.org/docs/dev/annotations/index.md): Use Ingress annotations to configure route behavior without writing templates.
- [Changelog](https://haproxy-haptic.org/docs/dev/changelog/index.md): All notable changes to HAPTIC — the controller and its Helm chart — are
- [CRD Reference](https://haproxy-haptic.org/docs/dev/crd-reference/index.md): An HAProxyTemplateConfig defines the watched resources, templates, deployment
- [Overview](https://haproxy-haptic.org/docs/dev/deploying-with-helm/index.md): Install HAPTIC with the Helm chart. It deploys the controller, two HAProxy
- [GatewayClass](https://haproxy-haptic.org/docs/dev/gateway-class/index.md): A GatewayClass selects the controller that manages a Gateway. HAPTIC creates the
- [Getting Started](https://haproxy-haptic.org/docs/dev/getting-started/index.md): Install HAPTIC with Helm, then route traffic through an Ingress. The optional
- [HAProxy Deployment](https://haproxy-haptic.org/docs/dev/haproxy-deployment/index.md): The chart can deploy HAProxy pods alongside the controller, or you can manage HAProxy separately.
- [IngressClass](https://haproxy-haptic.org/docs/dev/ingress-class/index.md): Use an IngressClass to select which Ingresses HAPTIC manages. The Helm chart
- [Migrating](https://haproxy-haptic.org/docs/dev/migrating/index.md): Move Ingresses from ingress-nginx, haproxy-ingress, or
- [Chart Values Reference](https://haproxy-haptic.org/docs/dev/reference/index.md): Every Helm value the chart accepts, with its type and default.
- [SSL Certificates](https://haproxy-haptic.org/docs/dev/ssl-certificates/index.md): The Helm chart creates a default certificate for HTTPS.
- [Supported Configuration](https://haproxy-haptic.org/docs/dev/supported-configuration/index.md): HAPTIC renders HAProxy configuration as text and deploys it through the HAPTIC
- [Overview](https://haproxy-haptic.org/docs/dev/template-libraries/index.md): A template library is a set of text templates that turns Kubernetes resource
- [Template Reference](https://haproxy-haptic.org/docs/dev/template-reference/index.md): Look up template context variables, HAPTIC functions, file paths, and status-patch
- [Templating](https://haproxy-haptic.org/docs/dev/templating/index.md): Write templates to add routing behavior the bundled libraries
- [Troubleshooting](https://haproxy-haptic.org/docs/dev/troubleshooting/index.md): Find your symptom in the quick reference below, then follow its diagnosis and fix.
- [Upgrading to 0.2](https://haproxy-haptic.org/docs/dev/upgrading-to-0.2/index.md): Use this guide to upgrade from 0.1.0 or a 0.2.0 alpha to 0.2.0. The controller
- [Validation Tests](https://haproxy-haptic.org/docs/dev/validation-tests/index.md): Validation tests render templates against fixture resources and check the output. Define them in HAProxyTemplateConfig or its libraries, run them locally with h
- [Watching Resources](https://haproxy-haptic.org/docs/dev/watching-resources/index.md): Use spec.watchedResources to select the Kubernetes resources your templates can
- [HAPTIC Agent](https://haproxy-haptic.org/docs/dev/development/agent/index.md): The HAPTIC agent runs as the agent container of every HAProxy pod. It owns
- [CRD Validation](https://haproxy-haptic.org/docs/dev/development/crd-validation-design/index.md): This page captures the durable design decisions behind the HAProxyTemplateConfig CRD and the validation stack. For field-by-field reference see CRD Reference; f
- [Design Overview](https://haproxy-haptic.org/docs/dev/development/design/index.md): HAPTIC is a Kubernetes operator that watches Kubernetes resources and renders them through templates into validated HAProxy configurations.
- [Gateway API Upgrade Playbook](https://haproxy-haptic.org/docs/dev/development/gateway-api-upgrade-playbook/index.md): Mechanical checklist for bumping the sigs.k8s.io/gateway-api dependency.
- [Linting](https://haproxy-haptic.org/docs/dev/development/linting/index.md): 1. Repo-consistency guards — the scripts/check-.sh set: test inventory, template libraries parsing as YAML, comment fusion, migration-coverage drift, vendor ann
- [Releasing](https://haproxy-haptic.org/docs/dev/development/releasing/index.md): The controller and the Helm chart are released together: one version number, one v<version> git tag, one changelog, one release pipeline. The VERSION file is th
- [Scriggo Fork Maintenance](https://haproxy-haptic.org/docs/dev/development/scriggo-fork-maintenance/index.md): HAPTIC renders operator-authored templates through a fork of Scriggo,
- [Overview](https://haproxy-haptic.org/docs/dev/development/design/architecture-overview/index.md): This page maps the controller's runtime components and how a Kubernetes change flows through rendering, validation, and deployment. For what HAPTIC is and why, 
- [Configuration Model](https://haproxy-haptic.org/docs/dev/development/design/configuration/index.md): The controller is headless: no CLI flags carry domain configuration, no config files are mounted. Operators interact with it through the HAProxyTemplateConfig C
- [Deployment](https://haproxy-haptic.org/docs/dev/development/design/deployment/index.md): graph TB
- [Design Decisions](https://haproxy-haptic.org/docs/dev/development/design/design-decisions/index.md): This page summarizes the current architecture. The linked Architecture Decision
- [Introspection](https://haproxy-haptic.org/docs/dev/development/design/introspection/index.md): The controller exposes its live state — config, rendered output, resources, events — over an HTTP debug server, so you can debug production issues and drive acc
- [Leader Election](https://haproxy-haptic.org/docs/dev/development/design/leader-election/index.md): HAPTIC runs multiple controller replicas for high availability. This page explains the mechanism: which components run on every replica, which run only on the l
- [Package Structure](https://haproxy-haptic.org/docs/dev/development/design/package-structure/index.md): The controller is split into small Go packages with one of three roles:
- [Sequence Diagrams](https://haproxy-haptic.org/docs/dev/development/design/sequence-diagrams/index.md): The controller uses a reinitialization loop pattern where it responds to configuration changes by restarting with the new configuration. Each iteration follows 
- [Base](https://haproxy-haptic.org/docs/dev/libraries/base/index.md): The base library supplies haproxyConfig and shared extension points for routing libraries and custom snippets.
- [Gateway API](https://haproxy-haptic.org/docs/dev/libraries/gateway/index.md): The Gateway API library compiles HTTPRoute, GRPCRoute, TLSRoute, and TCPRoute resources into HAProxy routing configuration.
- [haproxy-ingress (haproxy-ingress.github.io/*)](https://haproxy-haptic.org/docs/dev/libraries/haproxy-ingress/index.md): Use this library when migrating Ingresses with haproxy-ingress.github.io/
- [haproxytech (haproxy.org/*)](https://haproxy-haptic.org/docs/dev/libraries/haproxytech/index.md): Use this library when migrating Ingresses with haproxy.org/ annotations from
- [haptic-annotations (haproxy-haptic.org/*)](https://haproxy-haptic.org/docs/dev/libraries/haptic-annotations/index.md): Set routing, authentication, and response behavior with haproxy-haptic.org/
- [ingress-annotations-compat (internals)](https://haproxy-haptic.org/docs/dev/libraries/ingress-annotations-compat/index.md): This library provides shared macros for haptic-annotations, haproxytech, haproxy-ingress, and nginx-ingress. It emits no configuration on its own. Keep it enabl
- [Ingress](https://haproxy-haptic.org/docs/dev/libraries/ingress/index.md): The Ingress library turns networking.k8s.io/v1 Ingress resources into HAProxy routing configuration.
- [nginx-ingress (nginx.ingress.kubernetes.io/*)](https://haproxy-haptic.org/docs/dev/libraries/nginx-ingress/index.md): Use this library when migrating Ingresses with nginx.ingress.kubernetes.io/
- [Reload-free routing](https://haproxy-haptic.org/docs/dev/libraries/reload-free/index.md): HAProxy can change some running state through its Runtime API: map entries,
- [SSL](https://haproxy-haptic.org/docs/dev/libraries/ssl/index.md): The SSL library provides TLS certificate management, HTTPS frontend configuration, and SSL passthrough infrastructure for HAProxy.
- [Debugging](https://haproxy-haptic.org/docs/dev/operations/debugging/index.md): Inspect the controller's loaded configuration, rendered output, recent events,
- [Governance guardrails](https://haproxy-haptic.org/docs/dev/operations/governance/index.md): Use governance rules to require annotations, supply defaults, or constrain values
- [HAProxy Versions](https://haproxy-haptic.org/docs/dev/operations/haproxy-versions/index.md): Set haproxyVersion to select the HAProxy series for your installation. The chart
- [High Availability](https://haproxy-haptic.org/docs/dev/operations/high-availability/index.md): Run multiple controller replicas so configuration delivery can recover after a leader failure.
- [Monitoring](https://haproxy-haptic.org/docs/dev/operations/monitoring/index.md): Use Prometheus to monitor configuration delivery and traffic. This guide covers
- [Networking](https://haproxy-haptic.org/docs/dev/operations/networking/index.md): This page covers the chart's NetworkPolicy configuration: what the default policies allow, how to harden them, and how to replace them with your own. For exposi
- [Performance](https://haproxy-haptic.org/docs/dev/operations/performance/index.md): Size the controller for its watched resources, templates, and validation workload.
- [Pluggable Validators](https://haproxy-haptic.org/docs/dev/operations/pluggable-validators/index.md): Use validator sidecars to check auxiliary files before publication or deployment.
- [Response caching](https://haproxy-haptic.org/docs/dev/operations/response-cache/index.md): Use a shared Varnish cache to serve repeated GET and
- [Security](https://haproxy-haptic.org/docs/dev/operations/security/index.md): Configure permissions, credentials, pod security, and network access for your
- [SPIFFE/SPIRE mTLS](https://haproxy-haptic.org/docs/dev/operations/spiffe-mtls/index.md): Use SPIFFE/SPIRE to give HAProxy automatic mutual TLS (mTLS) to backend services: SPIRE issues and rotates short-lived X.509 certificates, and HAPTIC wires them
- [SPOA Hub](https://haproxy-haptic.org/docs/dev/operations/spoa-hub/index.md): The SPOA hub runs beside HAProxy and handles request processing through plugins:
- [Validate before deploying](https://haproxy-haptic.org/docs/dev/operations/validate-before-deploy/index.md): Run haptic preflight to check your chart values before deployment. Helm runs it
- [WAF policies](https://haproxy-haptic.org/docs/dev/operations/waf-policies/index.md): Define a web application firewall (WAF) policy once, then let application teams
- [ADR-0001: Renderer is synchronous, not an event adapter](https://haproxy-haptic.org/docs/dev/development/adr/0001-renderer-is-synchronous-not-event-adapter/index.md): Accepted.
- [ADR-0002: Helm library load rules are decentralized](https://haproxy-haptic.org/docs/dev/development/adr/0002-decentralized-helm-library-loader/index.md): Accepted. Partly superseded by ADR-0014: the decentralized helmload
- [ADR-0003: Annotation-compat scaffold lives at library hierarchy level 2.5](https://haproxy-haptic.org/docs/dev/development/adr/0003-annotation-compat-scaffold-level-2-5/index.md): Accepted.
- [ADR-0004: No typed registry over globalFeatures while it stays small](https://haproxy-haptic.org/docs/dev/development/adr/0004-no-typed-registry-over-global-features/index.md): Accepted.
- [ADR-0005: Path matching order is a values flag, not a library variant](https://haproxy-haptic.org/docs/dev/development/adr/0005-path-matching-order-as-values-flag/index.md): Accepted.
- [ADR-0006: HTTP store ↔ proposal validator stays event-driven](https://haproxy-haptic.org/docs/dev/development/adr/0006-httpstore-proposal-validation-stays-event-driven/index.md): Accepted.
- [ADR-0007: SPOA hub config is rendered by HAPTIC, hot-reloaded by the hub](https://haproxy-haptic.org/docs/dev/development/adr/0007-spoa-hub-config-rendered-by-haptic/index.md): Accepted.
- [ADR-0008: Template libraries may live as a directory of fragments](https://haproxy-haptic.org/docs/dev/development/adr/0008-split-library-directory-convention/index.md): Accepted.
- [ADR-0009: Auxiliary file UPDATEs always skip the dataplane's auto-reload](https://haproxy-haptic.org/docs/dev/development/adr/0009-aux-file-skip-reload/index.md): Obsoleted by ADR-0022 on 2026-08-18. The Data Plane API
- [ADR-0010: Typed top-level globals for watched resources](https://haproxy-haptic.org/docs/dev/development/adr/0010-typed-watched-resources/index.md): Accepted. Implementation: Tier-2 typed-watched-resources work merged in
- [ADR-0011: No HAProxy server-state-file — server addresses are config-driven](https://haproxy-haptic.org/docs/dev/development/adr/0011-no-haproxy-server-state-file/index.md): Accepted. Implementation on branch fix/endpoint-conditions-filter: removed
- [ADR-0012: store: on-demand — informer-body projection (accept) + access-gated reconcile (defer)](https://haproxy-haptic.org/docs/dev/development/adr/0012-on-demand-projection-and-access-gated-reconcile/index.md): Partially implemented. Mechanism 1 (informer-body projection) has shipped — pkg/k8s/watcher/projection.go installs the transform via SharedIndexInformer.SetTran
- [ADR-0013: Accept the bounded rolling-restart residual — a leaving worker's stranded keep-alive connection](https://haproxy-haptic.org/docs/dev/development/adr/0013-rolling-restart-leaving-worker-residual/index.md): Accepted. No code behaviour change. Documents why the two candidate fixes for
- [ADR-0014: One HAProxyTemplateConfig per template library, merged by the controller](https://haproxy-haptic.org/docs/dev/development/adr/0014-per-library-config-objects/index.md): Accepted, then superseded — first by ADR-0016, then by ADR-0017.
- [ADR-0015: Tag-based cache invalidation](https://haproxy-haptic.org/docs/dev/development/adr/0015-tag-based-cache-invalidation/index.md): Proposed. No code. Records what was verified against the deployed image, and the
- [ADR-0016: One config kind, many instances, validated before rollout](https://haproxy-haptic.org/docs/dev/development/adr/0016-one-config-kind-many-instances-pre-rollout-validation/index.md): Accepted 2026-08-05. Prerequisites shipped earlier (!1541, !1542, !1543);
- [ADR-0017: Library content moves to a HAProxyTemplateLibrary kind](https://haproxy-haptic.org/docs/dev/development/adr/0017-template-library-kind/index.md): Accepted 2026-08-08. Supersedes ADR-0016's
- [ADR-0018: Typed collection pipelines in chart templates](https://haproxy-haptic.org/docs/dev/development/adr/0018-typed-collection-pipelines/index.md): Accepted. Phase 1 and the map-identifier half of Phase 2 implemented in
- [ADR-0019: Domain events require a payload consumer](https://haproxy-haptic.org/docs/dev/development/adr/0019-domain-events-require-a-payload-consumer/index.md): Accepted.
- [ADR-0020: One authoritative validation pipeline for rendered output](https://haproxy-haptic.org/docs/dev/development/adr/0020-authoritative-render-validation-pipeline/index.md): Accepted 2026-08-10; amended 2026-08-26 to remove built-in and protocol-v1
- [ADR-0021: Prometheus scrapes HAProxy's exporter directly; the exclusion policy lives in HAProxy](https://haproxy-haptic.org/docs/dev/development/adr/0021-haproxy-exporter-scraped-directly/index.md): Accepted 2026-08-16.
- [ADR-0022: The HAPTIC agent replaces the Data Plane API; the controller decides, the agent applies](https://haproxy-haptic.org/docs/dev/development/adr/0022-haptic-agent/index.md): Accepted 2026-08-18. Obsoletes ADR-0009. Supersedes ADR-0020 §Decision steps 1
- [ADR-0023: Incremental rendering uses exact immutable dependencies](https://haproxy-haptic.org/docs/dev/development/adr/0023-incremental-render-graph/index.md): Proposed 2026-08-24. Implementation in progress for issue #187.
- [ADR-0024: Resource application backpressures the next render](https://haproxy-haptic.org/docs/dev/development/adr/0024-resource-application-backpressure/index.md): Accepted 2026-09-10.