CRD Reference¶

This document provides the API reference for Custom Resource Definitions (CRDs) used by the Cloudflare Tunnel Gateway Controller. The controller ships three project-owned CRDs — GatewayClassConfig, ExternalBackend, and GatewayConfig (per-Gateway data planes) — and watches the standard Gateway API resources.

GatewayClassConfig¶

API Version: cf.k8s.lex.la/v1alpha1 Kind: GatewayClassConfig Scope: Cluster

GatewayClassConfig provides tunnel configuration for the controller. It is referenced by a GatewayClass via spec.parametersRef.

Spec¶

The spec carries only the contract the controller needs for Cloudflare API calls. Proxy-side configuration (tunnel token, replicas, liveness probes) lives in the Helm chart proxy.* values; see Helm chart reference.

SecretReference¶

Example¶

apiVersion: cf.k8s.lex.la/v1alpha1
kind: GatewayClassConfig
metadata:
  name: cloudflare-tunnel-config
spec:
  tunnelID: "550e8400-e29b-41d4-a716-446655440000"
  # accountId: "0123456789abcdef0123456789abcdef"  # Optional 32-char hex; auto-detected if omitted
  cloudflareCredentialsSecretRef:
    name: cloudflare-credentials
    key: api-token

Status¶

GatewayClassConfig has a status.conditions subresource. The reconciler emits:

• SecretsResolved — True when the referenced credentials Secret exists and carries the expected key, False otherwise.
• Valid — True when all validation checks pass; False with the first failure message otherwise.

GatewayConfig¶

GatewayConfig is a namespaced CRD carrying per-Gateway data-plane parameters, referenced from Gateway.spec.infrastructure.parametersRef (group cf.k8s.lex.la, kind GatewayConfig, same namespace). Its presence opts the Gateway into a dedicated proxy Deployment and a dedicated Cloudflare Tunnel.

GatewayConfig Spec¶

Replica counts (replicas, minReplicas, maxReplicas) are capped at 100: they are tenant-controlled input on a shared cluster, and an unbounded value is a noisy-neighbour attack. The cap bounds one Gateway, not a tenant — use a per-namespace ResourceQuota for the aggregate.

GatewayConfig Example¶

apiVersion: cf.k8s.lex.la/v1alpha1
kind: GatewayConfig
metadata:
  name: edge-config
  namespace: tenant-a
spec:
  tunnelTokenSecretRef:
    name: edge-tunnel-token
  autoscaling:
    maxReplicas: 10
    targetInflightPerPod: 50

See the Per-Gateway Isolation guide for the full workflow.

ExternalBackend¶

API Version: cf.k8s.lex.la/v1alpha1 Kind: ExternalBackend Scope: Namespaced

ExternalBackend defines an out-of-cluster HTTP(S) endpoint that an HTTPRoute or GRPCRoute may target as a backendRef. The in-process L7 proxy ultimately dials a URL, so a route can point at an arbitrary external origin without a Service standing in for it. Unlike a Service of type ExternalName (which only carries a DNS name and infers the scheme from the port), ExternalBackend makes the scheme explicit and lets the host be an address that is not a valid Service name. It is a spec-only resource (no status): a route referencing a missing or malformed ExternalBackend surfaces the failure on the route's own ResolvedRefs condition, mirroring how an unresolvable Service backendRef is reported. See ExternalBackend for usage details.

ExternalBackend Spec¶

ExternalBackend Example¶

apiVersion: cf.k8s.lex.la/v1alpha1
kind: ExternalBackend
metadata:
  name: external-api
  namespace: default
spec:
  scheme: https
  host: api.example.com
  port: 443
  path: /v1

Gateway API Resources¶

The controller watches standard Gateway API resources. For their full specification, see the Gateway API documentation.

GatewayClass¶

Standard Gateway API GatewayClass with parametersRef pointing to GatewayClassConfig:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cloudflare-tunnel
spec:
  controllerName: cf.k8s.lex.la/tunnel-controller
  parametersRef:
    group: cf.k8s.lex.la
    kind: GatewayClassConfig
    name: cloudflare-tunnel-config

Gateway¶

Standard Gateway API Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: cloudflare-tunnel
  namespace: cloudflare-tunnel-system
spec:
  gatewayClassName: cloudflare-tunnel
  listeners:
    - name: http
      port: 80
      protocol: HTTP

HTTPRoute¶

Standard Gateway API HTTPRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: default
spec:
  parentRefs:
    - name: cloudflare-tunnel
      namespace: cloudflare-tunnel-system
  hostnames:
    - app.example.com
  rules:
    - backendRefs:
        - name: my-service
          port: 80

GRPCRoute¶

GRPCRoute is served by the in-process L7 proxy — gRPC service/method matches map onto /{service}/{method} path rules and the upstream hop is h2c. See GRPCRoute for the full field support matrix.

Standard Gateway API GRPCRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: my-grpc-service
  namespace: default
spec:
  parentRefs:
    - name: cloudflare-tunnel
      namespace: cloudflare-tunnel-system
  hostnames:
    - grpc.example.com
  rules:
    - backendRefs:
        - name: grpc-server
          port: 50051

ReferenceGrant¶

Standard Gateway API ReferenceGrant for cross-namespace references:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-cross-namespace
  namespace: backend
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: frontend
  to:
    - group: ""
      kind: Service

Status Conditions¶

Gateway Status¶

HTTPRoute/GRPCRoute Status¶

Controller-specific advisory conditions¶

Beyond the standard Gateway API conditions above, the controller surfaces domain-prefixed (cf.k8s.lex.la/) advisory conditions for situations the Gateway API defines no condition for — they are informational and do not flip Accepted/Programmed. On routes: cf.k8s.lex.la/RouteShadowed, cf.k8s.lex.la/ProxyConfigPushed, cf.k8s.lex.la/TunnelShared. On a Gateway listener or ListenerSet entry: cf.k8s.lex.la/PermissiveHostname (the allowedRoutes.namespaces.from: All + unpinned-hostname capture combination). Each is described in full on the Limitations page.

API Versions¶

Installing CRDs¶

Gateway API CRDs¶

kubectl apply --filename https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.1/standard-install.yaml

Project CRDs (GatewayClassConfig and ExternalBackend)¶

Installed automatically by the Helm chart. For manual installation:

kubectl apply --filename charts/cloudflare-tunnel-gateway-controller/crds/