CelldFleet API reference

A CelldFleet describes one celld fleet in a namespace: its profile, replica target, storage bucket, placement, optional capacity policy and maintenance requests. previews can be enabled once; its configuration is immutable thereafter. replicas, capacity, runtimeImage, maintenance and routing remain mutable. See the fleet API contract for semantics and the conditions reference for what status reports.

Field names, defaults, and validation rules come from the CRD. Required fields are marked below; optional fields can be omitted unless a validation rule requires them for your profile.

API group	celld.eric.dev
Version	v1alpha1
Kind	CelldFleet
Scope	Namespaced
Subresources	scale, status

CelldFleet supports serialized capacity and maintenance requests. The /scale subresource declared below exposes spec.replicas for external capacity mode.

Printer columns

Column	JSON path	Type
Ready	.status.readyReplicas	integer

Object-level validation

Validation rules and expressions

• fleet name must be a DNS label of at most 40 characters

  size(self.metadata.name) <= 40 && self.metadata.name.matches('^[a-z0-9]([-a-z0-9]*[a-z0-9])?$')

spec

Field	Type	Required	Description
bucketWorkload	string		Bucket workload layout. Defaults to Deployment; Ordered uses deterministic ordinal removal. Layout is immutable. One of Deployment, Ordered. Default "Deployment".
capacity	object		Optional policy; omission keeps manual ownership.
env	[]object		Additional celld settings. A change rolls the fleet one member at a time. Secret values stay in the referenced Secret; changes to Secret data take effect only in new Pods. Items 0–32.
execution	object		Per-fleet runtime sizing. A change rolls the fleet one member at a time. Omitted fields keep the prototype constants.
export	object		Optional change export of the cells’ SQLite changes; omission leaves it disabled. Needs a celld with change export. Adding, changing or removing it rolls members one at a time; only cells activated on a member that exports are exported, so backfill cells activated before the change.
lifecycle	object		Per-fleet shutdown and termination budgets. A change rolls the fleet one member at a time.
maintenance	object		Pause workload changes or request a rolling same-version restart.
mesh	object		Optional service mesh membership. Adding or removing it rolls members one at a time; until every member matches, the peer port accepts plaintext from any source the fleet NetworkPolicy admits. The settings inside change only the NetworkPolicy and AuthorizationPolicy.
placement	object	yes	Allowed availability zones and scheduling strictness. Immutable after creation.
previews	object		Optional immutable configuration for previews referencing this fleet.
profile	string	yes	Storage profile: Bucket uses temporary local disk and S3; PersistentFleet gives each member a persistent disk it keeps until the fleet is deleted. Immutable after creation. One of Bucket, PersistentFleet.
replicas	int32		Manual replica target. Capacity policy can choose a different applied count without editing this field. Must cover every configured availability zone. Default 3. Range 1–100.
routing	object		Optional public HTTP routing. Mutable without restarting the runtime. Omission removes operator-owned routes and their separate ingress policy.
runtimeImage	string		Requested immutable runtime digest. Required for provisioning; no default release is assumed. Use a homogeneous compatible fork; verify release and recovery compatibility. Pattern `^([a-z0-9]+([.-][a-z0-9]+)*
serviceAccountName	string	yes	Existing ServiceAccount in the fleet namespace with the runtime bucket permissions. Immutable after creation. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
storage	object	yes	Reserved object-store scope and local disk settings. Immutable after creation.
telemetry	object		Optional OTLP collector; omission leaves telemetry disabled. A change rolls the fleet one member at a time.

Validation rules and expressions

• preview configuration cannot change once enabled

  !has(oldSelf.previews) || (has(self.previews) && self.previews == oldSelf.previews)

• runtime storage, layout and placement are fixed at creation

  self.profile == oldSelf.profile && self.serviceAccountName == oldSelf.serviceAccountName && self.storage == oldSelf.storage && self.placement == oldSelf.placement && self.bucketWorkload == oldSelf.bucketWorkload

• preview storage must use a separate bucket from the parent runtime

  !has(self.previews) || self.previews.storage.bucket != self.storage.bucket

• export must not write to the preview bucket

  !has(self.previews) || !has(self.export) || !has(self.export.bucket) || !has(self.export.bucket.name) || self.export.bucket.name != self.previews.storage.bucket

• shared prefixes and scratch overrides require Bucket profile

  self.profile == 'Bucket' || (!has(self.storage.prefix) && !has(self.storage.scratch))

• Ordered bucketWorkload requires Bucket profile

  self.bucketWorkload != 'Ordered' || self.profile == 'Bucket'

• azCount must equal the zones count

  self.placement.azCount == size(self.placement.zones)

• replicas must be at least azCount

  self.replicas >= self.placement.azCount

• storageClassName is required only for PersistentFleet

  self.profile == 'PersistentFleet' ? has(self.storage.storageClassName) && size(self.storage.storageClassName) > 0 : !has(self.storage.storageClassName)

• zones must be standard AZ names in storage.region

  self.placement.zones.all(z, z.startsWith(self.storage.region) && size(z) == size(self.storage.region) + 1 && z.matches('.*[a-z]$'))

• capacity minimum must cover requested AZs

  !has(self.capacity) || self.capacity.minReplicas >= self.placement.azCount

spec.capacity

Optional policy; omission keeps manual ownership.

Field	Type	Required	Description
cpuHighMillicores	int32		Absolute per-container CPU threshold for high demand, in millicores; not a percentage of resource requests. Default 200. Range 1–1000000.
cpuLowMillicores	int32		Absolute per-container CPU threshold for low demand, in millicores. Default 80. Range 1–1000000.
maxAgeSeconds	int32		Maximum allowed observation age and gap between observations. Default 45. Range 10–600.
maxReplicas	int32		Policy ceiling for automatic additions. Manual overrides can exceed policy bounds. Default 10. Range 1–100.
maxWindowSeconds	int32		Maximum accepted Metrics Server CPU averaging window. Default 60. Range 5–300.
memoryHighMiB	int32		Per-container Metrics Server memory threshold for high demand, in MiB. Default 768. Range 1–1048576.
memoryLowMiB	int32		Per-container Metrics Server memory threshold for low demand, in MiB. Default 384. Range 1–1048576.
minReplicas	int32		Policy replica floor; must cover every configured availability zone. Manual overrides can exceed policy bounds. Default 3. Range 1–100.
minSamples	int32		Distinct advancing observations required in a stabilization window. Default 3. Range 2–100.
minWindowSeconds	int32		Minimum accepted Metrics Server CPU averaging window. Default 5. Range 1–60.
mode	string		Shadow reports recommendations only. ScaleOut permits bounded additions. Automatic also requests removals, which remain disabled against production evidence. External hands spec.replicas to one /scale writer (typically an HPA); the built-in policy computes nothing and the other policy fields are ignored. One of Shadow, ScaleOut, Automatic, External. Default "Shadow".
provisioningTimeoutSeconds	int32		Time allowed for requested capacity to become useful before further additions are held. Default 600. Range 60–86400.
redistributionObservationSeconds	int32		Continuous complete observation after an addition before judging redistribution. Default 120. Range 30–3600.
sampleIntervalSeconds	int32		Minimum interval between counted observations. Default 15. Range 5–300.
scaleInCooldownSeconds	int32		Minimum wait after a durable action before an automatic removal request. Default 900. Range 60–86400.
scaleInStabilizationSeconds	int32		Continuous low-demand duration required before a policy removal recommendation. Default 600. Range 60–86400.
scaleOutCooldownSeconds	int32		Minimum wait after a durable action before another automatic addition. Default 300. Range 30–86400.
scaleOutStabilizationSeconds	int32		Continuous high-demand duration required before a policy addition. Default 30. Range 10–3600.
scaleOutStep	int32		Maximum replicas added in one completed stable policy decision. Default 1. Range 1–10.

Validation rules and expressions

• invalid replica bounds

  self.minReplicas <= self.maxReplicas

• low thresholds must be below high thresholds

  self.cpuLowMillicores < self.cpuHighMillicores && self.memoryLowMiB < self.memoryHighMiB

• invalid sampling windows

  self.minWindowSeconds <= self.maxWindowSeconds && self.sampleIntervalSeconds <= self.maxAgeSeconds

spec.env[]

Field	Type	Required	Description
name	string	yes	Length 0–128. Pattern ^CELLD_[A-Z][A-Z0-9_]*$.
secretKeyRef	object		Secret in the same namespace as the fleet.
value	string		Literal, including an empty string. Use secretKeyRef for credentials. Length 0–4096.

Validation rules and expressions

• exactly one of value or secretKeyRef is required

  has(self.value) != has(self.secretKeyRef)

spec.env[].secretKeyRef

Secret in the same namespace as the fleet.

Field	Type	Required	Description
key	string	yes	Length 1–253. Pattern ^[-._a-zA-Z0-9]+$.
name	string	yes	Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.

spec.execution

Per-fleet runtime sizing. A change rolls the fleet one member at a time. Omitted fields keep the prototype constants.

Field	Type	Required	Description
cpuLimit	string		CPU limit for the celld container. Default: none. Pattern ^[0-9]+(\.[0-9]+)?m?$.
cpuRequest	string		CPU request for the celld container (Kubernetes quantity). Default 250m for fleets, 25m for preview pools. Pattern ^[0-9]+(\.[0-9]+)?m?$.
idleEvictSeconds	int32		Seconds after which an idle resident cell hibernates (CELLD_IDLE_EVICT_S). Unset leaves only pressure and the residency cap to evict idle cells. Range 1–86400.
maxResidentCells	int32		Hard resident-cell admission limit (CELLD_MAX_RESIDENT_CELLS). Unset leaves the runtime default. Range 1–1000000.
memoryLimit	string		Memory limit for the celld container. Default 1Gi for fleets, 256Mi for preview pools. Pattern `^[0-9]+(.[0-9]+)?(Ki
memoryRequest	string		Memory request for the celld container. Default 512Mi for fleets, 64Mi for preview pools. Pattern `^[0-9]+(.[0-9]+)?(Ki

Validation rules and expressions

• cpuLimit must be at least cpuRequest

  !has(self.cpuLimit) || !has(self.cpuRequest) || quantity(self.cpuLimit).isGreaterThan(quantity(self.cpuRequest)) || quantity(self.cpuLimit).compareTo(quantity(self.cpuRequest)) == 0

• memoryLimit must be at least memoryRequest

  !has(self.memoryLimit) || !has(self.memoryRequest) || quantity(self.memoryLimit).isGreaterThan(quantity(self.memoryRequest)) || quantity(self.memoryLimit).compareTo(quantity(self.memoryRequest)) == 0

spec.export

Optional change export of the cells’ SQLite changes; omission leaves it disabled. Needs a celld with change export. Adding, changing or removing it rolls members one at a time; only cells activated on a member that exports are exported, so backfill cells activated before the change.

Field	Type	Required	Description
bucket	object		Bucket sink settings.
classes	[]string		Durable Object classes to export (CELLD_EXPORT_CLASSES). Unset exports every application class plus D1 databases and KV namespaces. Queue brokers, Workflow instances and cron cells are never exported. Items 0–64.
excludeTables	[]string		Tables never exported, as Class.table (CELLD_EXPORT_TABLES). Items 0–128.
kafka	object		Kafka sink settings, required with the Kafka sink.
maxRecordBytes	int64		Fragment size (CELLD_EXPORT_MAX_RECORD_BYTES). celld default 1048576. Range 1–.
maxTransactionBytes	int64		Capture memory above which a transaction is exported as bulk (CELLD_EXPORT_MAX_TX_BYTES). celld default 4194304. Range 1–.
queueBytes	int64		Shared memory budget for commits waiting on durability and records waiting on the sink (CELLD_EXPORT_QUEUE_BYTES). celld default 268435456; size the memory limit for it. Range 1–.
sink	string		Where records go: Bucket writes Parquet objects to the export bucket; Kafka produces to a topic and needs a celld built with the export-kafka feature. One of Bucket, Kafka. Default "Bucket".

Validation rules and expressions

• kafka is required with the Kafka sink and only valid with it; bucket is only valid with the Bucket sink

  self.sink == 'Kafka' ? has(self.kafka) && !has(self.bucket) : !has(self.kafka)

• maxRecordBytes must not exceed queueBytes

  !has(self.maxRecordBytes) || !has(self.queueBytes) || self.maxRecordBytes <= self.queueBytes

spec.export.bucket

Bucket sink settings.

Field	Type	Required	Description
flushBytes	int64		Buffered bytes that trigger an early flush (CELLD_EXPORT_FLUSH_BYTES). celld default 8388608. Range 1–.
flushMilliseconds	int64		Flush interval and watermark cadence (CELLD_EXPORT_FLUSH_MS). celld default 10000. Range 1–.
name	string		A bucket for the export other than the fleet bucket, on the same endpoint and credentials (CELLD_EXPORT_BUCKET). The fleet’s ServiceAccount must be able to write it. Length 3–63. Pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$.
retentionDays	int32		Days after which a node deletes its export objects (CELLD_EXPORT_RETENTION). Unset leaves the lifecycle to the bucket. Range 1–36500.

spec.export.kafka

Kafka sink settings, required with the Kafka sink.

Field	Type	Required	Description
brokers	[]string	yes	Bootstrap servers as host:port (CELLD_EXPORT_KAFKA_BROKERS). Items 1–16.
egress	object	yes	The brokers, for one TCP egress rule on the brokers’ ports: labeled broker Pods, or a cidr that may be a whole network, such as a managed cluster’s subnets.
propertiesSecretKeyRef	object		Same-namespace Secret key holding librdkafka properties (TLS, SASL, compression), one name=value per line, read as CELLD_EXPORT_KAFKA_PROPERTIES. Every key of the Secret is mounted read-only under /etc/celld/export, so the properties can name files the same Secret carries, such as ssl.ca.location=/etc/celld/export/ca.crt.
retryMilliseconds	int64		How long the sink retries a record before it counts as dropped (CELLD_EXPORT_RETRY_MS). celld default 30000. Range 1–.
topic	string		The topic (CELLD_EXPORT_TOPIC). celld default celld-changes. Create it first; the sink never creates it. Length 0–249. Pattern ^[a-zA-Z0-9._-]+$.

spec.export.kafka.egress

The brokers, for one TCP egress rule on the brokers’ ports: labeled broker Pods, or a cidr that may be a whole network, such as a managed cluster’s subnets.

Field	Type	Required	Description
cidr	string		Single collector address, /32 for IPv4 or /128 for IPv6.
namespace	string		Collector namespace; only valid with podLabels.
podLabels	map[string]string		Labels on collector pods. A namespace is optional for same-namespace pods.

Validation rules and expressions

• exactly one of cidr or podLabels is required

  has(self.cidr) != has(self.podLabels)

spec.export.kafka.propertiesSecretKeyRef

Same-namespace Secret key holding librdkafka properties (TLS, SASL, compression), one name=value per line, read as CELLD_EXPORT_KAFKA_PROPERTIES. Every key of the Secret is mounted read-only under /etc/celld/export, so the properties can name files the same Secret carries, such as ssl.ca.location=/etc/celld/export/ca.crt.

Field	Type	Required	Description
key	string	yes	Length 1–253. Pattern ^[-._a-zA-Z0-9]+$.
name	string	yes	Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.

spec.lifecycle

Per-fleet shutdown and termination budgets. A change rolls the fleet one member at a time.

Field	Type	Required	Description
shutdownSeconds	int32		celld total stop bound in seconds (CELLD_SHUTDOWN_TOTAL_MS). Default 20. Range 1–3600.
terminationGraceSeconds	int32		Pod terminationGracePeriodSeconds. Default 30. Must exceed shutdownSeconds by 5. Range 6–3605.

Validation rules and expressions

• terminationGraceSeconds must exceed shutdownSeconds by at least 5

  !has(self.shutdownSeconds) || !has(self.terminationGraceSeconds) || self.shutdownSeconds + 5 <= self.terminationGraceSeconds

• shutdownSeconds above 25 requires an explicit terminationGraceSeconds

  !has(self.shutdownSeconds) || has(self.terminationGraceSeconds) || self.shutdownSeconds + 5 <= 30

• terminationGraceSeconds must be at least 25 with the default 20 second shutdown

  has(self.shutdownSeconds) || !has(self.terminationGraceSeconds) || self.terminationGraceSeconds >= 25

spec.maintenance

Pause workload changes or request a rolling same-version restart.

Field	Type	Required	Description
allowCoordinatedDowntime	boolean		Deprecated and ignored: restarts and upgrades replace one member at a time and need no downtime permission (ADR 0023).
paused	boolean		Stop applying workload changes. A rollout the workload controller has already started continues.
restartToken	string		Change to a new nonempty token to request a rolling same-version restart. The token is written to the Pod template, so a completed restart is not replayed. Length 0–128.

spec.mesh

Optional service mesh membership. Adding or removing it rolls members one at a time; until every member matches, the peer port accepts plaintext from any source the fleet NetworkPolicy admits. The settings inside change only the NetworkPolicy and AuthorizationPolicy.

Field	Type	Required	Description
istio	object	yes	Istio sidecar mode. Members get an injected sidecar, egress to istiod and an operator-owned AuthorizationPolicy, so they keep working under STRICT mTLS and alongside your own AuthorizationPolicies.

spec.mesh.istio

Istio sidecar mode. Members get an injected sidecar, egress to istiod and an operator-owned AuthorizationPolicy, so they keep working under STRICT mTLS and alongside your own AuthorizationPolicies.

Field	Type	Required	Description
applicationAccess	string		Who may call the application port 8080. AllowAll adds an ALLOW rule for port 8080 from any source, matching a fleet outside the mesh. Policies leaves port 8080 to AuthorizationPolicies you write; until one allows a caller, Istio denies it. Default AllowAll. One of AllowAll, Policies.
controlPlaneNamespace	string		Namespace of the istiod Pods (label app=istiod) that serve sidecar configuration on TCP 15012. Default istio-system. Length 0–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.

spec.placement

Allowed availability zones and scheduling strictness. Immutable after creation.

Field	Type	Required	Description
azCount	int32	yes	Number of availability zones; must equal the number of entries in zones. Range 1–6.
mode	string		Strict requires zone balance and distinct hosts. Relaxed makes spread and host separation preferences while retaining the zone allowlist. One of Strict, Relaxed. Default "Strict".
zones	[]string	yes	Explicit zone allowlist; no automatic reselection when capacity changes. Items 1–6.

spec.previews

Optional immutable configuration for previews referencing this fleet.

Field	Type	Required	Description
execution	object		Omitted values use preview defaults: 25m CPU, 64Mi request, 256Mi limit, eight resident cells and 30-second idle eviction.
routing	object	yes
runtimeImage	string	yes	Immutable celld runtime digest, shared by the independent preview runtimes. Pattern `^([a-z0-9]+([.-][a-z0-9]+)*
scratch	object		Disk-backed scratch; defaults to a 64Mi request and 512Mi limit.
seeding	object		Opt-in source authorization and trusted executor for state seeding.
serviceAccountName	string	yes	Existing ServiceAccount in the pool/preview namespace. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
storage	object	yes
zone	string	yes	One allowed zone. Previews use a single replica and relaxed host placement. Length 1–33.

Validation rules and expressions

• zone must belong to the storage region

  self.zone.startsWith(self.storage.region) && size(self.zone) == size(self.storage.region) + 1 && self.zone.matches('.*[a-z]$')

spec.previews.execution

Omitted values use preview defaults: 25m CPU, 64Mi request, 256Mi limit, eight resident cells and 30-second idle eviction.

Field	Type	Required	Description
cpuLimit	string		CPU limit for the celld container. Default: none. Pattern ^[0-9]+(\.[0-9]+)?m?$.
cpuRequest	string		CPU request for the celld container (Kubernetes quantity). Default 250m for fleets, 25m for preview pools. Pattern ^[0-9]+(\.[0-9]+)?m?$.
idleEvictSeconds	int32		Seconds after which an idle resident cell hibernates (CELLD_IDLE_EVICT_S). Unset leaves only pressure and the residency cap to evict idle cells. Range 1–86400.
maxResidentCells	int32		Hard resident-cell admission limit (CELLD_MAX_RESIDENT_CELLS). Unset leaves the runtime default. Range 1–1000000.
memoryLimit	string		Memory limit for the celld container. Default 1Gi for fleets, 256Mi for preview pools. Pattern `^[0-9]+(.[0-9]+)?(Ki
memoryRequest	string		Memory request for the celld container. Default 512Mi for fleets, 64Mi for preview pools. Pattern `^[0-9]+(.[0-9]+)?(Ki

Validation rules and expressions

• cpuLimit must be at least cpuRequest

  !has(self.cpuLimit) || !has(self.cpuRequest) || quantity(self.cpuLimit).isGreaterThan(quantity(self.cpuRequest)) || quantity(self.cpuLimit).compareTo(quantity(self.cpuRequest)) == 0

• memoryLimit must be at least memoryRequest

  !has(self.memoryLimit) || !has(self.memoryRequest) || quantity(self.memoryLimit).isGreaterThan(quantity(self.memoryRequest)) || quantity(self.memoryLimit).compareTo(quantity(self.memoryRequest)) == 0

spec.previews.routing

Field	Type	Required	Description
baseDomain	string	yes	Wildcard DNS for this domain must point to the Gateway or Ingress controller. Length 1–218. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
gateway	object
ingress	object
scheme	string		HTTPS requires a TLS listener on a Gateway or a wildcard TLS Secret for Ingress. One of http, https. Default "https".
source	object	yes

Validation rules and expressions

• choose exactly one of gateway or ingress

  has(self.gateway) != has(self.ingress)

• HTTPS ingress requires a TLS secret

  self.scheme != 'https' || !has(self.ingress) || has(self.ingress.tlsSecretName)

spec.previews.routing.gateway

Field	Type	Required	Description
name	string	yes	Name of an existing Gateway. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
namespace	string		Gateway namespace. Omission uses the fleet namespace. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
sectionName	string		Listener name. Omission attaches to compatible listeners. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.

spec.previews.routing.ingress

Field	Type	Required	Description
annotations	map[string]string		Controller-specific annotations, including optional cert-manager settings. Treat permission to configure these as privileged ingress administration.
className	string	yes	Explicit installed IngressClass. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
tlsSecretName	string		TLS Secret in the fleet namespace, covering every configured hostname. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.

spec.previews.routing.source

Field	Type	Required	Description
namespace	string	yes	Exact namespace containing the gateway or ingress data-plane pods. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
podLabels	map[string]string	yes	Nonempty matchLabels selector in that namespace.

spec.previews.scratch

Disk-backed scratch; defaults to a 64Mi request and 512Mi limit.

Field	Type	Required	Description
limit	string	yes	Length 0–32. Pattern `^[0-9]+(.[0-9]+)?(Ki
request	string	yes	Length 0–32. Pattern `^[0-9]+(.[0-9]+)?(Ki

Validation rules and expressions

• scratch limit must cover request

  quantity(self.limit).compareTo(quantity(self.request)) >= 0

• scratch request must be positive

  quantity(self.request).compareTo(quantity('0')) > 0

spec.previews.seeding

Opt-in source authorization and trusted executor for state seeding.

Field	Type	Required	Description
executor	string	yes	Trusted executor implementation that understands the seed request protocol. The operator does not install this executor or grant it source credentials. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
sources	[]object	yes	Items 1–32.

spec.previews.seeding.sources[]

Field	Type	Required	Description
fleetRef	object	yes
name	string	yes	Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.

spec.previews.seeding.sources[].fleetRef

Field	Type	Required	Description
name	string	yes	Length 1–40. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
namespace	string	yes	Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
uid	string	yes	Exact authorized fleet identity; recreating a name never transfers access. Length 1–64.

spec.previews.storage

Field	Type	Required	Description
bucket	string	yes	Existing bucket dedicated to this pool; the operator does not create or delete it. Length 3–63. Pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$.
endpoint	object		Omit for AWS S3 with ServiceAccount credentials. Set for a shared local store.
region	string	yes	Length 0–32. Pattern ^[a-z]{2}(-[a-z]+)+-[0-9]+$.

spec.previews.storage.endpoint

Omit for AWS S3 with ServiceAccount credentials. Set for a shared local store.

Field	Type	Required	Description
credentialsSecretName	string	yes	Same-namespace Secret with accessKeyId and secretAccessKey keys. Values are injected by kubelet, never read into controller status. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
egress	object	yes	Narrow object-store destination, independent of fleet peer ingress.
url	string	yes	HTTP(S) origin only. HTTP explicitly opts into plaintext transport. Length 0–512. Pattern ^https?://[^/?#@]+/?$.

spec.previews.storage.endpoint.egress

Narrow object-store destination, independent of fleet peer ingress.

Field	Type	Required	Description
cidr	string		Single collector address, /32 for IPv4 or /128 for IPv6.
namespace	string		Collector namespace; only valid with podLabels.
podLabels	map[string]string		Labels on collector pods. A namespace is optional for same-namespace pods.

Validation rules and expressions

• exactly one of cidr or podLabels is required

  has(self.cidr) != has(self.podLabels)

spec.routing

Optional public HTTP routing. Mutable without restarting the runtime. Omission removes operator-owned routes and their separate ingress policy.

Field	Type	Required	Description
gateway	object		Attach an HTTPRoute to an existing Gateway. TLS belongs to its listener.
hostnames	[]string	yes	Explicit hostnames; no catch-all route is created. Items 1–16.
ingress	object		Create a networking.k8s.io/v1 Ingress using an installed controller.
source	object	yes	Pods that originate application traffic, not the control-plane controller.

Validation rules and expressions

• choose exactly one of gateway or ingress

  has(self.gateway) != has(self.ingress)

spec.routing.gateway

Attach an HTTPRoute to an existing Gateway. TLS belongs to its listener.

Field	Type	Required	Description
name	string	yes	Name of an existing Gateway. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
namespace	string		Gateway namespace. Omission uses the fleet namespace. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
sectionName	string		Listener name. Omission attaches to compatible listeners. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.

spec.routing.ingress

Create a networking.k8s.io/v1 Ingress using an installed controller.

Field	Type	Required	Description
annotations	map[string]string		Controller-specific annotations, including optional cert-manager settings. Treat permission to configure these as privileged ingress administration.
className	string	yes	Explicit installed IngressClass. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.
tlsSecretName	string		TLS Secret in the fleet namespace, covering every configured hostname. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$.

spec.routing.source

Pods that originate application traffic, not the control-plane controller.

Field	Type	Required	Description
namespace	string	yes	Exact namespace containing the gateway or ingress data-plane pods. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
podLabels	map[string]string	yes	Nonempty matchLabels selector in that namespace.

spec.storage

Reserved object-store scope and local disk settings. Immutable after creation.

Field	Type	Required	Description
bucket	string	yes	S3 bucket permanently reserved to this fleet, or to the referenced preview pool. Length 3–63. Pattern ^[a-z0-9][a-z0-9-]*[a-z0-9]$.
endpoint	object
initialization	object		One-time startup gate, bound to an operator-owned seed request.
prefix	string		Single segment within a pool-owned bucket. Nested/overlapping prefixes are forbidden. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
previewFleetRef	object		Pool identity, permanently bound by the whole-bucket reservation.
region	string	yes	AWS region containing the bucket and the configured availability zones. Length 0–32. Pattern ^[a-z]{2}(-[a-z]+)+-[0-9]+$.
scratch	object		Disk-backed emptyDir request and limit; overrides sizeGiB only for Bucket.
sizeGiB	int32		Disk space in GiB: PVC size for PersistentFleet, disk-backed emptyDir limit for Bucket. Default 10. Range 1–16384.
storageClassName	string		Required only for PersistentFleet; must reference an existing CSI Delete/WaitForFirstConsumer class. Each member keeps its disk across restart, upgrade and scale-in; disks are deleted with the fleet. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.

Validation rules and expressions

• prefix and previewFleetRef must be supplied together

  has(self.prefix) == has(self.previewFleetRef)

• initialization requires a pool reservation

  !has(self.initialization) || has(self.previewFleetRef)

• custom endpoints require a pool reservation

  !has(self.endpoint) || has(self.previewFleetRef)

spec.storage.endpoint

Field	Type	Required	Description
credentialsSecretName	string	yes	Same-namespace Secret with accessKeyId and secretAccessKey keys. Values are injected by kubelet, never read into controller status. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
egress	object	yes	Narrow object-store destination, independent of fleet peer ingress.
url	string	yes	HTTP(S) origin only. HTTP explicitly opts into plaintext transport. Length 0–512. Pattern ^https?://[^/?#@]+/?$.

spec.storage.endpoint.egress

Narrow object-store destination, independent of fleet peer ingress.

Field	Type	Required	Description
cidr	string		Single collector address, /32 for IPv4 or /128 for IPv6.
namespace	string		Collector namespace; only valid with podLabels.
podLabels	map[string]string		Labels on collector pods. A namespace is optional for same-namespace pods.

Validation rules and expressions

• exactly one of cidr or podLabels is required

  has(self.cidr) != has(self.podLabels)

spec.storage.initialization

One-time startup gate, bound to an operator-owned seed request.

Field	Type	Required	Description
deadline	string	yes	Executor must stop before this time and must never begin after it. Format date-time.
executor	string	yes	Length 1–63.
selection	object	yes	PreviewSeedSpec selects persisted objects, copied once before runtime startup. Snapshots are consistent per object, not globally across the selection.
sourceFleet	object	yes
target	object	yes

spec.storage.initialization.selection

PreviewSeedSpec selects persisted objects, copied once before runtime startup. Snapshots are consistent per object, not globally across the selection.

Field	Type	Required	Description
alarms	string		Clear disables copied alarms. Preserve explicitly opts into scheduled work. One of Clear, Preserve. Default "Clear".
objects	[]object	yes	Items 1–100.
source	string	yes	Administrator-approved alias from the pool’s seeding.sources. Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.

spec.storage.initialization.selection.objects[]

Field	Type	Required	Description
class	string	yes	Exported Durable Object class, with the same mapping in the target application. Length 1–128. Pattern ^[A-Za-z0-9_$.-]+$.
id	string	yes	Canonical object ID, not an idFromName input or a storage path. Length 1–256. Pattern ^[A-Za-z0-9_$.-]+$.

spec.storage.initialization.sourceFleet

Field	Type	Required	Description
name	string	yes	Length 1–40. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
namespace	string	yes	Length 1–63. Pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$.
uid	string	yes	Exact authorized fleet identity; recreating a name never transfers access. Length 1–64.

spec.storage.initialization.target

Field	Type	Required	Description
fleetName	string	yes	Length 1–40.
previewFleetRef	object	yes
previewName	string	yes	Length 1–253.
previewUID	string	yes	Length 1–64.
storageURL	string	yes	Exact isolated S3 destination; no credentials. Length 0–133. Pattern ^s3://[a-z0-9-]+/[a-z0-9-]+$.

spec.storage.initialization.target.previewFleetRef

Field	Type	Required	Description
name	string	yes	Pool in the same namespace as the fleet. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
uid	string	yes	Exact pool UID; names alone cannot transfer a reservation. Length 1–64.

spec.storage.previewFleetRef

Pool identity, permanently bound by the whole-bucket reservation.

Field	Type	Required	Description
name	string	yes	Pool in the same namespace as the fleet. Length 1–253. Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.
uid	string	yes	Exact pool UID; names alone cannot transfer a reservation. Length 1–64.

spec.storage.scratch

Disk-backed emptyDir request and limit; overrides sizeGiB only for Bucket.

Field	Type	Required	Description
limit	string	yes	Length 0–32. Pattern `^[0-9]+(.[0-9]+)?(Ki
request	string	yes	Length 0–32. Pattern `^[0-9]+(.[0-9]+)?(Ki

Validation rules and expressions

• scratch limit must cover request

  quantity(self.limit).compareTo(quantity(self.request)) >= 0

• scratch request must be positive

  quantity(self.request).compareTo(quantity('0')) > 0

spec.telemetry

Optional OTLP collector; omission leaves telemetry disabled. A change rolls the fleet one member at a time.

Field	Type	Required	Description
collectorURL	string	yes	HTTP(S) collector base URL; celld appends /v1/traces and /v1/logs. Pattern ^https?://[^/?#@]+(/[^?#]*)?$.
egress	object	yes
flushBytes	int64		Range 1–.
flushMilliseconds	int64		Range 1–.
headersSecretKeyRef	object		Secret value contains comma-separated OTLP headers; it never enters status.
sampler	string		One of always_on, always_off, parentbased_always_on, parentbased_always_off, traceidratio, parentbased_traceidratio.
samplerArg	string		Decimal ratio in [0,1], serialized as a string for portable CRD clients. Pattern `^(0(.[0-9]+)?

Validation rules and expressions

• samplerArg is required only for ratio samplers

  has(self.sampler) && (self.sampler == 'traceidratio' || self.sampler == 'parentbased_traceidratio') ? has(self.samplerArg) : !has(self.samplerArg)

spec.telemetry.egress

Field	Type	Required	Description
cidr	string		Single collector address, /32 for IPv4 or /128 for IPv6.
namespace	string		Collector namespace; only valid with podLabels.
podLabels	map[string]string		Labels on collector pods. A namespace is optional for same-namespace pods.

Validation rules and expressions

• exactly one of cidr or podLabels is required

  has(self.cidr) != has(self.podLabels)

spec.telemetry.headersSecretKeyRef

Secret value contains comma-separated OTLP headers; it never enters status.

Field	Type	Required	Description
key	string	yes	Pattern ^[-._a-zA-Z0-9]+$.
name	string	yes	Pattern ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$.

status

Field	Type	Required	Description
application	object		Read-only application deployment observations, independent of lifecycle readiness.
appliedReplicas	int32		Replica target currently applied to the owned Kubernetes workload.
blockedSince	string		RFC3339 time when the fleet entered its current continuous Blocked state; empty when not blocked.
capacity	object		Latest capacity policy recommendation and observation coverage.
conditions	[]object		Current readiness, progress, blocked, and maintenance conditions.
desiredReplicas	int32		Enabled capacity-policy target, otherwise spec.replicas.
joiningReplicas	int32		Observed non-terminating Pods that are not ready yet.
labelSelector	string		Serialized selector for exactly this fleet’s Pods, for the /scale subresource.
lifecycle	object		Retained for compatibility with earlier releases; always empty.
observedGeneration	int64		Fleet metadata.generation reflected by this status update.
observedReplicas	int32		Number of owned Pods observed in the latest complete inventory, including terminating Pods.
readyReplicas	int32		Ready count from the owned workload status, provided it covers the current workload generation.
replicaObservationValid	boolean		Whether the Pod inventory was complete. False means counts must not be interpreted as proof of no running processes.
replicas	int32		Replicas and LabelSelector serve the /scale subresource: non-terminal pods of this fleet, including terminating ones, and the selector that matches exactly them. They never express permission to scale. Zero is serialized so the scale view always carries a count, but the schema does not require it: a status written before this field existed stays valid.
reservation	string		Name of the cluster-scoped storage reservation holding this fleet’s bucket ownership.
terminatingReplicas	int32		Observed Pods with a deletion timestamp.

status.application

Read-only application deployment observations, independent of lifecycle readiness.

Field	Type	Required	Description
expectedNodes	int32	yes
nodes	[]object		Items 0–100.
observedAt	string	yes	Format date-time.
observedNodes	int32	yes
observedVersion	object		Common loaded version; omitted when versions disagree or coverage is incomplete.
pendingCells	int64	yes	Counts from valid fresh observations only; incomplete coverage is Unknown.
swappingCells	int64	yes
unavailableNodes	int32	yes
versions	[]object		Items 0–100.

status.application.nodes[]

Field	Type	Required	Description
name	string	yes	Length 0–253.
reason	string	yes	Length 0–64.
runtimeGeneration	string		Length 0–128.
uid	string	yes	Length 0–128.
version	string		Length 0–256.

status.application.observedVersion

Common loaded version; omitted when versions disagree or coverage is incomplete.

Field	Type	Required	Description
prefix	string	yes	Length 0–1024.
version	string	yes	Length 0–256.

status.application.versions[]

Field	Type	Required	Description
nodes	int32	yes
prefix	string	yes	Length 0–1024.
version	string	yes	Length 0–256.

status.capacity

Latest capacity policy recommendation and observation coverage.

Field	Type	Required	Description
coveredReplicas	int32		Expected replicas covered by the current capacity observations.
desiredReplicas	int32		Recommended count; informational in Shadow mode and not necessarily the applied workload count.
message	string		Human-readable explanation of the latest recommendation or hold.
mode	string		Current capacity policy mode.
pendingReplicas	int32		Capacity requested but not yet observed as useful.
reason	string		Machine-readable explanation of the latest recommendation or hold.
usefulReplicas	int32		Observed replicas considered ready and useful by the capacity policy.

status.conditions[]

Condition contains details for one aspect of the current state of this API Resource.

Field	Type	Required	Description
lastTransitionTime	string	yes	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. Format date-time.
message	string	yes	message is a human readable message indicating details about the transition. This may be an empty string. Length 0–32768.
observedGeneration	int64		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. Range 0–.
reason	string	yes	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. Length 1–1024. Pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$.
status	string	yes	status of the condition, one of True, False, Unknown. One of True, False, Unknown.
type	string	yes	type of condition in CamelCase or in foo.example.com/CamelCase. Length 0–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])$.

status.lifecycle

Retained for compatibility with earlier releases; always empty.

Field	Type	Required	Description
blocker	string		Reason the current operation cannot progress.
deadline	string		RFC3339 operation deadline. Passing it reports a stall; it does not cancel recovery.
from	int32		Starting replica count of the active capacity operation.
lastCompletionAt	string		RFC3339 completion time of the last completed operation, when available.
lastOutcome	string		Outcome recorded in the last completed operation.
operationID	string		Identifier of the active capacity or maintenance operation.
phase	string		Current phase of the active operation; use the condition message for the next action.
requestID	string		Identifier or token of the current request.
requestKind	string		Kind of a current maintenance or runtime-transition request.
stalled	boolean		Whether the active operation has exceeded its persisted deadline.
startedAt	string		RFC3339 start time of the active operation, when available.
targetGeneration	string		Runtime session generation of the selected target.
targetImage	string		Requested runtime image of a current transition request.
targetPod	string		Pod selected for the active capacity operation, when applicable.
targetUID	string		Exact Kubernetes UID of the selected target Pod.
to	int32		Target replica count of the active capacity operation.