# ADR-0026: Policies for Gateway HTTP and gRPC rules

## Status

Accepted.

## Context

The native Ingress annotations configure authentication, fleet-wide rate limits,
WAF inspection, and shared caching. Gateway routes need the same enforcement
without copying Ingress annotations or adding resource-specific Go code.

Route names alone cannot identify enforcement state. An HTTPRoute and GRPCRoute
can share a namespace and name, and rules within either route can require
different policies. Backend names must also distinguish the target namespace.

## Decision

The chart defines a namespaced `HAProxyRoutePolicy` resource. An HTTPRoute or
GRPCRoute rule attaches one policy through an `ExtensionRef` filter with group
`haproxy-haptic.org`. The policy must be in the route's namespace. Credential
Secrets must be in the policy's namespace. Backend-level attachments and multiple
policy filters on one rule are rejected; there is no implicit merge or precedence.

Credential Secrets must be immutable. Route and policy admission validate their
contents before attachment, and Kubernetes rejects subsequent data updates.
Rotation creates a new immutable Secret and changes the policy reference. Every
reconciliation rechecks immutability and content, including after deletion and
recreation under the same name.

This replaces the unreleased broad Secret webhook: protecting credentials no
longer depends on a controller being available when a Secret changes. The policy
change still validates the complete affected route set before acceptance. Missing,
mutable, or malformed credentials fail closed during reconciliation. Mutable
frontend and operational TLS Secrets retain their existing validation and renewal
paths. Helm can write its release metadata while repairing a stopped controller.

Gateway WAF catalogs follow the same reference contract. `waf.catalogRef` selects
an immutable ConfigMap in the policy's namespace, with a key defaulting to
`policies.yaml`. Rotation creates a new immutable catalog and updates the policy
reference. Each catalog version has a distinct enforcement identity, so old and
new versions can coexist. Namespace and cluster policy limits count distinct
catalog entries, including the existing Ingress catalogs; sharing a reference
doesn't consume the budget twice. Inline administrator policies remain available;
external trusted catalogs must also be immutable when used by Gateway policies.

Kubernetes rejects catalog data edits even while the controller is stopped.
Route and policy admission validate new selections, and reconciliation rejects
missing, mutable, or invalid replacements under an existing name. This replaces
the unreleased ConfigMap webhook without exempting a mutable policy dependency.
Admission stays in the controller pods. Helm can write its operational ConfigMaps
and Secrets before running repair hooks; policy reference changes still fail
closed while admission is unavailable. Missing or invalid trusted catalogs also
fail closed for their Ingress consumers instead of aborting the entire render.
Admission continues to reject invalid catalogs and unresolved default policies.

A policy can combine JWT and API-key authentication, a shared rate limit, a WAF
catalog selection, and HTTP caching. Both authentication checks apply when both
are configured. WAF selection keeps the catalog's enforcement and tenant limits.
GRPCRoute rejects caching and WAF policies that buffer request bodies.

Rate limits apply across the HAProxy fleet. Reusing a policy shares its budget
across attached rules; source IP or authenticated consumer partitions the budget.
Cache entries remain separated by the selected origin and route rule. Each key
component is encoded before joining it to avoid delimiter collisions. Authenticated cached
responses also require a verified consumer identity in the cache key.

The existing engines accept normalized settings and route records through a
shared chart library. Ingress annotation parsing remains in its annotation
library; Gateway attachment and status handling live in the `gateway-policies`
library, loaded with Gateway support.
Neither adapter constructs fake resources for the other. Go continues to discover
schemas and watch resources through the existing generic interfaces.

Runtime policy lookups use an identity containing route kind, namespace, name,
and rule index. Human-readable access-log resource fields retain namespace/name.
Policy identity and route identity are separate: a shared rate budget belongs to
the policy, while filter selection and cache origin belong to the route rule.

Missing or invalid attached policies fail closed for the affected rule. Admission
rejects changes that introduce invalid attachments or dependencies. Reconciliation
must also handle invalid objects that predate admission and dependencies removed
after attachment; these cannot block unrelated routes or retain stale permission.
Route status reports unresolved references and unsupported configurations. A
policy update revalidates every attached rule, including gRPC restrictions.

## Verification

Native chart tests cover schema absence, namespace ownership, same-name route
kinds, multiple rules, missing dependencies, policy updates and deletion, and
disabled feature dependencies. Live tests verify credential rejection, budget
sharing across replicas, WAF rejection, cache isolation, and recovery. Existing
Ingress behavior and Gateway conformance remain required gates.