cfgate.iocfgate v0.2.0-alpha.11 · Release documentation

CloudflareTunnel schema

These fields come from the released CRD. Required means required when its parent object is present. Schema defaults do not describe every runtime fallback.

v1alpha1

Field	Type	Required in parent	Schema default	Description

Field	Type	Required in parent	Schema default	Description
“	object	no	none	CloudflareTunnel is the Schema for the cloudflaretunnels API. CloudflareTunnel manages the lifecycle of a Cloudflare Tunnel and its cloudflared daemon deployment. It handles tunnel creation or adoption, credential management, and deploys cloudflared pods that establish secure connections to Cloudflare’s edge network. CloudflareTunnel follows a composable architecture where tunnel lifecycle is separate from DNS management. Use CloudflareDNS with a tunnelRef to create DNS records pointing to this tunnel’s domain. Status conditions: - Ready: tunnel is fully operational - CredentialsValid: API credentials have been validated - TunnelReady: tunnel exists in Cloudflare - ConfigurationSynced: ingress configuration is synced - CloudflaredDeployed: cloudflared pods are running

Field	Type	Required in parent	Schema default	Description
`apiVersion`	string	no	none	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

Field	Type	Required in parent	Schema default	Description
`kind`	string	no	none	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

Field	Type	Required in parent	Schema default	Description
`metadata`	object	no	none

Field	Type	Required in parent	Schema default	Description
`spec`	object	no	none	CloudflareTunnelSpec defines the desired state of a CloudflareTunnel resource. CloudflareTunnelSpec configures the tunnel identity, Cloudflare credentials, cloudflared deployment settings, and origin connection defaults. The tunnel manages lifecycle only; DNS records are managed separately via CloudflareDNS resources.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare`	object	yes	none	Cloudflare defines the Cloudflare API credentials.

Validation for spec.cloudflare:

x-kubernetes-validations:
  - message: either accountId or accountName must be specified
    rule: has(self.accountId) || has(self.accountName)
  - message: accountId must be a 32-character hex string
    rule: "!has(self.accountId) || self.accountId.matches('^[a-f0-9]{32}$')"

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.accountId`	string	no	none	AccountID is the Cloudflare Account ID.

Validation for spec.cloudflare.accountId:

maxLength: 32

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.accountName`	string	no	none	AccountName is the Cloudflare Account name. Will be looked up via API.

Validation for spec.cloudflare.accountName:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretKeys`	object	no	none	SecretKeys defines the key mappings within the secret.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretKeys.apiToken`	string	no	`"CLOUDFLARE_API_TOKEN"`	APIToken is the key name for the Cloudflare API token.

Validation for spec.cloudflare.secretKeys.apiToken:

maxLength: 253

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef`	object	yes	none	SecretRef references the Secret containing Cloudflare API credentials. The secret must contain an API token (not tunnel token).

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef.name`	string	yes	none	Name of the secret.

Validation for spec.cloudflare.secretRef.name:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.cloudflare.secretRef.namespace`	string	no	none	Namespace of the secret. Defaults to the tunnel’s namespace.

Validation for spec.cloudflare.secretRef.namespace:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared`	object	no	none	Cloudflared defines the cloudflared deployment configuration.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.extraArgs`	array	no	none	ExtraArgs are additional arguments to pass to cloudflared.

Validation for spec.cloudflared.extraArgs:

maxItems: 20

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.extraArgs[]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.image`	string	no	`"ghcr.io/inherent-design/cloudflared:2026.9.3-h2c.1@sha256:6c46ca006f9d6af5e973e59f2d71f5d6d3dc138c8a5484380d5797092171e3ad"`	Image is the cloudflared container image.

Validation for spec.cloudflared.image:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.imagePullPolicy`	string	no	`"IfNotPresent"`	ImagePullPolicy is the pull policy for the cloudflared image.

Allowed values for spec.cloudflared.imagePullPolicy: ["Always","Never","IfNotPresent"].

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.metrics`	object	no	none	Metrics configures the cloudflared metrics endpoint.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.metrics.enabled`	boolean	no	`true`	Enabled declares the metrics container port for scraping. Health probes and their shared listener remain enabled.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.metrics.port`	integer	no	`44483`	Port is the port for the metrics endpoint.

Validation for spec.cloudflared.metrics.port:

format: int32
maximum: 65535
minimum: 1

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.nodeSelector`	object	no	none	NodeSelector is a selector for nodes to run cloudflared on.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.nodeSelector[key]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.podAnnotations`	object	no	none	PodAnnotations are annotations to add to cloudflared pods.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.podAnnotations[key]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.protocol`	string	no	`"auto"`	Protocol is the tunnel transport protocol: auto, quic, http2.

