Control HAProxy routing
with your own templates.

HAPTIC is an open-source HAProxy ingress controller for Kubernetes. Start with Ingress and Gateway API support. Use templates to add your own annotations, routing rules, or custom resource types.

Install HAPTIC Try a template

haproxy.cfg.tmpl Try in browser

{% for _, ingress := range resources.ingresses.List() %}
backend {{ ingress.metadata.name }}
  balance roundrobin
  {{ render "servers" }}
{% end %}

haproxy.cfg

backend echo
  balance roundrobin
  server echo-pod-1 10.42.0.7:8080 check
  server echo-pod-2 10.42.0.9:8080 check

Routing you can extend

Route HTTP, gRPC, and TCP

Use HAProxy to serve web applications, gRPC services, and TCP connections. HAPTIC generates the routing configuration from Ingress, Gateway API, or your own resources.

Authenticate, limit, and inspect requests

Use native annotations for API-key, JWT, and HMAC authentication. Add shared rate limits, Varnish caching, JSON request validation, and reusable web application firewall (WAF) policies.

Add your own routing behavior

Add an annotation or routing rule by editing a template. Reuse it across services through shared templates, without changing or rebuilding the controller.

Use your platform's resources

Already describe your applications with a custom Kubernetes resource? Watch it directly and use its fields in a template. HAPTIC updates HAProxy when those resources change.

Reload only when needed

Pod scaling, certificate rotation, and routing-map updates can change HAProxy's running configuration without replacing its worker process. For changes that need a reload, HAPTIC starts a new worker while the old one drains connections. See what can update live.

Check changes before rollout

Run haptic preflight on candidate values; Helm runs the check during installation and upgrades. Embedded tests check configuration changes, and admission validates proposed routes with HAProxy and your output validators.

Enforce platform policies

Require a WAF policy or limit the timeout a team can set on a route. Platform rules apply these checks across your resources, so reviewers don't have to check each manifest by hand. Start by reporting violations, then reject new ones.

Trace requests to their routes

Find the route, backend, and policy outcome in JSON access logs and request metrics. Enable distributed tracing to export request and upstream spans through Vector.

Start with the routing rules you already use.

HAPTIC includes sets of templates that turn Ingress, Gateway API, and annotation settings into HAProxy configuration. You can use them as shipped or extend them. When migrating, enable the matching templates for ingress-nginx, HAProxy Technologies, or haproxy-ingress. Check its supported annotations before switching traffic.

Add a custom annotation

Let each Ingress choose a request-ID header for its own backends. Add this snippet under controller.config.templateSnippets in your Helm values:

values.yaml Try in browser

controller:
  config:
    templateSnippets:
      backend-directives-300-request-id:
        template: |
          {%- if ingress != nil %}
            {%- var header = ingress.metadata.annotations["example.com/request-id-header"] %}
            {%- if header != "" %}
              {%- if !regex_search(header, "^[A-Za-z0-9-]+$") %}
                {{ fail("example.com/request-id-header must contain only letters, digits, or hyphens.") }}
              {%- end %}
              http-request set-header {{ header }} %[uuid()]
            {%- end %}
          {%- end %}

Set example.com/request-id-header: "X-Request-ID" on an Ingress. Header names use letters, digits, and hyphens. Changes to this backend directive require a reload.

Customize with your AI agent

Give your agent tested examples and validation steps for writing HAPTIC templates. Install the skill in your configuration project, then ask it to add a custom annotation or watch your own resource type.

bash — install skill

$ npx skills add https://haproxy-haptic.org --skill haptic

Use with Codex, Claude Code, GitHub Copilot in VS Code, or another Agent Skills client. Requires Node.js. Installation guide, ZIP download, and example prompts.

Install with Helm

Requires Kubernetes 1.33 or newer. The chart installs the controller, HAProxy, and the bundled routing libraries. Review the release notes before upgrading.

bash — install

$ helm install \
    haptic oci://registry.gitlab.com/haproxy-haptic/haptic/charts/haptic \
    --version 0.2.0-alpha.3
$ kubectl get haproxytemplateconfig

Documentation and playground

~/docs

Documentation

Install HAPTIC, configure routes and policies, or write your first template. Find deployment procedures, configuration references, and troubleshooting steps for your version.

Available versions

Loading…

~/playground

Playground

Try the controller's template engine in your browser without a cluster. Edit a resource, inspect the generated HAProxy configuration, and share your example with a link.

Launch playground

Apache-2.0 · Playground · Source on GitLab

Community project — independent and not affiliated with or endorsed by HAProxy Technologies.

Control HAProxy routing with your own templates.