HAProxyRoutePolicy reference¶
haproxy-haptic.org/v1alpha1, kind HAProxyRoutePolicy, configures enforcement for
one or more HTTPRoute or GRPCRoute rules. The chart installs its CRD. Interpretation
and enforcement live in the Gateway and shared HTTP policy template libraries.
Attachment¶
A rule attaches one policy through an ExtensionRef filter. Set group to
haproxy-haptic.org, kind to HAProxyRoutePolicy, and name to the policy name.
The policy must be in the route's namespace. Multiple policy filters on one rule,
backend-level attachments, and SSL passthrough combined with a policy are rejected.
There is no inherited policy or implicit merge.
A policy must configure at least one of authentication, rateLimit, waf, or
cache. See Protect Gateway routes for a
complete example.
Authentication¶
When both authentication.jwt and authentication.apiKey are configured, both
checks must pass. Missing or invalid request credentials return 401; invalid
policy configuration returns 503 for the affected rule.
Credential Secrets must set immutable: true. Kubernetes prevents changes to
their contents. Admission validates credentials when you attach a policy or
change an attached policy.
Rotate credentials by creating a new immutable Secret and changing secretRef.name;
see Rotate credentials.
A deleted Secret or a mutable replacement makes the affected rules return 503.
JWT¶
JSON Web Tokens (JWTs) use the Authorization: Bearer header. The Secret named by secretRef.name
must be in the policy's namespace and contain one PEM public key in pubkey.pem.
RSA keys require at least 2048 bits. ECDSA curves must match the selected algorithm.
Field under authentication.jwt |
Default | Meaning |
|---|---|---|
secretRef.name |
Required | Public-key Secret |
algorithm |
RS256 |
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, or ES512 |
issuer |
Unset | Required iss value when configured |
audience |
Unset | Required aud value when configured |
requiredClaims |
[] |
Claims that must be present; use [exp, sub] for expiring tokens with a consumer identity |
forwardClaims |
[] |
List of {claim, header} entries copied into request headers after verification |
Present exp and nbf claims are checked. JWT sub supplies the authenticated
consumer identity. Forwarded headers must be distinct and can't overwrite
Authorization or an API-key credential header.
API key¶
Field under authentication.apiKey |
Default | Meaning |
|---|---|---|
secretRef.name |
Required | Same-namespace Secret containing a keys entry |
header |
X-API-Key |
Request header carrying the key |
consumerHeader |
Unset | Header receiving the verified consumer identity |
keys contains newline-separated key:consumer entries. A bare key uses itself
as the consumer identity. Duplicate keys with different consumers are invalid.
A configured consumer header replaces the caller's value. When JWT and API-key
authentication both apply, JWT sub supplies the consumer identity for forwarded
headers, rate limits, and cache partitioning. The API-key consumer is used when
the JWT has no sub claim.
Shared rate limit¶
Requires rateLimit.shared.enabled=true and the shared rate-limit SPOA plugin.
The chart can manage Valkey with rateLimit.shared.managedStore.enabled=true.
Field under rateLimit |
Default | Meaning |
|---|---|---|
requests |
Required | Positive request budget per period |
period |
1s |
Positive duration with ms, s, m, h, or d suffix |
burst |
requests |
Positive burst capacity |
algorithm |
token-bucket |
token-bucket uses distributed leases; gcra checks the shared store for each decision |
key |
ip |
Partition by source IP or authenticated consumer |
A policy's budget is shared by all its attached rules and replicas. The refill
horizon, burst × period ÷ requests, must not exceed 3600 seconds. Consumer limits
require authentication and reject requests with no authenticated consumer.
WAF¶
waf.policy selects a web application firewall (WAF) policy. With no
waf.catalogRef, it selects an administrator's inline policy or a policy from an
immutable trusted catalog. waf.catalogRef.name selects an immutable ConfigMap in
the route policy's namespace; waf.catalogRef.key defaults to policies.yaml.
Explicit catalog references require waf.policies.selfService.enabled=true.
Rotate a catalog by creating a new immutable ConfigMap and changing the policy
reference. Admission validates the affected routes before accepting the change.
Kubernetes rejects data updates to the old catalog. Missing, mutable, or malformed
catalogs fail closed, including after deletion and recreation under the same name.
Existing WAF permissions and limits apply, including
waf.ingressPermissions.allowPolicySelection. Distinct catalog entries share the
namespace and cluster budgets with Ingress catalogs. A self-service policy can't
weaken a default-on deny baseline. The route policy doesn't override enforcement
mode.
Requires spoaHub.plugins.coraza.enabled=true. GRPCRoute requires the selected
catalog policy's requestBody.mode to be none. See the
WAF catalog documentation.
HTTP response cache¶
Requires cache.varnish.enabled=true. Caching applies to GET and HEAD requests;
GRPCRoute rejects this setting.
Field under cache |
Default | Meaning |
|---|---|---|
ttlSeconds |
Origin Cache-Control |
Non-negative cache lifetime in seconds |
maxObjectSizeBytes |
Cache default | Positive maximum object size |
varyHeaders |
[] |
Additional request headers included in the cache key |
Each route rule has a separate cache partition, including rules that rewrite to
the same origin URL. Authenticated caching also partitions by verified consumer
and rejects requests without one. Key components are encoded separately so
separator characters can't merge distinct identities. Reserved X-Haptic-*
headers can't be used as varyHeaders.
Filter order and failures¶
Authentication, quota checks, and WAF inspection precede a configured
RequestRedirect. Gateway CORS preflight handling returns before authentication;
browsers don't send application credentials in preflight requests. Actual requests
still pass the attached policy.
Missing and invalid dependencies deny the affected rule with 503. Route status
sets Accepted=False when all rules are invalid, PartiallyInvalid=True when
some remain valid, and ResolvedRefs=False for unresolved policy or credential
references. Fixing the dependency restores enforcement without changing the
attachment.