# 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/latest/agent-skills/haptic/SKILL.md): Workflow for Scriggo customization, resource access, and validation.
- [Install the skill](https://haproxy-haptic.org/docs/latest/development/agent-skill/index.md): Installation, downloads, and example prompts.

## Documentation

- [Home](https://haproxy-haptic.org/docs/latest/index.md): HAPTIC lets you shape Kubernetes traffic routing by editing the templates
- [Compatibility overview](https://haproxy-haptic.org/docs/latest/annotation-compatibility/index.md): Compare the annotations HAPTIC accepts from other ingress controllers.
- [Ingress annotations](https://haproxy-haptic.org/docs/latest/annotations/index.md): Use Ingress annotations to configure route behavior without writing templates.
- [Changelog](https://haproxy-haptic.org/docs/latest/changelog/index.md): All notable changes to HAPTIC — the controller and its Helm chart — are
- [Install the CLI](https://haproxy-haptic.org/docs/latest/cli/index.md): The haptic command inspects generated configuration and tests changes before
- [Configuration CRDs](https://haproxy-haptic.org/docs/latest/crd-reference/index.md): An HAProxyTemplateConfig defines the watched resources, templates, deployment
- [Install and upgrade with Helm](https://haproxy-haptic.org/docs/latest/deploying-with-helm/index.md): Install HAPTIC with the Helm chart. It deploys the controller, two HAProxy
- [Try Gateway API](https://haproxy-haptic.org/docs/latest/gateway-api/index.md): Use a Gateway to define your listening ports and an HTTPRoute to send matching
- [GatewayClass](https://haproxy-haptic.org/docs/latest/gateway-class/index.md): A GatewayClass selects the controller that manages a Gateway. The default
- [Install and try HAPTIC](https://haproxy-haptic.org/docs/latest/getting-started/index.md): Install HAPTIC with Helm, then route your applications. The optional
- [Configure HAProxy pods and access](https://haproxy-haptic.org/docs/latest/haproxy-deployment/index.md): The chart deploys two HAProxy replicas by default. Configure Service access,
- [IngressClass](https://haproxy-haptic.org/docs/latest/ingress-class/index.md): Use an IngressClass to select which Ingresses HAPTIC manages. The Helm chart
- [Migrate from another controller](https://haproxy-haptic.org/docs/latest/migrating/index.md): Move Ingresses from ingress-nginx, haproxy-ingress, or
- [Chart values](https://haproxy-haptic.org/docs/latest/reference/index.md): Look up a Helm value's type, default, and behavior. Put these values in the file
- [HAProxyRoutePolicy](https://haproxy-haptic.org/docs/latest/route-policy/index.md): Use HAProxyRoutePolicy to configure authentication, shared rate limits, a web
- [Choose a routing guide](https://haproxy-haptic.org/docs/latest/routing/index.md): Use the bundled Ingress and Gateway API support to route traffic to your
- [TLS certificates](https://haproxy-haptic.org/docs/latest/ssl-certificates/index.md): The Helm chart creates a default certificate for HTTPS.
- [Supported HAProxy configuration](https://haproxy-haptic.org/docs/latest/supported-configuration/index.md): Your templates can generate any directive supported by the HAProxy version you
- [Generate configuration and files](https://haproxy-haptic.org/docs/latest/template-files/index.md): Use these examples when writing your own configuration or auxiliary-file
- [Template syntax](https://haproxy-haptic.org/docs/latest/template-language/index.md): Learn the syntax with small examples you can edit in your browser. These
- [Share and extend libraries](https://haproxy-haptic.org/docs/latest/template-libraries/index.md): A template library is a set of text templates that turns Kubernetes resource
- [Functions and variables](https://haproxy-haptic.org/docs/latest/template-reference/index.md): Look up template context variables, HAPTIC functions, file paths, and status-patch
- [Read resources](https://haproxy-haptic.org/docs/latest/template-resources/index.md): Use watched Kubernetes resources to decide what your templates generate.
- [Report resource status](https://haproxy-haptic.org/docs/latest/template-status/index.md): Report the result of a configuration change on a watched resource with
- [Write your first template](https://haproxy-haptic.org/docs/latest/templating/index.md): Extend the bundled configuration with a snippet when you need behavior the
- [Troubleshooting](https://haproxy-haptic.org/docs/latest/troubleshooting/index.md): Find your symptom in the quick reference below, then follow its diagnosis and fix.
- [Upgrade notes](https://haproxy-haptic.org/docs/latest/upgrade-notes/index.md): Check the notes for every version between your installed version and the version
- [Validation tests](https://haproxy-haptic.org/docs/latest/validation-reference/index.md): Look up fixture fields, test requirements, and assertion types. For a first test
- [Test templates](https://haproxy-haptic.org/docs/latest/validation-tests/index.md): Check that a template produces the configuration you intend before using it for
- [Watch resources](https://haproxy-haptic.org/docs/latest/watching-resources/index.md): Make a Kubernetes resource available to your templates by adding it to
- [AI agent skill](https://haproxy-haptic.org/docs/latest/development/agent-skill/index.md): Install the HAPTIC skill to give your coding agent instructions for
- [HAPTIC Agent](https://haproxy-haptic.org/docs/latest/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/latest/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
- [Debug endpoints and profiles](https://haproxy-haptic.org/docs/latest/development/debug-endpoints/index.md): Use these endpoints when investigating controller behavior or collecting a
- [Design Overview](https://haproxy-haptic.org/docs/latest/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/latest/development/gateway-api-upgrade-playbook/index.md): Mechanical checklist for bumping the sigs.k8s.io/gateway-api dependency.
- [Linting](https://haproxy-haptic.org/docs/latest/development/linting/index.md): 1. Repo-consistency guards — CI job selection and the scripts/check-.sh set: test inventory, template libraries parsing as YAML, comment fusion, migration-cover
- [Releasing](https://haproxy-haptic.org/docs/latest/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/latest/development/scriggo-fork-maintenance/index.md): HAPTIC renders operator-authored templates through a fork of Scriggo,
- [Overview](https://haproxy-haptic.org/docs/latest/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/latest/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/latest/development/design/deployment/index.md): graph TB
- [Design Decisions](https://haproxy-haptic.org/docs/latest/development/design/design-decisions/index.md): This page summarizes the current architecture. The linked Architecture Decision
- [Introspection](https://haproxy-haptic.org/docs/latest/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/latest/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/latest/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/latest/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 extension points](https://haproxy-haptic.org/docs/latest/libraries/base/index.md): The base library provides the main HAProxy configuration and the places where
- [Gateway API](https://haproxy-haptic.org/docs/latest/libraries/gateway/index.md): Route HTTP, gRPC, TLS, and TCP traffic with Gateway API resources. This library
- [haproxy-ingress](https://haproxy-haptic.org/docs/latest/libraries/haproxy-ingress/index.md): Use this library when migrating Ingresses with haproxy-ingress.github.io/
- [HAProxy Technologies](https://haproxy-haptic.org/docs/latest/libraries/haproxytech/index.md): Use this library when migrating Ingresses with haproxy.org/ annotations from
- [Native Ingress annotations](https://haproxy-haptic.org/docs/latest/libraries/haptic-annotations/index.md): Set routing, authentication, and response behavior with haproxy-haptic.org/
- [Annotation library internals](https://haproxy-haptic.org/docs/latest/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 routing](https://haproxy-haptic.org/docs/latest/libraries/ingress/index.md): Route requests by hostname and path using Kubernetes Ingress resources. The
- [ingress-nginx](https://haproxy-haptic.org/docs/latest/libraries/nginx-ingress/index.md): Use this library when migrating Ingresses with nginx.ingress.kubernetes.io/
- [Reload-free routing](https://haproxy-haptic.org/docs/latest/libraries/reload-free/index.md): HAProxy can change some running state through its Runtime API: map entries,
- [TLS extension points](https://haproxy-haptic.org/docs/latest/libraries/ssl/index.md): Serve HTTPS with certificates stored in Kubernetes Secrets. The SSL library
- [Overview](https://haproxy-haptic.org/docs/latest/operations/index.md): Use these guides after installing HAPTIC. Start with
- [Access logging](https://haproxy-haptic.org/docs/latest/operations/access-logging/index.md): Read request logs from the vector container in a default installation. If you
- [Agent certificates](https://haproxy-haptic.org/docs/latest/operations/agent-certificates/index.md): The default chart creates and automatically renews the certificate authority (CA)
- [Debugging](https://haproxy-haptic.org/docs/latest/operations/debugging/index.md): Start with fleet diagnostics to identify a failed validation
- [Fleet diagnostics](https://haproxy-haptic.org/docs/latest/operations/diagnostics/index.md): command. For 0.2.0-alpha.3 or earlier, use the
- [Gateway API conformance](https://haproxy-haptic.org/docs/latest/operations/gateway-conformance/index.md): Use the Gateway API reference to check supported
- [Gateway route policies](https://haproxy-haptic.org/docs/latest/operations/gateway-policies/index.md): Attach a HAProxyRoutePolicy to an HTTPRoute or GRPCRoute rule to authenticate
- [GitOps](https://haproxy-haptic.org/docs/latest/operations/gitops/index.md): Manage HAPTIC through Argo CD or Flux with the examples below. Stable Secrets
- [Enforce routing policies](https://haproxy-haptic.org/docs/latest/operations/governance/index.md): Use governance rules to require annotations, supply defaults, or constrain values
- [HAProxy versions](https://haproxy-haptic.org/docs/latest/operations/haproxy-versions/index.md): Set haproxyVersion to select the HAProxy series for your installation. The chart
- [High availability](https://haproxy-haptic.org/docs/latest/operations/high-availability/index.md): The chart starts two controller replicas and two HAProxy replicas by default.
- [Kubernetes versions](https://haproxy-haptic.org/docs/latest/operations/kubernetes-versions/index.md): HAPTIC requires Kubernetes 1.33 or newer. The chart uses native sidecars to keep
- [Controller and agent metrics](https://haproxy-haptic.org/docs/latest/operations/metrics-reference/index.md): Use this reference to build queries and investigate configuration delivery. For
- [Metrics, alerts, and dashboards](https://haproxy-haptic.org/docs/latest/operations/monitoring/index.md): Use Prometheus to check whether HAPTIC is applying configuration changes and
- [Networking](https://haproxy-haptic.org/docs/latest/operations/networking/index.md): Use NetworkPolicy to control which services the controller and HAProxy pods can
- [Resource sizing](https://haproxy-haptic.org/docs/latest/operations/performance/index.md): For a default installation, reserve about 1 CPU core and 5.4 GiB of memory
- [Validate generated files](https://haproxy-haptic.org/docs/latest/operations/pluggable-validators/index.md): HAProxy checks its own configuration, but your templates may also generate
- [Response caching](https://haproxy-haptic.org/docs/latest/operations/response-cache/index.md): Use a shared Varnish cache to serve repeated GET and
- [Security](https://haproxy-haptic.org/docs/latest/operations/security/index.md): Configure permissions, credentials, pod security, and network access for your
- [Backend mTLS with SPIFFE/SPIRE](https://haproxy-haptic.org/docs/latest/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
- [Traffic processing plugins](https://haproxy-haptic.org/docs/latest/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/latest/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/latest/operations/waf-policies/index.md): Define a web application firewall (WAF) policy once, then let application teams
- [Tune WAF rules](https://haproxy-haptic.org/docs/latest/operations/waf-tuning/index.md): Start a WAF policy in enforcement: detect mode to observe
- [Webhook certificates](https://haproxy-haptic.org/docs/latest/operations/webhook-certificates/index.md): The admission webhook uses its own certificate, separate from the certificates
- [ADR-0001: Renderer is synchronous, not an event adapter](https://haproxy-haptic.org/docs/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/development/adr/0024-resource-application-backpressure/index.md): Accepted 2026-09-10.
- [ADR-0025: Mutual TLS for agent transport](https://haproxy-haptic.org/docs/latest/development/adr/0025-agent-transport-security/index.md): Accepted. Extends ADR-0022's agent protocol.
- [ADR-0026: Policies for Gateway HTTP and gRPC rules](https://haproxy-haptic.org/docs/latest/development/adr/0026-gateway-route-policies/index.md): Accepted.