haproxytech library¶

Use this library when migrating Ingresses with haproxy.org/* annotations from HAProxy Technologies' Kubernetes Ingress Controller. Review the supported annotations and caveats before switching traffic.

The library is disabled by default. Enable it through the configuration below. For new routes, use native HAPTIC annotations. Both libraries can be enabled during migration; configure each feature through one annotation family to avoid conflicts.

Watch the haproxy.org/* annotations render to HAProxy config live:

In the Resources panel, change the shop Ingress's haproxy.org/load-balance value from leastconn to source, then watch the shop backend's balance line update in the haproxy.cfg tab.

What to expect

The shop backend changes from balance leastconn to balance source. HAProxy then selects a server by client IP hash instead of the current connection count.

Before moving traffic, check annotation compatibility and follow the migration guide.

Important notes:

Annotations apply to Ingress resources only (not Services)
Gateway API resources (HTTPRoute, GRPCRoute) use filters instead of annotations — see Gateway API Library
All annotations use the haproxy.org/ prefix

Configuration¶

Apply the following Helm values through your values file. The annotation examples on this page belong under an Ingress's metadata.annotations; quote all annotation values.

controller:
  templateLibraries:
    haproxytech:
      enabled: true  # Set to enable this opt-in library (disabled by default)

Access control & IP filtering¶

`haproxy.org/allow-list`¶

Allow only the listed IP addresses or CIDR ranges to access the Ingress.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: protected-api
  annotations:
    haproxy.org/allow-list: "192.168.1.0/24, 10.0.0.1"
spec:
  ingressClassName: haptic
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

Related annotations: Can be combined with deny-list

`haproxy.org/deny-list`¶

Deny access from the listed IP addresses or CIDR ranges.

annotations:
  haproxy.org/deny-list: "203.0.113.0/24, 198.51.100.50"

Related annotations: Can be combined with allow-list

`haproxy.org/whitelist`¶

Status: Supported (deprecated alias)

Deprecated alias for allow-list, honoured only when allow-list is absent on the same Ingress. Kept for upstream parity — prefer allow-list for new Ingresses.

Note: If both allow-list and whitelist are set, allow-list wins and whitelist is ignored.

`haproxy.org/blacklist`¶

Status: Supported (deprecated alias)

Deprecated alias for deny-list, honoured only when deny-list is absent on the same Ingress. Kept for upstream parity — prefer deny-list for new Ingresses.

Note: If both deny-list and blacklist are set, deny-list wins and blacklist is ignored.

CORS configuration¶

`haproxy.org/cors-enable`¶

Enable CORS (Cross-Origin Resource Sharing) processing for the ingress.

annotations:
  haproxy.org/cors-enable: "true"
  haproxy.org/cors-allow-origin: "*"
  haproxy.org/cors-allow-methods: "GET, POST, PUT, DELETE"
  haproxy.org/cors-allow-headers: "Content-Type, Authorization"

CORS headers are added to backend responses. To have HAProxy answer preflight requests itself, set cors-respond-to-options.

Dependencies: All other cors-* annotations require cors-enable: "true"

`haproxy.org/cors-allow-origin`¶

Specifies allowed origins for CORS requests. Supports wildcard (*), exact URL, or regex pattern.

Choose one value, for example an exact origin:

haproxy.org/cors-allow-origin: "https://example.com"

Use "*" for any origin, or a regular expression such as ^https://(.+\.)?example\.com$ to match a domain and its subdomains.