Image

A build recipe Fleet turns into a runnable image, and its build status.

On this page: Object · REST · SDK

The image object#

The full Image resource. apiVersion: images.cua.ai/v1alpha1, kind: Image. The same resource cua image build reads from image.json.

Fleet does not build kind: container recipes yet: a cloud Image with layers fails with a clear error. Build it locally and push it to a registry instead.

Metadata and spec#

Field	Type	Default	Description
`metadata.annotations`	`map of string`	none	Annotations on the Image resource.
`metadata.labels`	`map of string`	none	Labels on the Image resource.
`metadata.name`	`string`	required	Image name: a DNS label. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`.
`metadata.namespace`	`string`	required	Namespace the image belongs to. 1 to 63 characters. Matches `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`.
`spec.build`	`object`	none	Build resources and limits.
`spec.build.diskSize`	`string`	`"40Gi"`	Disk size of the build machine (default `40Gi`). Matches `^[1-9][0-9]*(Gi\|Ti)$`.
`spec.build.timeoutSeconds`	`integer`	`7200`	Build budget in seconds (default 7200). 60 to 86400.
`spec.metadata`	`object`	none	Free-form metadata kept with the image.
`spec.metadata.tags`	`map of string`	none	Tags, as key-value pairs.
`spec.recipe`	`object`	required	What to build.
`spec.recipe.distro`	`string`	required	Distribution of the base, for example `ubuntu`. 1 to 64 characters.
`spec.recipe.env`	`map of string`	none	Environment variables of the image.
`spec.recipe.files`	`object[]`	none	Uploaded files copied into the image. At most 128 items.
`spec.recipe.files[].destination`	`string`	required	Absolute path in the image. At most 4096 characters. Matches `^/.*`.
`spec.recipe.files[].source`	`object`	required	The uploaded file.
`spec.recipe.files[].source.digest`	`string`	required	SHA-256 digest of the file. Matches `^sha256:[0-9a-f]{64}$`.
`spec.recipe.files[].source.reference`	`string`	required	Upload reference from the image upload API (`uploads/<namespace>/<id>`). 1 to 2048 characters. Matches `^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$`.
`spec.recipe.files[].source.sizeBytes`	`integer`	required	Size in bytes. At least 0.
`spec.recipe.from`	`string`	none	Registry base image (`kind: container`): layers are built on top of it and the result is an OCI rootfs. 1 to 1024 characters.
`spec.recipe.fromPullSecret`	`string`	none	A `cua-registry-` pull Secret in this namespace for a private base. At most 253 characters. Matches `^cua-registry-[a-z0-9]([-a-z0-9][a-z0-9])?$`.
`spec.recipe.kind`	`"vm" \| "container"`	required	`vm`: a VM disk image. `container`: an OCI rootfs built on `from`.
`spec.recipe.layers`	`object[]`	required	Build steps, run in order. At most 128 items.
`spec.recipe.osType`	`"linux"`	required	Guest OS family.
`spec.recipe.ports`	`integer[]`	none	Ports the image exposes. At most 32 items.
`spec.recipe.version`	`string`	required	Distribution version, for example `24.04`. 1 to 64 characters.

Status#

Set by Fleet; read-only.

Field	Type	Default	Description
`status.artifacts`	`object`	none	What the build produced.
`status.artifacts.oci`	`object`	none	The built OCI image.
`status.artifacts.oci.digest`	`string`	required	Image digest. Matches `^sha256:[0-9a-f]{64}$`.
`status.artifacts.oci.reference`	`string`	required	Image reference. 1 to 2048 characters.
`status.artifacts.volumeSnapshot`	`object`	none	The built VM disk, as a volume snapshot.
`status.artifacts.volumeSnapshot.name`	`string`	required	Name of the snapshot. 1 to 253 characters.
`status.artifacts.volumeSnapshot.namespace`	`string`	required	Namespace of the snapshot. 1 to 63 characters.
`status.buildIdentity`	`string`	none	Identifier of the build run. At most 63 characters.
`status.conditions`	`object[]`	none	Kubernetes-style conditions of the build.
`status.conditions[].lastTransitionTime`	`string`	required	When the condition last changed (RFC 3339).
`status.conditions[].message`	`string`	none	Human-readable detail. At most 32768 characters.
`status.conditions[].observedGeneration`	`integer`	none	The spec generation the condition describes. At least 0.
`status.conditions[].reason`	`string`	required	Machine-readable reason. 1 to 128 characters.
`status.conditions[].status`	`"True" \| "False" \| "Unknown"`	required	`True`, `False` or `Unknown`.
`status.conditions[].type`	`string`	required	Condition type. 1 to 64 characters.
`status.logs`	`object`	none	Where the build log is.
`status.logs.livePodName`	`string`	none	Pod that streams the log while the build runs. At most 253 characters.
`status.logs.retainedReference`	`string`	none	Where the log is kept after the build. At most 2048 characters.
`status.observedGeneration`	`integer`	none	The spec generation this status describes. At least 0.
`status.phase`	`"Pending" \| "Validating" \| "Building" \| "PushingOCI" \| "Importing" \| "Quiescing" \| "Snapshotting" \| "Ready" \| "Failed" \| "Cancelling"`	none	Build phase.
`status.recipeDigest`	`string`	none	Digest of the recipe that was built. Matches `^sha256:[0-9a-f]{64}$`.

Layer types#

spec.recipe.layers[] holds build steps, each tagged by type.

`type`	Fields
`apt_install`	`packages` `string[]`
`pip_install`	`packages` `string[]`
`uv_install`	`packages` `string[]`
`app_install`	`appId` `string`
`run`	`command` `string`

REST#

Create image#

POST /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.

Body: the image object (application/json).

Returns: 201 with the image object.

Errors: 401, 403, 502 (Errors).

List images#

GET /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.

Returns: 200 with {"items": [...]}, a list of the image object.

Errors: 401, 403, 502 (Errors).

Get image#

GET /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images/{name}

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.
`name`	path	The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).

Returns: 200 with the image object.

Errors: 401, 403, 502 (Errors).

Delete image#

DELETE /api/k8s/apis/images.cua.ai/v1alpha1/namespaces/{namespace}/images/{name}

Parameter	In	Description
`namespace`	path	The pool's namespace. A pool, its namespace and its template share one name.
`name`	path	The object name: a DNS label (lowercase letters, digits and `-`, at most 63 characters).

Returns: 200, 202, 204 with no body.

404 is treated as success: the object is already gone.

Errors: 401, 403, 502 (Errors).

Presign image uploads#

POST /api/image-uploads/presign

Body (application/json): namespace (string), files (object[]). Each of files[] has digest (string), sizeBytes (integer), name (string): the file's SHA-256 digest, size and name.

Returns: 200 with files[], one instruction per file: digest (string), sizeBytes (integer), reference (string), upload (object). reference is what an image recipe's files[].source.reference names. upload (method (string), url (string), headers (map of string)) is a presigned request to send the bytes with; it is absent when Fleet already has the file.

Errors: see Errors.

SDK#

Methods of the Fleet handle (cua.fleet()), with signatures in every language in the Cua SDK reference.

Method	Returns	Description
`Fleet.create_image(namespace, manifest_json)`	`string`	Creates an image resource (remote build) from a JSON manifest.
`Fleet.list_images(namespace)`	`string[]`	Lists image resources (JSON) in a namespace.
`Fleet.get_image(namespace, name)`	`string`	Gets an image resource (JSON).
`Fleet.delete_image(namespace, name)`	none	Deletes an image resource.