Allowed values for spec.cloudflared.protocol: ["auto","quic","http2"].

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.replicas`	integer	no	`2`	Replicas is the number of cloudflared replicas.

Validation for spec.cloudflared.replicas:

format: int32
maximum: 10
minimum: 1

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources`	object	no	none	Resources are the resource requirements for cloudflared containers.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.claims`	array	no	none	Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This field depends on the DynamicResourceAllocation feature gate. This field is immutable. It can only be set for containers.

Validation for spec.cloudflared.resources.claims:

x-kubernetes-list-map-keys:
  - name
x-kubernetes-list-type: map

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.claims[]`	object	no	none	ResourceClaim references one entry in PodSpec.ResourceClaims.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.claims[].name`	string	yes	none	Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.claims[].request`	string	no	none	Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.limits`	object	no	none	Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.limits[key]`	integer or string	no	none

Validation for spec.cloudflared.resources.limits[key]:

anyOf:
  - type: integer
  - type: string
pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
x-kubernetes-int-or-string: true

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.requests`	object	no	none	Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.resources.requests[key]`	integer or string	no	none

Validation for spec.cloudflared.resources.requests[key]:

anyOf:
  - type: integer
  - type: string
pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
x-kubernetes-int-or-string: true

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations`	array	no	none	Tolerations are tolerations for the cloudflared pods.

Validation for spec.cloudflared.tolerations:

maxItems: 20

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[]`	object	no	none	The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator .

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[].effect`	string	no	none	Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[].key`	string	no	none	Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys.

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[].operator`	string	no	none	Operator represents a key’s relationship to the value. Valid operators are Exists, Equal, Lt, and Gt. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. Lt and Gt perform numeric comparisons (requires feature gate TaintTolerationComparisonOperators).

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[].tolerationSeconds`	integer	no	none	TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system.

Validation for spec.cloudflared.tolerations[].tolerationSeconds:

format: int64

Field	Type	Required in parent	Schema default	Description
`spec.cloudflared.tolerations[].value`	string	no	none	Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string.

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef`	object	no	none	FallbackCredentialsRef references a secret containing fallback Cloudflare API credentials. Used during deletion when primary credentials (in Cloudflare.SecretRef) are unavailable. This enables cleanup of Cloudflare resources even if the per-tunnel secret is deleted. The secret must contain the same keys as the primary credentials secret.

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef.name`	string	yes	none	Name of the secret.

Validation for spec.fallbackCredentialsRef.name:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.fallbackCredentialsRef.namespace`	string	no	none	Namespace of the secret. Defaults to the resource’s namespace if empty.

Validation for spec.fallbackCredentialsRef.namespace:

maxLength: 63

Field	Type	Required in parent	Schema default	Description
`spec.fallbackTarget`	string	no	`"http_status:404"`	FallbackTarget is the service for unmatched requests.

Validation for spec.fallbackTarget:

maxLength: 255

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults`	object	no	none	OriginDefaults defines default settings for origin connections.

Validation for spec.originDefaults:

x-kubernetes-validations:
  - message: http2Origin and h2cOrigin are mutually exclusive
    rule: "!(self.http2Origin && self.h2cOrigin)"

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.caPoolSecretRef`	object	no	none	CAPoolSecretRef references a Secret containing CA certificates for origin verification.

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.caPoolSecretRef.key`	string	no	`"ca.crt"`	Key is the key within the secret data.

Validation for spec.originDefaults.caPoolSecretRef.key:

maxLength: 253

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.caPoolSecretRef.name`	string	yes	none	Name of the secret.

Validation for spec.originDefaults.caPoolSecretRef.name:

maxLength: 253
minLength: 1

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.connectTimeout`	string	no	`"30s"`	ConnectTimeout is the timeout for connecting to the origin.

Validation for spec.originDefaults.connectTimeout:

pattern: ^[0-9]+(s|m|h)$

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.h2cOrigin`	boolean	no	`false`	H2cOrigin enables HTTP/2 cleartext (h2c) for origin connections. Use this for origins that speak HTTP/2 without TLS (e.g., gRPC services). Mutually exclusive with http2Origin (TLS-based HTTP/2).

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.http2Origin`	boolean	no	`false`	HTTP2Origin enables HTTP/2 for origin connections.

Field	Type	Required in parent	Schema default	Description
`spec.originDefaults.noTLSVerify`	boolean	no	`false`	NoTLSVerify disables TLS verification for origin connections.

Field	Type	Required in parent	Schema default	Description
`spec.tunnel`	object	yes	none	Tunnel defines the tunnel identity configuration.

Field	Type	Required in parent	Schema default	Description
`spec.tunnel.name`	string	yes	none	Name is the tunnel name in Cloudflare. Existing tunnels require explicit cfgate.io/adopt-existing=true and an exclusive installation ownership claim. If not, create it. Tunnel ID is stored in status after resolution/creation.

Validation for spec.tunnel.name:

maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

