cloudflare-gateway-controller

HTTPRoute

The controller processes HTTPRoute resources attached to managed Gateways and sets conditions on .status.parents entries with .controllerName: cloudflare-gateway-controller.io/controller.

This document covers only the conditions set by this controller. For the full HTTPRoute spec, see the Gateway API documentation.

Example

The following example shows an HTTPRoute that routes traffic for app.example.com to a backend Service:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "app.example.com"
  rules:
    - backendRefs:
        - name: my-backend
          port: 80

When DNS is configured in the CloudflareGatewayParameters, the controller creates CNAME records for each hostname in the HTTPRoute.

Validations

The controller validates each HTTPRoute on every reconciliation. If any validation fails, the HTTPRoute is rejected with Accepted=False/UnsupportedValue.

Unsupported fields

The following fields are not supported and must not be set:

Backend references

Match rules

Session persistence

Session persistence pins a client to the same backend across requests.

Cookie-based (default): The proxy sets a cookie on the first response. Subsequent requests with that cookie are routed to the same backend.

rules:
  - sessionPersistence:
      type: Cookie
      sessionName: my-session          # optional, default "cgw-session"
      absoluteTimeout: 1h              # optional
      cookieConfig:
        lifetimeType: Permanent        # "Session" (default) or "Permanent"
    backendRefs:
      - name: svc-a
        port: 80
        weight: 50
      - name: svc-b
        port: 80
        weight: 50

Header-based: The client supplies a header with the backend ID. No cookie is set by the proxy.

rules:
  - sessionPersistence:
      type: Header
      sessionName: X-My-Session        # optional, default "X-Cgw-Session"
    backendRefs:
      - name: svc-a
        port: 80

Cookie lifetime types:

Idle timeout: Gateway API v1.6 removed sessionPersistence.idleTimeout. The controller no longer exposes idle timeout through HTTPRoute or GRPCRoute; the internal proxy configuration still supports it for non-Gateway API sources.

Namespace restrictions

The HTTPRoute must be in a namespace allowed by the Gateway’s listener allowedRoutes configuration. Routes from disallowed namespaces are rejected with Accepted=False/NotAllowedByListeners.

HTTPRoute Status

Conditions

An HTTPRoute enters various states during its lifecycle, reflected as Kubernetes Conditions on each .status.parents entry. It can be accepted, have its references resolved, have DNS records applied, or be ready.

Accepted HTTPRoute

Standard Gateway API condition. The controller marks an HTTPRoute as accepted when it passes validation.

When the HTTPRoute is accepted:

When the HTTPRoute is not accepted:

Reasons for rejection:

Resolved refs

Standard Gateway API condition. The controller reports whether all backendRef references could be resolved.

When all references are resolved:

When a reference cannot be resolved:

The RefNotPermitted reason indicates a cross-namespace backendRef is not permitted by a ReferenceGrant.

DNS records applied

Custom condition, not part of the Gateway API spec. Reports whether DNS CNAME records have been applied for the route’s hostnames. This condition is only present when DNS management is enabled (see CloudflareGatewayParameters for configuration details).

When DNS records are applied successfully:

In all-hostnames mode (default), the message lists all applied hostnames. In specific-zones mode, the message lists applied and skipped hostnames.

When DNS record creation or update fails:

This condition is removed from the status when DNS is disabled.

Ready HTTPRoute

Custom condition, not part of the Gateway API spec. kstatus-compatible condition. This condition starts from the parent Gateway’s Ready value but may be downgraded to Unknown/ProgressingWithRetry when the Gateway is ready but a DNS error occurred for this route’s hostnames.

When the Gateway is ready and DNS records (if configured) applied successfully:

When the Gateway has a terminal failure:

When the Gateway is waiting for the Deployment:

When the Gateway is retrying after transient errors, or the Gateway is ready but a DNS error occurred for this route:

This site is open source. Improve this page.