Replace a Image
const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/images/example';const options = { method: 'PUT', headers: {'Content-Type': 'application/json'}, body: '{"apiVersion":"example","kind":"example","metadata":{"annotations":{"additionalProperty":"example"},"creationTimestamp":"example","deletionGracePeriodSeconds":1,"deletionTimestamp":"example","finalizers":["example"],"generateName":"example","generation":1,"labels":{"additionalProperty":"example"},"managedFields":[{"apiVersion":"example","fieldsType":"example","fieldsV1":{"additionalProperty":"example"},"manager":"example","operation":"example","subresource":"example","time":"example"}],"name":"example","namespace":"example","ownerReferences":[{"apiVersion":"example","blockOwnerDeletion":true,"controller":true,"kind":"example","name":"example","uid":"example"}],"resourceVersion":"example","selfLink":"example","uid":"example"},"spec":{"base":"example","buildSecrets":["example"],"dockerfile":{"blob":"example","buildArgs":{"additionalProperty":"example"},"context":"example","inline":"example","target":"example"},"fromSandbox":{"attempt":{"epoch":1,"name":"example"},"includePaths":["example"],"name":"example","uid":"example"},"imagePullSecrets":["example"],"platform":"example","python":"example","steps":[{"aptInstall":["example"],"copy":{"blob":"example","dest":"example"},"env":{"additionalProperty":"example"},"pipInstall":{"extraIndexURLs":["example"],"indexURL":"example","packages":["example"]},"run":["example"],"uvPipInstall":{"extraIndexURLs":["example"],"indexURL":"example","packages":["example"]},"uvSync":{"frozen":true,"project":"example"},"workdir":"example"}],"tags":["example"]},"status":{"build":{"attempt":"example","cached":true,"completionTime":"example","costUSD":"example","cpuSeconds":1,"startTime":"example"},"capture":{"attempt":{"epoch":1,"name":"example"},"base":"example","blob":"example","bytes":1,"completedAt":"example","deadline":"example","failed":true,"id":"example","node":"example","platform":"example","pullSecrets":["example"],"sandboxUID":"example"},"conditions":[{"lastTransitionTime":"example","message":"example","observedGeneration":1,"reason":"example","status":"example","type":"example"}],"digest":"example","message":"example","observedGeneration":1,"phase":"example","progress":{"stage":"example"},"python":"example","reason":"example","reference":"example","size":1,"specHash":"example","tags":{"additionalProperty":"example"}}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/apis/nodus.dev/v1/namespaces/example/images/example \ --header 'Content-Type: application/json' \ --data '{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "base": "example", "buildSecrets": [ "example" ], "dockerfile": { "blob": "example", "buildArgs": { "additionalProperty": "example" }, "context": "example", "inline": "example", "target": "example" }, "fromSandbox": { "attempt": { "epoch": 1, "name": "example" }, "includePaths": [ "example" ], "name": "example", "uid": "example" }, "imagePullSecrets": [ "example" ], "platform": "example", "python": "example", "steps": [ { "aptInstall": [ "example" ], "copy": { "blob": "example", "dest": "example" }, "env": { "additionalProperty": "example" }, "pipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "run": [ "example" ], "uvPipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "uvSync": { "frozen": true, "project": "example" }, "workdir": "example" } ], "tags": [ "example" ] }, "status": { "build": { "attempt": "example", "cached": true, "completionTime": "example", "costUSD": "example", "cpuSeconds": 1, "startTime": "example" }, "capture": { "attempt": { "epoch": 1, "name": "example" }, "base": "example", "blob": "example", "bytes": 1, "completedAt": "example", "deadline": "example", "failed": true, "id": "example", "node": "example", "platform": "example", "pullSecrets": [ "example" ], "sandboxUID": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "digest": "example", "message": "example", "observedGeneration": 1, "phase": "example", "progress": { "stage": "example" }, "python": "example", "reason": "example", "reference": "example", "size": 1, "specHash": "example", "tags": { "additionalProperty": "example" } } }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”The project.
The object’s name.
Query Parameters
Section titled “ Query Parameters ”Header Parameters
Section titled “ Header Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”Image is a container image Nodus builds from a base and steps or a Dockerfile, or a catalog image in the nodus project. An identical spec on the same base digest reuses the built digest.
object
object
object
object
object
object
object
ImageSpec is exactly one of base (with steps), dockerfile or fromSandbox.
object
Base is the OCI reference or catalog image (nodus/
BuildSecrets are Secrets mounted as BuildKit secrets; never baked into layers.
ImageDockerfile is a Dockerfile build: exactly one of inline and blob.
object
Blob is the blob digest of the Dockerfile.
BuildArgs are –build-arg values.
object
Context is the blob digest of the build context (a tar archive).
Inline is the Dockerfile text.
Target is the stage to build.
ImageFromSandbox names a Sandbox whose filesystem becomes the image.
object
SandboxAttempt names one run of a Sandbox’s container.
object
Epoch counts the runs: it grows on every start and every recovery.
Name is the attempt’s id.
IncludePaths limits the layer to these paths.
Name is the Sandbox.
UID, when set, refuses a replacement Sandbox that has reused the name.
ImagePullSecrets are Registry Secrets for a private base.
Platform is linux/amd64 or linux/arm64. A filesystem save inherits its source’s platform when omitted.
Python is the interpreter version the steps use; detected from the base when unset.
Steps run in order on the base (at most 128).
ImageStep is exactly one build step.
object
AptInstall installs Debian packages.
ImageCopy copies a blob to a path.
object
Blob is the blob digest (sha256:…) of a file or tar archive.
Dest is the absolute destination path.
Env sets environment variables.
object
PipInstall lists packages and optional indexes.
object
ExtraIndexURLs are searched after the index.
IndexURL replaces the default index.
Packages are requirement specifiers.
Run runs shell commands, one layer for all of them.
PipInstall lists packages and optional indexes.
object
ExtraIndexURLs are searched after the index.
IndexURL replaces the default index.
Packages are requirement specifiers.
UVSync installs a uv project (pyproject.toml and uv.lock) uploaded as a blob.
object
Frozen installs exactly the lock file.
Project is the blob digest (sha256:…) of the project archive.
Workdir sets the working directory.
Tags this build publishes.
ImageBuildStatus is the build’s outcome.
object
ImageBuild describes a build attempt, or a reused digest when Cached.
object
Attempt is the build attempt’s id.
Cached is true when an identical build’s digest was reused.
CompletionTime is when it finished.
CostUSD is what the build cost.
CPUSeconds is the metered build vCPU time.
StartTime is when the build started.
ImageCaptureStatus is the durable identity and result of a filesystem capture; only the server writes it.
object
SandboxAttempt names one run of a Sandbox’s container.
object
Epoch counts the runs: it grows on every start and every recovery.
Name is the attempt’s id.
Base is the source’s immutable OCI reference.
Blob is the immutable digest fixed before an upload URL is issued.
Bytes is the archive length fixed with Blob; it cannot change on a retry.
CompletedAt is set only after the uploaded object is verified and its source epoch is still live.
Deadline bounds export, upload and retries.
Failed means the node could not capture the admitted source; another save requires a new Image.
ID distinguishes this capture from every other save of the same Sandbox.
Node is the Nodus node assigned to that incarnation.
Platform is the architecture of the captured filesystem and cannot change in a rebuild.
PullSecrets are source Registry Secret names inherited when spec.imagePullSecrets is omitted.
SandboxUID identifies the source even after its name is reused.
Conditions are the latest observations.
object
Digest is the built manifest digest (sha256:…).
Message is a scrubbed explanation.
ObservedGeneration is the spec generation the status reflects.
Phase is Pending, Ready or Failed.
ImageProgress is the stage of a running build.
object
Stage is Queued, Capturing, Building or Pushing.
Python is the interpreter version in the image.
Reason says why the build failed.
Reference is the pullable reference, repository@digest.
Size is the compressed image size in bytes.
SpecHash is the content hash of the rendered build; equal hashes share a digest.
Tags maps each published tag to its digest.
object
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "base": "example", "buildSecrets": [ "example" ], "dockerfile": { "blob": "example", "buildArgs": { "additionalProperty": "example" }, "context": "example", "inline": "example", "target": "example" }, "fromSandbox": { "attempt": { "epoch": 1, "name": "example" }, "includePaths": [ "example" ], "name": "example", "uid": "example" }, "imagePullSecrets": [ "example" ], "platform": "example", "python": "example", "steps": [ { "aptInstall": [ "example" ], "copy": { "blob": "example", "dest": "example" }, "env": { "additionalProperty": "example" }, "pipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "run": [ "example" ], "uvPipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "uvSync": { "frozen": true, "project": "example" }, "workdir": "example" } ], "tags": [ "example" ] }, "status": { "build": { "attempt": "example", "cached": true, "completionTime": "example", "costUSD": "example", "cpuSeconds": 1, "startTime": "example" }, "capture": { "attempt": { "epoch": 1, "name": "example" }, "base": "example", "blob": "example", "bytes": 1, "completedAt": "example", "deadline": "example", "failed": true, "id": "example", "node": "example", "platform": "example", "pullSecrets": [ "example" ], "sandboxUID": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "digest": "example", "message": "example", "observedGeneration": 1, "phase": "example", "progress": { "stage": "example" }, "python": "example", "reason": "example", "reference": "example", "size": 1, "specHash": "example", "tags": { "additionalProperty": "example" } }}Responses
Section titled “ Responses ”OK
Image is a container image Nodus builds from a base and steps or a Dockerfile, or a catalog image in the nodus project. An identical spec on the same base digest reuses the built digest.
object
object
object
object
object
object
object
ImageSpec is exactly one of base (with steps), dockerfile or fromSandbox.
object
Base is the OCI reference or catalog image (nodus/
BuildSecrets are Secrets mounted as BuildKit secrets; never baked into layers.
ImageDockerfile is a Dockerfile build: exactly one of inline and blob.
object
Blob is the blob digest of the Dockerfile.
BuildArgs are –build-arg values.
object
Context is the blob digest of the build context (a tar archive).
Inline is the Dockerfile text.
Target is the stage to build.
ImageFromSandbox names a Sandbox whose filesystem becomes the image.
object
SandboxAttempt names one run of a Sandbox’s container.
object
Epoch counts the runs: it grows on every start and every recovery.
Name is the attempt’s id.
IncludePaths limits the layer to these paths.
Name is the Sandbox.
UID, when set, refuses a replacement Sandbox that has reused the name.
ImagePullSecrets are Registry Secrets for a private base.
Platform is linux/amd64 or linux/arm64. A filesystem save inherits its source’s platform when omitted.
Python is the interpreter version the steps use; detected from the base when unset.
Steps run in order on the base (at most 128).
ImageStep is exactly one build step.
object
AptInstall installs Debian packages.
ImageCopy copies a blob to a path.
object
Blob is the blob digest (sha256:…) of a file or tar archive.
Dest is the absolute destination path.
Env sets environment variables.
object
PipInstall lists packages and optional indexes.
object
ExtraIndexURLs are searched after the index.
IndexURL replaces the default index.
Packages are requirement specifiers.
Run runs shell commands, one layer for all of them.
PipInstall lists packages and optional indexes.
object
ExtraIndexURLs are searched after the index.
IndexURL replaces the default index.
Packages are requirement specifiers.
UVSync installs a uv project (pyproject.toml and uv.lock) uploaded as a blob.
object
Frozen installs exactly the lock file.
Project is the blob digest (sha256:…) of the project archive.
Workdir sets the working directory.
Tags this build publishes.
ImageBuildStatus is the build’s outcome.
object
ImageBuild describes a build attempt, or a reused digest when Cached.
object
Attempt is the build attempt’s id.
Cached is true when an identical build’s digest was reused.
CompletionTime is when it finished.
CostUSD is what the build cost.
CPUSeconds is the metered build vCPU time.
StartTime is when the build started.
ImageCaptureStatus is the durable identity and result of a filesystem capture; only the server writes it.
object
SandboxAttempt names one run of a Sandbox’s container.
object
Epoch counts the runs: it grows on every start and every recovery.
Name is the attempt’s id.
Base is the source’s immutable OCI reference.
Blob is the immutable digest fixed before an upload URL is issued.
Bytes is the archive length fixed with Blob; it cannot change on a retry.
CompletedAt is set only after the uploaded object is verified and its source epoch is still live.
Deadline bounds export, upload and retries.
Failed means the node could not capture the admitted source; another save requires a new Image.
ID distinguishes this capture from every other save of the same Sandbox.
Node is the Nodus node assigned to that incarnation.
Platform is the architecture of the captured filesystem and cannot change in a rebuild.
PullSecrets are source Registry Secret names inherited when spec.imagePullSecrets is omitted.
SandboxUID identifies the source even after its name is reused.
Conditions are the latest observations.
object
Digest is the built manifest digest (sha256:…).
Message is a scrubbed explanation.
ObservedGeneration is the spec generation the status reflects.
Phase is Pending, Ready or Failed.
ImageProgress is the stage of a running build.
object
Stage is Queued, Capturing, Building or Pushing.
Python is the interpreter version in the image.
Reason says why the build failed.
Reference is the pullable reference, repository@digest.
Size is the compressed image size in bytes.
SpecHash is the content hash of the rendered build; equal hashes share a digest.
Tags maps each published tag to its digest.
object
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "base": "example", "buildSecrets": [ "example" ], "dockerfile": { "blob": "example", "buildArgs": { "additionalProperty": "example" }, "context": "example", "inline": "example", "target": "example" }, "fromSandbox": { "attempt": { "epoch": 1, "name": "example" }, "includePaths": [ "example" ], "name": "example", "uid": "example" }, "imagePullSecrets": [ "example" ], "platform": "example", "python": "example", "steps": [ { "aptInstall": [ "example" ], "copy": { "blob": "example", "dest": "example" }, "env": { "additionalProperty": "example" }, "pipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "run": [ "example" ], "uvPipInstall": { "extraIndexURLs": [ "example" ], "indexURL": "example", "packages": [ "example" ] }, "uvSync": { "frozen": true, "project": "example" }, "workdir": "example" } ], "tags": [ "example" ] }, "status": { "build": { "attempt": "example", "cached": true, "completionTime": "example", "costUSD": "example", "cpuSeconds": 1, "startTime": "example" }, "capture": { "attempt": { "epoch": 1, "name": "example" }, "base": "example", "blob": "example", "bytes": 1, "completedAt": "example", "deadline": "example", "failed": true, "id": "example", "node": "example", "platform": "example", "pullSecrets": [ "example" ], "sandboxUID": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "digest": "example", "message": "example", "observedGeneration": 1, "phase": "example", "progress": { "stage": "example" }, "python": "example", "reason": "example", "reference": "example", "size": 1, "specHash": "example", "tags": { "additionalProperty": "example" } }}default
Section titled “ default ”An error: a metav1.Status whose reason is a registered code.
Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).
object
object
object
Docs is the URL of the code’s docs page.
Fix says what to do next, for example a CLI command or the field to change.
object
object
RequestID identifies the request in logs and support tickets.
Example generated
{ "apiVersion": "example", "code": 1, "details": { "causes": [ { "field": "example", "message": "example", "reason": "example" } ], "group": "example", "kind": "example", "name": "example", "retryAfterSeconds": 1, "uid": "example" }, "docs": "example", "fix": "example", "kind": "example", "message": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }, "reason": "example", "requestId": "example", "status": "example"}