Field	Type	Required in parent	Schema default	Description
`status`	object	no	none	CloudflareTunnelStatus defines the observed state of a CloudflareTunnel resource. CloudflareTunnelStatus captures the tunnel’s Cloudflare-assigned identifiers, deployment status, and reconciliation state. The TunnelDomain field provides the CNAME target ({tunnelId}.cfargotunnel.com) that CloudflareDNS uses for DNS record creation.

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies`	array	no	none	AccessDependencies track applications needed by current or possibly applied configurations. Entries are cleared only after remote configuration withdrawal is confirmed.

Validation for status.accessDependencies:

maxItems: 256

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[]`	object	no	none	TunnelAccessDependency records possibly active application and policy protection.

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].accountId`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].hostnames`	array	yes	none

Validation for status.accessDependencies[].hostnames:

maxItems: 64

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].hostnames[]`	string	no	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].name`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].namespace`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].pending`	boolean	no	none	Pending records an unconfirmed publication attempt; protection cannot be removed until a later confirmed sync.

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies`	array	no	none

Validation for status.accessDependencies[].policies:

maxItems: 64

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies[]`	object	no	none	TunnelAccessPolicyDependency retains policy identity until remote withdrawal is verified.

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies[].name`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies[].namespace`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies[].policyId`	string	no	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].policies[].uid`	string	no	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].tunnelId`	string	yes	none

Field	Type	Required in parent	Schema default	Description
`status.accessDependencies[].uid`	string	no	none

Field	Type	Required in parent	Schema default	Description
`status.accountId`	string	no	none	AccountID is the resolved Cloudflare account ID.

Field	Type	Required in parent	Schema default	Description
`status.conditions`	array	no	none	Conditions represent the latest available observations of the tunnel’s state.

Validation for status.conditions:

x-kubernetes-list-map-keys:
  - type
x-kubernetes-list-type: map

Field	Type	Required in parent	Schema default	Description
`status.conditions[]`	object	no	none	Condition contains details for one aspect of the current state of this API Resource.

Field	Type	Required in parent	Schema default	Description
`status.conditions[].lastTransitionTime`	string	yes	none	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

Validation for status.conditions[].lastTransitionTime:

format: date-time

Field	Type	Required in parent	Schema default	Description
`status.conditions[].message`	string	yes	none	message is a human readable message indicating details about the transition. This may be an empty string.

Validation for status.conditions[].message:

maxLength: 32768

Field	Type	Required in parent	Schema default	Description
`status.conditions[].observedGeneration`	integer	no	none	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

Validation for status.conditions[].observedGeneration:

format: int64
minimum: 0

Field	Type	Required in parent	Schema default	Description
`status.conditions[].reason`	string	yes	none	reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.

Validation for status.conditions[].reason:

maxLength: 1024
minLength: 1
pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

Field	Type	Required in parent	Schema default	Description
`status.conditions[].status`	string	yes	none	status of the condition, one of True, False, Unknown.

Allowed values for status.conditions[].status: ["True","False","Unknown"].

Field	Type	Required in parent	Schema default	Description
`status.conditions[].type`	string	yes	none	type of condition in CamelCase or in foo.example.com/CamelCase.

Validation for status.conditions[].type:

maxLength: 316
pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

Field	Type	Required in parent	Schema default	Description
`status.connectedRouteCount`	integer	no	none	ConnectedRouteCount is the number of routes connected to this tunnel.

Validation for status.connectedRouteCount:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.lastFullReconcileTime`	string	no	none	LastFullReconcileTime is the last successful credentials, tunnel, deployment, and configuration reconciliation. Configuration-only reconciliations do not advance this timestamp.

Validation for status.lastFullReconcileTime:

format: date-time

Field	Type	Required in parent	Schema default	Description
`status.lastSyncTime`	string	no	none	LastSyncTime is the last time the configuration was synced to Cloudflare.

Validation for status.lastSyncTime:

format: date-time

Field	Type	Required in parent	Schema default	Description
`status.lifecycleDependencyHash`	string	no	none	LifecycleDependencyHash identifies the Secret revisions and Deployment generation checked during the last full reconciliation. It contains no Secret data.

Field	Type	Required in parent	Schema default	Description
`status.observedGeneration`	integer	no	none	ObservedGeneration is the generation observed by the controller.

Validation for status.observedGeneration:

format: int64

Field	Type	Required in parent	Schema default	Description
`status.readyReplicas`	integer	no	none	ReadyReplicas is the number of ready cloudflared replicas.

Validation for status.readyReplicas:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.replicas`	integer	no	none	Replicas is the total number of cloudflared replicas.

Validation for status.replicas:

format: int32

Field	Type	Required in parent	Schema default	Description
`status.tunnelDomain`	string	no	none	TunnelDomain is the tunnel’s CNAME target domain (e.g., {tunnelId}.cfargotunnel.com).

Field	Type	Required in parent	Schema default	Description
`status.tunnelId`	string	no	none	TunnelID is the Cloudflare tunnel ID.

Field	Type	Required in parent	Schema default	Description
`status.tunnelName`	string	no	none	TunnelName is the Cloudflare tunnel name.