CelldStorageReservation API reference

A CelldStorageReservation is the cluster-scoped, never garbage-collected tombstone that binds a bucket to exactly one fleet identity. Its celld.eric.dev/current-operation annotation holds only capacity-policy state. The operator creates it; administrators read it. Never delete one to reuse a bucket or a retained disk. See PersistentFleet lifecycle and the exact disk contract.

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	CelldStorageReservation
Scope	Cluster
Subresources	status

CelldStorageReservation is a durable, cluster-wide tombstone. Never garbage collected.

Object-level validation

Validation rules and expressions

• terminal seed results cannot change

  !has(oldSelf.status) || !has(oldSelf.status.phase) || !(oldSelf.status.phase in ['Succeeded', 'Failed', 'Canceled']) || (has(self.status) && self.status == oldSelf.status)

• captured snapshot manifest cannot change or be removed

  !has(oldSelf.status) || !has(oldSelf.status.manifest) || (has(self.status) && has(self.status.manifest) && self.status.manifest == oldSelf.status.manifest)

• executor target identity cannot change

  !has(oldSelf.status) || !has(oldSelf.status.targetFleetUID) || (has(self.status) && has(self.status.targetFleetUID) && self.status.targetFleetUID == oldSelf.status.targetFleetUID)

• canceled seed requests cannot be claimed

  !has(self.status) || !has(self.status.phase) || self.status.phase != 'Running' || ((!has(self.status.canceled) || !self.status.canceled) && (!has(oldSelf.status) || !has(oldSelf.status.phase) || oldSelf.status.phase in ['Pending', 'Running'])) || (has(oldSelf.status) && has(oldSelf.status.phase) && oldSelf.status.phase == 'Running')

• success requires an uncanceled request, target identity and manifest

  !has(self.status) || !has(self.status.phase) || self.status.phase != 'Succeeded' || ((!has(self.status.canceled) || !self.status.canceled) && has(self.status.manifest) && has(self.status.targetFleetUID))

• executor claim requires execution and target identities

  !has(self.status) || !has(self.status.phase) || !(self.status.phase in ['Running', 'Succeeded']) || (has(self.status.executorID) && has(self.status.targetFleetUID))

• executor identity cannot change

  !has(oldSelf.status) || !has(oldSelf.status.executorID) || (has(self.status) && has(self.status.executorID) && self.status.executorID == oldSelf.status.executorID)

• success requires a previously claimed execution

  !has(self.status) || !has(self.status.phase) || self.status.phase != 'Succeeded' || (has(oldSelf.status) && has(oldSelf.status.phase) && oldSelf.status.phase in ['Running', 'Succeeded'])

• claimed requests cannot return to pending

  !has(oldSelf.status) || !has(oldSelf.status.phase) || oldSelf.status.phase != 'Running' || (has(self.status) && has(self.status.phase) && self.status.phase != 'Pending')

• seed cancellation cannot be removed or reversed

  !has(oldSelf.status) || !has(oldSelf.status.canceled) || !oldSelf.status.canceled || (has(self.status) && has(self.status.canceled) && self.status.canceled)

• executor must claim this reservation’s fleet UID

  !has(self.status) || !has(self.status.targetFleetUID) || self.status.targetFleetUID == self.spec.fleetUID

• seed status requires an initialization request

  !has(self.status) || !has(self.status.phase) || has(self.spec.initialization)

spec

Field	Type	Required	Description
bucket	string	yes	S3 bucket permanently bound to this reservation’s owner (and optional prefix).
endpoint	string		Custom object-store origin; bucket names remain globally reserved in this cluster.
fleetName	string	yes	Name of the fleet or pool that owns the reservation.
fleetNamespace	string	yes	Namespace of the fleet or pool that owns the reservation.
fleetUID	string	yes	Exact Kubernetes UID of the owning fleet or pool; reusing a name never transfers a reservation.
initialReplicas	int32		InitialReplicas binds the replica component of SpecHash before provisioning. Optional only for reservations created before this field existed. Range 1–100.
initialization	object		Immutable seed request for this exclusive preview destination.
ownerKind	string		Empty means CelldFleet for existing reservations. Pool reservations own the whole bucket. One of FleetPreviews.
prefix	string		Empty reserves the whole bucket. Nonempty reserves exactly one path segment.
specHash	string	yes	Fingerprint of the original immutable owner configuration used to detect conflicting reuse.

Validation rules and expressions

• storage reservations cannot be transferred or changed

  self == oldSelf

spec.initialization

Immutable seed request for this exclusive preview destination.

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.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.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.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.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.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.

status

Field	Type	Required	Description
canceled	boolean		Cancellation is monotonic and participates in the executor claim CAS.
executorID	string		Stable execution identity. Other workers cannot take over a Running request. Length 1–128.
manifest	object		Publish all snapshot identities atomically before importing any objects. The manifest is immutable and retained for repeatable retries and audit.
message	string		Bounded, non-sensitive progress or failure summary; never secret values. Length 0–1024.
phase	string		Running is an exclusive claim, published with resourceVersion before any I/O. Terminal phases certify there are no active or retryable writes left. One of Pending, Running, Succeeded, Failed, Canceled.
targetFleetUID	string		Exact destination fleet UID whose prefix reservation was verified by the executor. Length 1–64.

status.manifest

Publish all snapshot identities atomically before importing any objects. The manifest is immutable and retained for repeatable retries and audit.

Field	Type	Required	Description
objects	[]object	yes	Items 1–100.

status.manifest.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_$.-]+$.
digest	string	yes	SHA-256 of the exported snapshot payload. Length 0–64. Pattern ^[a-f0-9]{64}$.
id	string	yes	Canonical object ID, not an idFromName input or a storage path. Length 1–256. Pattern ^[A-Za-z0-9_$.-]+$.
snapshotID	string	yes	Opaque immutable snapshot handle understood by the executor, never a live source pointer. Length 1–256.
sourceVersion	string	yes	Committed source version captured for this object. Length 1–256.