API Reference¶
Field-level reference for the project's own custom resources, generated from the Go types the CRDs are built from. For examples, status conditions and the Gateway API resources the controller watches, see the CRD Reference.
cf.k8s.lex.la/v1alpha1¶
Package v1alpha1 contains API Schema definitions for the cf.k8s.lex.la v1alpha1 API group.
Resource Types¶
- ExternalBackend
- ExternalBackendList
- GatewayClassConfig
- GatewayClassConfigList
- GatewayConfig
- GatewayConfigList
ExternalBackend¶
ExternalBackend is the Schema for the externalbackends API. It is a namespaced, 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.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | ExternalBackend | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec ExternalBackendSpec |
ExternalBackendList¶
ExternalBackendList contains a list of ExternalBackend.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | ExternalBackendList | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items ExternalBackend array |
ExternalBackendScheme¶
Underlying type: string
ExternalBackendScheme is the wire protocol used to reach an external backend.
Validation:
- Enum: [http https]
Appears in:
| Value | Description |
|---|---|
http | ExternalBackendSchemeHTTP reaches the backend over plaintext HTTP. |
https | ExternalBackendSchemeHTTPS reaches the backend over TLS. |
ExternalBackendSpec¶
ExternalBackendSpec defines an out-of-cluster HTTP(S) endpoint that an HTTPRoute or GRPCRoute may target as a backendRef. It exists because the in-process L7 proxy ultimately just 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), this type makes the scheme explicit and lets the host be an address that is not a valid Service name.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
scheme ExternalBackendScheme | Scheme is the protocol used to dial the backend: "http" or "https". | Enum: [http https] Required | |
host string | Host is the backend hostname or IP address (no scheme, port, or path). IPv6 literals must be bracketed (e.g. "[2001:db8::1]"). The controller performs a final URL parse; this pattern only rejects obvious mistakes such as embedding a scheme or path. | MaxLength: 253 MinLength: 1 Pattern: ^[a-zA-Z0-9._:\[\]-]+$ Required | |
port integer | Port is the backend TCP port. | Maximum: 65535 Minimum: 1 Required | |
path string | Path is an optional base path prepended to the request path when the proxy dials the backend. Must begin with "/". It may include a query string (e.g. "/v1?token=abc"); those query parameters are merged into every dialed request, with the request's own parameters taking precedence on a key conflict. | Pattern: ^/.*$ Optional |
GatewayClassConfig¶
GatewayClassConfig is the Schema for the gatewayclassconfigs API. It provides configuration for Cloudflare Tunnel Gateway API implementation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | GatewayClassConfig | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec GatewayClassConfigSpec | |||
status GatewayClassConfigStatus |
GatewayClassConfigList¶
GatewayClassConfigList contains a list of GatewayClassConfig.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | GatewayClassConfigList | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items GatewayClassConfig array |
GatewayClassConfigSpec¶
GatewayClassConfigSpec defines the desired state of GatewayClassConfig.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
cloudflareCredentialsSecretRef SecretReference | CloudflareCredentialsSecretRef references a Secret containing Cloudflare API credentials. The Secret must hold a valid Cloudflare API token under the key named by Key, which defaults to "api-token". | Required | |
accountId string | AccountID is the Cloudflare account ID. Optional - if not specified, it will be read from the credentials secret ("account-id" key) or auto-detected if the API token has access to only one account. When set, must be a 32-character lowercase hexadecimal string -- the format Cloudflare uses for account IDs. Validated server-side via a CRD-level CEL rule (Kubernetes >= 1.25) so an invalid value is rejected at admission time, before the controller has to reconcile it. Empty string passes through because the field is optional. | Optional | |
tunnelID string | TunnelID is the Cloudflare Tunnel UUID. | Pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$ Required | |
allowSharedTunnels boolean | AllowSharedTunnels permits a Gateway with a dedicated data plane to serve a Cloudflare Tunnel that another namespace's Gateway, or this GatewayClass itself, already serves. Off by default, because holding a tunnel's connector token proves access to the tunnel, not a right to the routes another namespace serves on it, and one token can end up in two namespaces. Sharing a tunnel merges both parties' routes into one ingress document and pushes the union to both parties' proxies. With this off, such a Gateway is refused with Accepted=False/InvalidParameters and none of its routes are programmed. A claim Cloudflare does not confirm is refused either way. Turn it on only where every party on a shared tunnel is trusted to see the others' routes — a single-tenant cluster, or a migration from the shared plane to dedicated ones. It lives here, on the cluster-scoped GatewayClassConfig, precisely so a tenant cannot grant it to themselves. | Optional | |
maxDataPlanesPerNamespace integer | MaxDataPlanesPerNamespace limits how many Gateways in one namespace may each have a dedicated data plane. Every opted-in Gateway renders a proxy Deployment, a headless Service, a NetworkPolicy and an optional HPA into its own namespace, and registers a connector on its tunnel. A tenant able to create Gateways and GatewayConfigs can otherwise multiply that as far as they like. Past the cap the newest Gateways are refused with Accepted=False/DataPlaneQuotaExceeded and their planes are not rendered. Oldest first (creation timestamp, then UID), so a Gateway created now takes a free slot or is refused and never evicts one already serving. Two things do evict, tearing down a running plane on the next reconcile: lowering the cap below what a namespace already holds, and an OLDER Gateway opting in later, since the order is by creation timestamp rather than by when the plane was asked for. Counted per namespace over every Gateway carrying spec.infrastructure.parametersRef, including ones already refused for something else and ones whose configuration does not currently resolve. Counting only the ones that resolve would let a tenant make a token unreadable to slip another Gateway under the cap. Omitting the field means unlimited, which is what an upgrade that does not set it gets. 0 is rejected rather than accepted as a second spelling of unlimited: it is what an operator writes for "no dedicated planes here", and granting the opposite would fail open. It lives here, on the cluster-scoped GatewayClassConfig, so a tenant cannot raise it. | Minimum: 1 Optional |
GatewayClassConfigStatus¶
GatewayClassConfigStatus defines the observed state of GatewayClassConfig.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | Conditions describe the current state of the GatewayClassConfig. | Optional |
GatewayConfig¶
GatewayConfig is the Schema for the gatewayconfigs API: the per-Gateway data-plane configuration referenced by Gateway.spec.infrastructure.parametersRef. Its presence opts the Gateway into hard data-plane isolation — a dedicated proxy Deployment and a dedicated Cloudflare Tunnel.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | GatewayConfig | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
spec GatewayConfigSpec | |||
status GatewayConfigStatus |
GatewayConfigList¶
GatewayConfigList contains a list of GatewayConfig.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | cf.k8s.lex.la/v1alpha1 | ||
kind string | GatewayConfigList | ||
metadata ListMeta | Refer to Kubernetes API documentation for fields of metadata. | ||
items GatewayConfig array |
GatewayConfigSpec¶
GatewayConfigSpec configures a DEDICATED data plane for one Gateway: its own proxy Deployment and its own Cloudflare Tunnel, instead of the shared chart-deployed proxy pool serving every Gateway of the class. Referenced from Gateway.spec.infrastructure.parametersRef (group=cf.k8s.lex.la, kind=GatewayConfig, same namespace). A Gateway without a parametersRef keeps the shared data plane unchanged.
The tunnel identity (tunnel ID and account) is PARSED from the connector token — there is deliberately no separate tunnelID field, which would invite token/ID mismatch bugs.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
tunnelTokenSecretRef LocalSecretReference | TunnelTokenSecretRef references the Secret (same namespace) holding the Cloudflare Tunnel connector token under the "tunnel-token" key (or Key). The token determines the tunnel this Gateway's data plane serves. | Required | |
cloudflareCredentialsSecretRef LocalSecretReference | CloudflareCredentialsSecretRef optionally overrides the API credentials used to write this Gateway's tunnel ingress document, from a Secret in the SAME namespace under the "api-token" key (or Key). Defaults to the credentials resolved from the Gateway's GatewayClass → GatewayClassConfig (class defaults, Gateway overrides). Namespace-local like every other reference here — a cross-namespace option would let a tenant point the controller at another tenant's credentials. | Optional | |
authTokenSecretRef LocalSecretReference | AuthTokenSecretRef optionally references a Secret (same namespace) with a bearer token (key "auth-token" or Key) protecting this Gateway's proxy config API; the controller authenticates its config pushes with it. | Optional | |
replicas integer | Replicas is the fixed proxy replica count. Defaults to 2 (the HA floor for tunnel connectors). Mutually exclusive with autoscaling. Capped at 100 — see Autoscaling.MaxReplicas for the rationale. | Maximum: 100 Minimum: 1 Optional | |
autoscaling ProxyAutoscaling | Autoscaling renders a HorizontalPodAutoscaler for the proxy Deployment instead of a fixed replica count. | Optional | |
resources ResourceRequirements | Resources sets the proxy container's resource requests and limits. Defaults to the controller's built-in proxy defaults when unset. | Optional | |
image string | Image overrides the proxy container image for this Gateway. Defaults to the controller's --proxy-image flag (set by the Helm chart to the release's proxy image). The pattern is a permissive image-reference sanity check ( registry[:port]/repo[:tag][@digest]) — it rejects empty, leadingjunk, and whitespace at admission rather than letting a garbage value fail only at pod-pull time, far from the Gateway's status. | MinLength: 1 Pattern: ^[a-zA-Z0-9][a-zA-Z0-9._/:@-]*$ Optional |
GatewayConfigStatus¶
GatewayConfigStatus defines the observed state of GatewayConfig. Reserved: the controller does not write it today (config problems surface on the REFERENCING Gateway as Accepted=False/InvalidParameters, the actionable place), and its RBAC deliberately grants no status write. The subresource exists so adding conditions later is not a breaking CRD change.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array | Conditions describe the current state of the GatewayConfig. | Optional |
LocalSecretReference¶
LocalSecretReference references a Secret in the SAME namespace as the referencing resource — deliberately no Namespace field. A GatewayConfig is reached through Gateway.spec.infrastructure.parametersRef, which the Gateway API defines as namespace-local; the credentials it carries follow the same boundary so one tenant's Gateway cannot point at another tenant's Secrets.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the Secret. | MinLength: 1 Required | |
key string | Key in the Secret. Defaults depend on context: "tunnel-token" for tunnelTokenSecretRef, "auth-token" for authTokenSecretRef, "api-token" for cloudflareCredentialsSecretRef. | Optional |
ProxyAutoscaling¶
ProxyAutoscaling configures a HorizontalPodAutoscaler for the per-Gateway proxy Deployment, scaling on the proxy's in-flight request gauge (an I/O-bound L7 hop saturates on concurrency, not CPU). Serving the metric to the HPA requires a metrics adapter (prometheus-adapter or KEDA) exposing it through the custom-metrics API; without one the HPA reports FailedGetPodsMetric and holds minReplicas.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
minReplicas integer | MinReplicas is the lower bound. Defaults to 2 — the HA floor for tunnel connectors. | Maximum: 100 Minimum: 1 Optional | |
maxReplicas integer | MaxReplicas is the upper bound. Capped at 100: replica counts are tenant-controlled input on a shared cluster, and an unbounded value is a noisy-neighbour attack. Aggregate resource usage still needs a per-namespace ResourceQuota — the cap bounds one Gateway, not a tenant. | Maximum: 100 Minimum: 1 Required | |
targetInflightPerPod integer | TargetInflightPerPod is the average in-flight request count per pod the HPA aims for. | Minimum: 1 Required | |
metricName string | MetricName overrides the Pods-type custom metric the HPA consumes. Defaults to the proxy's in-flight gauge. | Optional |
SecretReference¶
SecretReference is a reference to a Kubernetes Secret.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the Secret. | MinLength: 1 Required | |
namespace string | Namespace of the Secret. Defaults to the namespace the controller runs in. | Optional | |
key string | Key in the Secret. Defaults to "api-token". | Optional |