[Gateway API] Add BackendTLSPolicy support for HTTPS backend connections

[evanlhatch]

Summary

The Pomerium Gateway API controller does not currently support the BackendTLSPolicy resource (gateway.networking.k8s.io/v1alpha3). This prevents users from configuring TLS connections to backend services when using the Gateway API, which is a core feature of the Gateway API specification for backends that require HTTPS (e.g., the Kubernetes API, external services with TLS).

Current Behavior

When creating an HTTPRoute that routes to a backend service on port 443 (HTTPS), Pomerium's Envoy proxy sends HTTP traffic instead of HTTPS, resulting in errors like "Client sent an HTTP request to an HTTPS server." The BackendTLSPolicy resource, which is the standard Gateway API mechanism for configuring backend TLS, is not watched or processed by the Pomerium controller.

Expected Behavior

Pomerium should watch BackendTLSPolicy resources and configure Envoy to use TLS when connecting to backend services as specified. This would align with the Gateway API specification and provide feature parity with the Ingress API (which supports ingress.pomerium.io/backend-protocol: HTTPS annotations).

Steps to Reproduce

1. Install Pomerium with Gateway API enabled
2. Create a service that requires HTTPS (e.g., Kubernetes API or any TLS-enabled service)
3. Create an HTTPRoute referencing that service on port 443:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: pomerium-gateway
  hostnames:
  - example.com
  rules:
  - backendRefs:
    - name: tls-backend-service
      port: 443

4. Create a BackendTLSPolicy for that service:

apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: tls-config
spec:
  targetRefs:
  - group: ""
    kind: Service
    name: tls-backend-service
  validation:
    hostname: backend.example.com
    wellKnownCACertificates: "System"

5. Attempt to access the route through Pomerium
6. Observe that traffic fails with HTTP errors because Envoy sends HTTP to an HTTPS backend

Evidence

From controller startup logs, Pomerium watches these Gateway API resources:

• GatewayClasses, Gateways, HTTPRoutes
• ReferenceGrants (v1beta1)
• PolicyFilters (v1alpha1)

Notably absent: BackendTLSPolicy (v1alpha3) is not watched, despite being a standard Gateway API resource for configuring backend TLS.

Proposed Solution

1. Add BackendTLSPolicy to the Gateway controller's watched resources
2. Implement reconciliation logic to read BackendTLSPolicy configurations
3. Configure Envoy clusters with appropriate TLS settings when a BackendTLSPolicy targets a service used as a backend
4. Support common BackendTLSPolicy fields:
   • spec.validation.hostname for SNI
   • spec.validation.wellKnownCACertificates or spec.validation.caCertificates for CA validation
   • spec.options for implementation-specific settings

Workarounds

Currently, users must either:

• Use the Ingress API instead (which supports backend TLS via annotations)
• Only proxy HTTP backends through Gateway API
• Implement custom sidecars or proxies to handle TLS termination

References

• Gateway API BackendTLSPolicy documentation: https://gateway-api.sigs.k8s.io/geps/gep-1897/
• BackendTLSPolicy API reference: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
• Pomerium Ingress backend TLS annotations: https://www.pomerium.com/docs/k8s/ingress#annotations

Version Info

• Pomerium: v0.32.3
• Gateway API: v1alpha3 (BackendTLSPolicy)