Zudoku
Unikraft Cloud Platform API
Unikraft Cloud Platform API

Schemas

Audit.AuditAttribution

The operation an event belongs to. Events sharing an `operation` describe one overarching action, which is what makes a state transition attributable to the thing that caused it rather than only observable after the fact.
trigger
​string · enum · required

Whether this event was raised by the operation or observed after it.

Enum values:
requested
observed
origin
​string · enum · required

What caused the operation.

Enum values:
unknown
api
guest
proxy
autoscale
scale-to-zero
scheduled-op
restart
operation
​string · uuid

UUID shared by every event belonging to the same operation.

​

What was performed on the object.

user
​string · uuid

The user that caused the operation, when one did.

Audit.AuditEvent

One audit event.
type
​string · enum · required

The type of event.

Enum values:
vm.state_change
vm.start_failed
gap
timestamp
​string · date-time · required

When the event was raised.

​object

The object the event is about. Absent on gap, which names no object.

​object

The operation the event belongs to.

​object

The event payload. Its fields depend on type.

dropped
​integer · uint64

How many events were lost. Only on gap.

Audit.AuditEventData

The payload of an audit event. Which fields are present depends on the event type: - `vm.state_change` - `vm.start_failed`
prev
​string

The state before the transition.

new
​string

The state after the transition.

state
​string

The state the instance was left in after a failed start.

error
​string

The error that failed the start, as an errno name such as EDQUOT.

​object

Why the instance stopped.

Audit.AuditEventType

string · enum
Enum values:
vm.state_change
vm.start_failed
gap

The type of an audit event.

An enum rather than an open union because this is also a query parameter, and an open union generates as an interface that a client cannot serialise into a filter. Further event types are added here; a Go client decodes one it does not know as its plain string value rather than failing.

Audit.AuditObject

The object an audit event is about.
​required

The kind of object.

uuid
​string · uuid · required

The object's UUID.

owner
​string · uuid

The UUID of the user the object belongs to.

tags
​string[]

The tags set on the object.

Audit.AuditObjectType

anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = string
type = string
Properties for Variant 1:
string · enum
Enum values:
i
v

Audit.AuditOperationKind

anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = string
type = string
Properties for Variant 1:
string · enum
Enum values:
start
stop
drain
suspend
restart

Audit.AuditOrigin

string · enum
Enum values:
unknown
api
guest
proxy
autoscale
scale-to-zero
scheduled-op
restart

What caused the operation.

Audit.AuditStop

Why an instance stopped.
reason
​string[]

The origins that contributed to the stop.

code
​integer · uint32

The kernel stop code.

cause
​string

The stop cause.

Audit.AuditTrigger

string · enum
Enum values:
requested
observed

Whether the event was raised by the operation or observed as a result of it.

Autoscale.AdjustmentType

string · enum
Enum values:
change
exact
percentage

AdjustmentType defines the type of adjustment to be made in an autoscaling step policy.

Autoscale.AutoscalePolicy

AutoscalePolicy defines the autoscale policy for a service. Right now it contains fields from both the `ondemand` and `step` policies. They are marked both as optional, so only one of them should be set at a time. This is a current limitation of the API design.
name
​string · required

The name of the policy.

enabled
​boolean

Whether the policy is enabled.

metric
​string · enum

Metric to use for the step policy (only for step policies).

Enum values:
cpu
adjustment_type
​string · enum

The type of adjustment to be made in the step policy (only for step policies).

Enum values:
change
exact
percentage

The steps for the step policy. Each step defines an adjustment value and optional bounds.

Autoscale.AutoscalePolicyStep

A single step in a step autoscaling policy.
adjustment
​integer · int64 · required

The adjustment value for the step.

lower_bound
​integer · int64

Lower bound for the step.

upper_bound
​integer · int64

Upper bound for the step.

Autoscale.ConfigurationInstanceCreateArgs

​object

The ROM to use for the autoscale configuration.

​object

The template to use for the autoscale configuration.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: roms
type = object · requires: template
Properties for Variant 1:
​object · required

The ROM to use for the autoscale configuration.

​object

The template to use for the autoscale configuration.

Autoscale.CreateAutoscaleConfigurationByServiceGroupUUIDRequest

The request message to create an autoscale configuration for a service group based on its UUID.
uuid
​string · uuid · required

The UUID of the service to create a configuration for.

​object · required

The arguments to use when creating instances.

min_size
​integer · int64

The minimum number of instances to keep running.

max_size
​integer · int64

The maximum number of instances to keep running.

warmup_time_ms
​integer · int64

The warmup time in milliseconds for new instances.

cooldown_time_ms
​integer · int64

The cooldown time in milliseconds for the autoscale configuration.

The policies to apply to the autoscale configuration.

Autoscale.CreateAutoscaleConfigurationByServiceGroupUUIDRequestInstanceCreateArgs

​object

The ROM to use for the autoscale configuration.

​object

The template to use for the autoscale configuration.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: roms
type = object · requires: template
Properties for Variant 1:
​object · required

The ROM to use for the autoscale configuration.

​object

The template to use for the autoscale configuration.

Autoscale.CreateAutoscaleConfigurationPolicyRequest

The request message to create an autoscale configuration policy for a service.
name
​string · required

The name of the policy.

​object · required

The policy type to add to the autoscale configuration.

Autoscale.CreateAutoscaleConfigurationPolicyResponse

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.CreateAutoscaleConfigurationPolicyResponsePolicy

Per-item result for a create autoscale configuration policy operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.CreateAutoscaleConfigurationsRequestConfiguration

​object · required

The arguments to use when creating instances.

uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

min_size
​integer · int64

The minimum number of instances to keep running.

max_size
​integer · int64

The maximum number of instances to keep running.

warmup_time_ms
​integer · int64

The warmup time in milliseconds for new instances.

cooldown_time_ms
​integer · int64

The cooldown time in milliseconds for the autoscale configuration.

The policies to apply to the autoscale configuration.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

min_size
​integer · int64

The minimum number of instances to keep running.

max_size
​integer · int64

The maximum number of instances to keep running.

warmup_time_ms
​integer · int64

The warmup time in milliseconds for new instances.

cooldown_time_ms
​integer · int64

The cooldown time in milliseconds for the autoscale configuration.

​object

The arguments to use when creating instances.

The policies to apply to the autoscale configuration.

Autoscale.CreateAutoscaleConfigurationsResponse

The response to a CreateAutoscaleConfigurationRequest.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.CreateAutoscaleConfigurationsResponseConfigurationsResponse

Per-item result for a create autoscale configurations operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.DeleteAutoscaleConfigurationPolicyResponse

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.DeleteAutoscaleConfigurationPolicyResponsePoliciesResponse

Per-item result for a delete autoscale configuration policy operation.
name
​string · required

The name of the deleted policy.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.DeleteAutoscaleConfigurationsResponse

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.DeleteAutoscaleConfigurationsResponseServiceGroup

Per-item result for a delete autoscale configurations operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.DeletePolicyRequest

The request message to delete an autoscale configuration policy by name.
name
​string · required

The name of the policy to delete.

Autoscale.GetAutoscaleConfigurationPolicyRequest

The request message to get an autoscale configuration policy by name.
name
​string · required

The Name of the policy to get.

Example: funky-policy

Autoscale.GetAutoscaleConfigurationPolicyResponse

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.GetAutoscaleConfigurationPolicyResponsePolicyResponse

Per-item result for a get autoscale configuration policy operation.
​object · required

The policy which was retrieved by the request.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.GetAutoscaleConfigurationsResponse

The response message for a GetAutoscaleConfigurationsRequest.
status
​string · enum · required

The status of the response.

Enum values:
success
error
unconfigured
​object · required

The response data for this request.

op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

A list of errors which may have occurred during the request.

Autoscale.GetAutoscaleConfigurationsResponseServiceGroup

Per-item result for a get autoscale configurations operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

enabled
​boolean · required

If the autoscale configuration is enabled.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

min_size
​integer · int64

The minimum number of instances to keep running. Only if enabled is true.

max_size
​integer · int64

The maximum number of instances to keep running. Only if enabled is true.

warmup_time_ms
​integer · int64

The warmup time in seconds for new instances. Only if enabled is true.

cooldown_time_ms
​integer · int64

The cooldown time in seconds for the autoscale configuration. Only if enabled is true.

​object

The instance template used for the autoscale configuration. Only if enabled is true.

The policies applied to the autoscale configuration.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Autoscale.InstanceCreateArgsInstanceCreateRequestRoms

A ROM to use for an autoscale instance create configuration.
name
​string · required

The name of the ROM.

​

The image of the ROM to use for the autoscale configuration. Mutually exclusive with files. Accepts either a plain image reference string ("nginx:latest") or an object carrying additional pull configuration ({"url": "nginx:latest", "pull_policy": "always"}).

Example: nginx:latest

Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

Autoscale.ServiceGroupTemplate

The instance template used for an autoscale configuration.
uuid
​string · uuid · required

The UUID of the template used for the autoscale configuration.

name
​string · required

The name of the template used for the autoscale configuration.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Autoscale.StepPolicyMetric

string · enum
Enum values:
cpu

The step policy is a type of autoscaling policy that scales the number of instances in a service by a fixed number of instances at each step. It uses a metric to determine when to scale up or down.

Certificates.Certificate

Certificate with per-item response envelope fields merged in.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

created_at
​string · date-time · required

The time the certificate was created.

common_name
​string · required

The common name (CN) field from the certificate's subject.

This is typically the primary domain name that the certificate is issued for. It represents the main identity that the certificate validates.

Example: my-common-name
state
​string · enum · required

The current state of the certificate.

This indicates whether the certificate is pending issuance, valid and ready for use, or in an error state. See CertificateState enum for detailed state descriptions.

Enum values:
pending
valid
error
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

subject
​string

The complete subject distinguished name (DN) of the certificate.

This contains the full subject information from the certificate, including the common name, organization, organizational unit, locality, state, and country. The subject identifies the entity that the certificate is issued to. Only present when the certificate has been issued.

Example: example.com
issuer
​string

The complete issuer distinguished name (DN) of the certificate.

This identifies the Certificate Authority (CA) that issued the certificate. It contains information about the CA including its common name, organization, and country. Only present when the certificate has been issued.

Example: CN=R10,O=Let's Encrypt,C=US
serial_number
​string

The unique serial number assigned to the certificate by the issuing CA.

This is a unique identifier within the scope of the issuing CA that can be used to identify and track the certificate. Serial numbers are typically represented as hexadecimal strings. Only present when the certificate has been issued.

Example: 123456789ABCDEF123456789ABCDEF123456
not_before
​string · date-time

The date and time when the certificate becomes valid.

The certificate should not be trusted before this date. This timestamp marks the beginning of the certificate's validity period. Only present when the certificate has been issued.

not_after
​string · date-time

The date and time when the certificate expires.

The certificate should not be trusted after this date. This timestamp marks the end of the certificate's validity period. Certificates should be renewed before this date to maintain service availability. Only present when the certificate has been issued.

​object

Validation status when state is pending.

​Common.ResourceID[]

Service groups using this certificate.

Certificates.CertificateState

string · enum
Enum values:
pending
valid
error

The current state of a certificate.

The certificate can be in one of the following states:

StateDescription
pendingThe certificate request is pending while the certificate is being requested from the certification authority. During this phase any service using this certificate is not available if this is not a renewal.
validThe certificate is valid and can be used by your services.
errorThe certificate request failed after multiple attempts. This can happen, for example, if your DNS configuration is not correct, you run into Let's Encrypt™ quota limits, or the domain validation process failed for some other reason. There won't be any further automatic attempts.

Certificates.CertificateValidation

Validation status for a pending certificate.
attempt
​integer · int32 · required

The current validation attempt number.

next
​string · date-time · required

The next validation attempt time.

Certificates.CreateCertificateRequest

The request message for creating/uploading a new certificate.
chain
​string · required

The certificate chain in PEM format. Required for user-uploaded certificates.

pkey
​string · required

The private key in PEM format. Required for user-uploaded certificates.

name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

common_name
​string

The common name (CN) of the certificate.

This must be a fully-qualified domain name (FQDN). Exactly one of cn or common_name must be specified.

Example: funky-town.com

Certificates.CreateCertificateResponse

The response message for creating a new certificate.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Certificates.DeleteCertificatesResponse

The response message for deleting of one or more certificate(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Certificates.DeleteCertificatesResponseDeletedCertificate

Per-item result for a delete certificates operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Certificates.GetCertificatesResponse

The response message for getting one or more certificate(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Certificates.UpdateCertificateByUUIDRequestBody

The request body for updating a certificate by its UUID or name.
chain
​string · required

The new certificate chain. This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

pkey
​string · required

The new private key. This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

Certificates.UpdateCertificatesRequestItem

A single update operation to be applied to a certificate.
chain
​string · required

The new certificate chain. This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

pkey
​string · required

The new private key. This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

Certificates.UpdateCertificatesResponse

The response message for updating one or more certificate(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Common.InlineDataEncoding

string · enum
Enum values:
text
base64

Encoding type for inline file data.

Common.InlineFile

An inline file entry represents a single file within an image.
path
​string · required

The file path within the image.

data
​string · required

The file data, encoded according to the encoding field.

encoding
​string · enum

The encoding of the data field. Defaults to "text".

Enum values:
text
base64

Common.NameOrUUID

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

Common.PaginationOrder

string · enum
Enum values:
asc
desc

The sort order used by list endpoints.

Common.PaginationSortBy

string · enum
Enum values:
create_time

The sort field used by list endpoints.

Common.ResourceID

Identity fields for a resource, including the node it is placed on.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Common.ResponseError

The error response message for an API request.
status
​integer · uint64 · required

The HTTP status code of the error.

Common.ResponseStatus

string · enum
Enum values:
success
error
partial_success

The response status of an API request.

Common.SchedPriority

string · enum
Enum values:
normal
medium
high
admin

SchedPriority defines the scheduling priority for an instance. User requires the override_vm_priority permission to change it.

The list of available scheduling priorities:

PriorityDescription
normalDefault scheduling priority.
mediumMedium scheduling priority.
highHigh scheduling priority.
adminAdmin scheduling priority.

Images.GetImagesRequestTagOrDigest

digest
​string
tag
​string
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: digest
type = object · requires: tag
Properties for Variant 1:
digest
​string · required
tag
​string

Images.GetImagesResponse

The response message for getting one or more image(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Images.Image

An image representing a VM which can be deployed on Unikraft Cloud.
url
​string · required

The image URL.

created_at
​string · date-time · required

The time the image was created.

initrd_or_rom
​boolean · required

Whether the image is an initrd or ROM.

size_in_bytes
​integer · int64 · required

The size of the image in bytes.

args
​string[]

Command-line arguments for the image.

​object

Environment variables for the image.

tags
​string[]

Tags associated with the image.

users
​string[]

Users associated with the image.

persistent
​boolean

Whether the image is pinned and exempt from cache eviction. Only populated (and only ever true) for callers with image manager permissions; omitted otherwise, including when the image is not pinned.

Example: true

Images.PinImageRequestItem

The request item for pinning a single image.
url
​string · required

The image URL to pull and pin.

Example: user/image:latest
timeout_s
​integer · int64 · required

Number of seconds to wait for the pull to complete. Required and must be non-zero; -1 waits up to the platform's maximum timeout.

Example: 30
credentials
​string

Optional credentials for authenticating to an OCI registry. Only valid for OCI registry URLs; the platform rejects this field for non-OCI schemes.

Example: dXNlcjpwYXNzd29yZA==
​object

Optional HTTP headers to send when fetching the image.

Example: {"Authorization":"Bearer token123"}
pull_policy
​string · enum

Controls when the image is pulled relative to what is already cached on the node. If unset, this is inferred from the URL.

Enum values:
always
if_not_present
never
merge_requests
​boolean

Avoid duplicate pulls by merging with any in-flight request for the same image. Defaults to true.

Example: true
​object

Automatically unpin the image after a period of inactivity.

Images.PinImageRequestItemAutokill

Automatically unpin the image after a period of inactivity.
time_ms
​integer · uint64 · required

Automatically unpin the image after this many milliseconds of inactivity. 0 (the default) disables this.

Example: 60000

Images.PinImagesResponse

The response message for pinning one or more images.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Images.PinImagesResponseImage

The result of pinning a single image. On success, `uuid` through `tags` are set; on failure, only `message` and `error` are set (the image being pulled is not otherwise identified in the response).
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

uuid
​string · uuid

The UUID of the image. Only set on success.

name
​string

The name of the image. Only set on success.

created_at
​string · date-time

The time the image was created. Only set on success.

Example: 2021-01-01T00:00:00Z
state
​string

The current state of the image (e.g. ready). Only set on success.

Example: ready
url
​string

The image URL. Only set on success.

Example: user/image:latest
persistent
​boolean

Whether the image is pinned and exempt from cache eviction. Only set on success, where it is always true.

Example: true
tags
​string[]

The tags associated with the image. Only set on success.

Images.UnpinImageRequestItem

The request item for unpinning a single image.
uuid
​string · uuid · required

The UUID of the image to unpin. Only UUID is supported; name, URL, tag, and digest are not.

Images.UnpinImagesResponse

The response message for unpinning one or more images.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Images.UnpinImagesResponseImage

The result of unpinning a single image.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the image.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

name
​string

The name of the image. Only set on success, and only if the image has a name.

Instances.CheckpointAutokill

Automatic delete-on-idle configuration for the checkpoint instance.
time_ms
​integer · uint64

Time in milliseconds after the checkpoint was last used for restoring before it is deleted. A value of 0 disables checkpoint autokill.

Example: 60000

Instances.CheckpointHistoryEntry

A checkpoint history entry, representing a single checkpoint in the history of an instance.
uuid
​string · uuid · required

The UUID of the checkpoint.

name
​string · required

The name of the checkpoint.

Example: my-checkpoint
created_at
​string · date-time · required

The time the checkpoint was created.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.CreateCheckpointInstancesRequestItem

A single checkpoint creation request.
​object · required

The source instance to create a checkpoint from (by name or UUID).

name
​string

The name of the checkpoint. If not provided, a name will be generated.

Example: my-checkpoint
node
​string

The name of the node to place the checkpoint on. Must be the node of the source instance. Only accepted on metros that span multiple nodes.

timeout_s
​integer · int64

Timeout in seconds to wait for the checkpoint to be created. No wait performed for a value of 0.

Example: 10
tags
​string[]

Tags to associate with the checkpoint.

​object

Automatic delete-on-idle configuration for the new checkpoint.

Instances.CreateCheckpointInstancesResponse

The response message for creating one or more checkpoint(s) from existing instance(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.CreateCheckpointInstancesResponseCheckpointInstance

Per-item result for a create checkpoint instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the checkpoint.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.CreateInstanceRequest

The request message for creating a new instance.
name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

​

The image to use for the instance.

Either an image or a template must be specified. Accepts either a plain image reference string ("nginx:latest") or an object carrying additional pull configuration ({"url": "nginx:latest", "pull_policy": "always"}).

args
​string[]

The arguments to pass to the instance when it starts.

​object

Environment variables to set for the instance.

Example: {"ENV_VAR1":"value1","ENV_VAR2":"value2"}
memory_mb
​integer · int64

Memory in MB to allocate for the instance. Default is 128.

Example: 256
min_memory_mb
​integer · int64

Lower bound in MB for memory vertical scaling. Setting this or max_memory_mb enables memory vertical scaling, which is only supported by microVM instances. The instance boots with this amount of memory, and memory_mb selects the initial allocation within the bounds, defaulting to min_memory_mb. Must be lower than max_memory_mb, and within the user's memory limits. Cannot be used with templates that have a snapshot, branch_from or checkpoint.

Example: 256
max_memory_mb
​integer · int64

Upper bound in MB for memory vertical scaling. Setting this or min_memory_mb enables memory vertical scaling. Defaults to the user's maximum memory limit. Must be higher than min_memory_mb by at least the platform's memory block size. Cannot be used with templates that have a snapshot, branch_from or checkpoint.

Example: 1024
​object

The service group configuration when creating an instance.

When creating an instance, either a previously created (persistent) service group can be referenced (either through its name or UUID), or a new (ephemeral) service group can be created for the instance by specifying the list of services it should expose and optionally the domains it should use. Not used by template instances.

Volumes to attach to the instance.

This list can contain both existing and new volumes to create as part of the instance creation. Existing volumes can be referenced by their name or UUID. New volumes can be created by specifying a name, size in MiB, and mount point in the instance. The mount point is the directory in the instance where the volume will be mounted.

autostart
​boolean

Whether the instance should start automatically on creation. Must be set to true when timeout_s is specified.

Example: true
replicas
​integer · int64

Number of additional replicas to create. The total number of instances created is replicas + 1. Defaults to 0.

Example: 5
restart_policy
​string · enum

Restart policy for the instance. This defines how the instance should behave when it stops or crashes. Cannot be combined with the delete-on-stop feature.

Enum values:
never
always
on-failure
​object

Scale-to-zero configuration for the instance. Requires service_group to be set. Cannot be combined with the delete-on-stop feature.

vcpus
​integer · int32

Number of vCPUs to allocate for the instance. Defaults to 1.

Example: 1
min_vcpus
​integer · int32

Lower bound for vCPU vertical scaling. Setting this or max_vcpus enables vCPU vertical scaling, which is only supported by microVM instances. The instance boots with this number of vCPUs, and vcpus selects the initial allocation within the bounds, defaulting to min_vcpus. Must be lower than max_vcpus, and within the user's vCPU limits. Cannot be used with templates that have a snapshot, branch_from or checkpoint.

Example: 1
max_vcpus
​integer · int32

Upper bound for vCPU vertical scaling. Setting this or min_vcpus enables vCPU vertical scaling. Defaults to the user's maximum vCPU limit. Must be higher than min_vcpus. Cannot be used with templates that have a snapshot, branch_from or checkpoint.

Example: 4

Features to enable for the instance. Features are specific configurations or capabilities that can be enabled for the instance. The scale-to-zero and delete-on-stop features are mutually exclusive.

Enum values:
delete-on-stop
nested-virt
timeout_s
​integer · int64

Timeout in seconds to wait for all new instances to reach running state. Requires autostart to be set. If you autostart your new instance, you can wait for it to finish starting with a blocking API call if you specify a wait timeout greater than zero. No wait performed for a value of 0.

Example: 2

Read-Only Memory (ROM) blobs to attach to the instance. Unikraft Cloud supports the ability to attach Read-Only Memory (ROM) blobs to instances. It allows you to create a general-purpose base image and then customize individual instances by attaching code or data as separate ROM blobs.

Plugins to attach to the instance. Plugins let you attach small helper programs to an instance and reach each one over a direct, authenticated HTTP endpoint. Each plugin loads from its own ROM image, mounts at /uk/plugins/<plugin_name>, and is reachable at .../v1/instances/<uuid>/plugins/<plugin_name>/<path>. At most 8 plugins may be attached to an instance.

tags
​string[]

Tags to associate with the instance.

​object

Annotations to associate with the instance.

Unlike tags, annotations also reach the guest: they are included in the instance's startdata, and selected keys can be injected into the console log output.

Keys follow the Kubernetes annotation key syntax, [<prefix>/]<name>: the optional prefix is a non-wildcard DNS subdomain of at most 253 characters, and the name is at most 63 characters of [-_.a-zA-Z0-9] starting and ending with an alphanumeric. Values are unconstrained apart from ASCII control characters. An instance holds at most 256 annotations.

When the instance inherits annotations from a template, branch, or checkpoint, the given annotations are merged into them rather than replacing them. On a key clash the value given here wins.

Example: {"my-key":"value1","example.com/annotation2":"value2"}
​object

Template instances. An existing instance can be saved as a template. This template is then used to create new instances that inherit the exact configuration and state the original instance had when the template was created.

sched_priority
​string · enum

The scheduling priority for the instance. Only settable by users with scheduling priority override permissions.

Enum values:
normal
medium
high
admin
Example: high

Schedules for the instance. Scheduled operations let you automatically start, stop, delete, or exec a command in the instance on a calendar- based schedule. For exec schedules, set the args field to the command and its arguments. Each instance stores its own schedules, and cloning preserves them.

​object

Automatic delete-on-idle/request-limit configuration. Not used for template instances.

hostname
​string

The hostname of the instance.

If not provided, the hostname will be set to the instance name. The hostname must be a valid DNS label (e.g., "my-instance") and is used for internal DNS resolution within the Unikraft Cloud network.

Example: my-instance
​Common.NameOrUUID[]

Dependencies of the instance.

A list of instance identifiers (name or UUID) that this instance depends on. Dependencies define startup ordering and can be used to ensure that prerequisite instances are running before this instance starts.

​object

Reference to an existing instance to branch from. The instance can be running or stopped. If the source instance is running, a snapshot will be taken asynchronously and the new instance will wait for it to complete before starting. Mutually exclusive with image and template.

​object

Reference to an existing checkpoint to create the instance from. The checkpoint must be in the checkpoint state. The new instance will be created with the same configuration and state as the checkpoint. Mutually exclusive with image, template, and branch_from.

gateway
​string

The default gateway to configure inside the guest.

Example: 10.0.0.1
nameserver
​string

The DNS resolver to configure inside the guest.

Example: 8.8.8.8

Network interfaces to attach to the instance.

type
​string · enum

The type of virtual machine to use for the instance. Defaults to micro, which runs on Firecracker. full runs on QEMU instead and is required for GPU passthrough (see gpus) and, in the future, Windows VMs. QEMU- backed instances currently do not support scale-to-zero, templates, branching, or checkpointing, and only support block-based volumes (no virtiofs). Requires a plan with full VM support and cannot be combined with template, branch_from, or checkpoint.

Enum values:
micro
full
Example: full
gpus
​integer · int32 · min: 0 · max: 1

Number of GPUs to attach to the instance. Currently restricted to at most

  1. Requires type to be full and a plan with GPU support. A GPU stays assigned to the instance, even while stopped, until the instance is deleted. Cannot be combined with template, branch_from, or checkpoint.
Example: 1

Instances.CreateInstanceRequestAutokill

Automatic delete-on-idle/request-limit configuration for non-template instances.
time_ms
​integer · uint64

Time in milliseconds after the instance was stopped before it is deleted. A value of 0 disables time-based autokill.

num_requests
​integer · uint32

Maximum number of requests/connections the instance serves before it is deleted. A value of 0 disables request-based autokill.

Instances.CreateInstanceRequestDomain

The domain configuration for the service group. A domain defines a publicly accessible domain name for the instance. If the domain name ends with a period `.`, it must be a valid Fully Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.
name
​string · required

Publicly accessible domain name.

If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), e.g. example.com.; otherwise it will become a subdomain of the target metro, e.g. example becomes example.fra0.unikraft.app.

Example: funky-town-g756b5d.fra0.unikraft.app.
​object

A reference to an existing certificate which can be used for the specified domain. If unspecified, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

Instances.CreateInstanceRequestNetworkInterface

Network interface configuration for a new instance.
name
​string

The interface name. If omitted, Unikraft Cloud generates one as -ethX, falling back to eth- when the instance name is too long.

Example: eth0
tap_name
​string

The TAP device to attach the interface to. Provide it together with ip.

Example: tap0
ip
​string

The interface IP address in CIDR notation. Provide it together with tap_name to bring your own interface.

Example: 10.0.0.5/24
mac
​string

The interface MAC address. Provide it together with tap_name. Must be a unicast address outside the platform's address pool.

Example: 02:00:00:00:00:01
autoconfig
​boolean

Whether the guest configures the interface itself. Defaults to true.

Example: true
​object

Relay configuration for this interface.

Instances.CreateInstanceRequestPlugin

A helper program attached to the instance and reachable over a direct, authenticated HTTP endpoint. A plugin runs inside the instance next to the main application, loads from its own ROM image, and answers requests that the Unikraft Cloud API forwards to it.
name
​string · required

The plugin name. It becomes the <plugin_name> segment in the plugin endpoint (.../plugins/<plugin_name>/<path>). A plugin name has a maximum length of 63 characters and contains only letters (a-z, A-Z), digits (0-9), hyphen (-), and underscore (_).

Example: my-plugin
​

The plugin's image. The platform loads the image, mounts it at /uk/plugins/<plugin_name>, and runs its init program when the plugin starts. Accepts either a plain image reference string ("user/myplugin:latest") or an object carrying additional pull configuration ({"url": "user/myplugin:latest", "pull_policy": "always"}). Exactly one of image and rom must be set.

Example: user/myplugin:latest
config
​

Arbitrary JSON configuration that the platform passes to the plugin's init program on STDIN. Any JSON value works, including a string, a number, or an object.

​object

How requests to the plugin endpoint are authenticated. Without it, the platform API token of a user with access to the instance (userdb) is required. The platform checks the token and strips it before forwarding the request to the plugin.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: image
type = object · requires: rom
Properties for Variant 1:
​required

The plugin's image. The platform loads the image, mounts it at /uk/plugins/<plugin_name>, and runs its init program when the plugin starts. Accepts either a plain image reference string ("user/myplugin:latest") or an object carrying additional pull configuration ({"url": "user/myplugin:latest", "pull_policy": "always"}). Exactly one of image and rom must be set.

Example: user/myplugin:latest
name
​string

The plugin name. It becomes the <plugin_name> segment in the plugin endpoint (.../plugins/<plugin_name>/<path>). A plugin name has a maximum length of 63 characters and contains only letters (a-z, A-Z), digits (0-9), hyphen (-), and underscore (_).

Example: my-plugin
config
​

Arbitrary JSON configuration that the platform passes to the plugin's init program on STDIN. Any JSON value works, including a string, a number, or an object.

​object

How requests to the plugin endpoint are authenticated. Without it, the platform API token of a user with access to the instance (userdb) is required. The platform checks the token and strips it before forwarding the request to the plugin.

Instances.CreateInstanceRequestRom

A ROM to attach when creating an instance.
name
​string · required

The name of the ROM to use for the instance configuration.

Example: funky-rom
​

The image of the ROM to use for the instance configuration. Mutually exclusive with files. Accepts either a plain image reference string ("nginx:latest") or an object carrying additional pull configuration ({"url": "nginx:latest", "pull_policy": "always"}).

Example: nginx:latest
at
​string

The path at which the ROM should be automatically mounted inside the instance. When set, the platform mounts the ROM device at the specified path so the guest does not need to mount it manually. When omitted, the ROM is exposed as a raw block device and the guest is responsible for mounting it.

Example: /rom0

Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

Instances.CreateInstanceRequestServiceGroup

The service group configuration when creating an instance. If no existing (persistent) service group is specified via its identifier, a new (ephemeral) service group can be created by specifying the services it should expose. A service defines the configuration settings of an exposed port by the instance. A service is a combination of a public port, an internal port, and a set of handlers that define how the service will handle incoming connections.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

soft_limit
​integer · uint32
hard_limit
​integer · uint32
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

soft_limit
​integer · uint32
hard_limit
​integer · uint32

Instances.CreateInstanceRequestTemplate

Template configuration when creating an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

prepare
​boolean

Whether the instance needs to run in order to reach template state

Example: false
​object

Configuration parameters to apply when building the new instance from the source template.

prepare_timeout_s
​integer · int64

Timeout in seconds for preparing the template before the preparation is aborted. Only applies when prepare is set. A value of 0 means no timeout.

Example: 30
​object

Automatic delete-on-idle configuration for the template. Only applies when prepare is set.

Instances.CreateInstanceRequestVolume

A volume defines a storage volume that can be attached to the instance.
at
​string · required
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

size_mb
​integer · uint64
host_path
​string
readonly
​boolean
quota_policy
​string
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: size_mb
type = object · requires: host_path
Properties for Variant 1:
size_mb
​integer · uint64 · required
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

host_path
​string
at
​string
readonly
​boolean
quota_policy
​string
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object

Instances.CreateInstanceResponse

The response message for creating a new instance.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.CreateInstanceScaleToZero

Scale-to-zero configuration when creating an instance.
policy
​string · enum

The specific policy to use for scaling the instance to zero.

Enum values:
off
on
idle
stateful
​boolean

Whether the instance should be stateful when scaled to zero. If set to true, the instance will retain its state (e.g., RAM contents) when scaled to zero. This is useful for instances that need to maintain their state across scale-to-zero operations. If set to false, the instance will lose its state when scaled to zero, and it will be restarted from scratch when scaled back up.

Example: true
cooldown_time_ms
​integer · int32

The cooldown time in milliseconds before the instance can be scaled to zero again. This is useful to prevent rapid scaling to zero and back up, which can lead to performance issues or resource exhaustion.

Example: 3000
notify_time_ms
​integer · int32

The notification time in milliseconds before the instance is scaled to zero. This allows the instance to perform any necessary cleanup or state saving before being scaled down.

Example: 1000

Instances.CreateTemplateInstancesRequestItem

A single template instance to be created.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

timeout_s
​integer · int64

Timeout in seconds to wait for the template instances to be created. A value of -1 means to wait indefinitely until the instance reaches the desired state. No wait performed for a value of 0.

Example: 2
​object

Automatic delete-on-idle configuration for the new template.

Instances.CreateTemplateInstancesResponse

The response message for converting one or more instance(s) to templates.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.CreateTemplateInstancesResponseTemplateInstance

Per-item result for a create template instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.DeleteCheckpointInstancesResponse

The response message for deleting one or more checkpoint instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.DeleteCheckpointInstancesResponseCheckpointInstance

Per-item result for a delete checkpoint instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.DeleteInstanceByUUIDRequestBody

Parameters for deleting the instance by UUID.
timeout_s
​integer · int64

Timeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.

Example: 2
dont_retain
​boolean

Delete immediately without retention. If the instance is already being retained, this will force its deletion. Ignored if retention for instances is not configured.

Example: false

Instances.DeleteInstanceRequestItem

The request item for deleting an instance by its UUID or name.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

timeout_s
​integer · int64

Timeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.

Example: 2
dont_retain
​boolean

Delete immediately without retention. If the instance is already being retained, this will force its deletion. Ignored if retention for instances is not configured.

Example: false

Instances.DeleteInstancesResponse

The response message for deleting one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.DeleteInstancesResponseInstance

Per-item result for a delete instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

previous_state
​string · required

The previous state of the instance before it was deleted.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.DeleteTemplateInstancesResponse

The response message for deleting one or more template instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.DeleteTemplateInstancesResponseTemplateInstance

Per-item result for a delete template instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.GetCheckpointHistoryResponse

The response message for getting the checkpoint history of one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.GetCheckpointHistoryResponseInstanceHistory

Per-item result for a get checkpoint/instance history operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

The checkpoint history entries.

Instances.GetCheckpointInstancesResponse

The response message for getting one or more checkpoint instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.GetInstanceLogsByUUIDRequestBody

offset
​integer · int64

The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.

Example: 56000
limit
​integer · int64

The amount of bytes to return at most.

Example: 1500

Instances.GetInstancesLogsRequestItem

A single request item to get an instance's logs.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

offset
​integer · int64

The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.

Example: 56000
limit
​integer · int64

The amount of bytes to return at most.

Example: 1500

Instances.GetInstancesLogsResponse

The response message for getting the logs of one or more instance(s) by their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.GetInstancesLogsResponseAvailable

Per-item result for a get instances logs operation.
start
​integer · int64 · required

The first byte offset that can be retrieved.

Example: 250
end
​integer · int64 · required

The last byte offset that can be retrieved.

Example: 2700

Instances.GetInstancesLogsResponseLoggedInstance

Per-item result for a get instances logs operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

output
​string · required

Base64 encoded log output of the instance.

​object · required

Description of the log availability.

​object · required

Description of the range that was returned. Useful for requests with offset relative to end.

state
​string · enum · required

State of the instance when the logs were retrieved.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.GetInstancesLogsResponseRange

start
​integer · int64 · required

The first retrieved byte.

Example: 450
end
​integer · int64 · required

The last retrieved byte.

Example: 900

Instances.GetInstancesMetricsResponse

The response message for getting the metrics of one or more instance(s) by their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.GetInstancesMetricsResponseInstanceMetrics

Per-item result for a get instances metrics operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

rss_bytes
​integer · uint64 · required

Resident set size of the VMM in bytes.

The resident set size (RSS) specifies the amount of physical memory that has been touched by the instance and is currently reserved for the instance on the Unikraft Cloud server. The RSS grows until the instance has touched all memory assigned to it via the memory_mb setting and may also exceed this value as supporting services running outside the instance acquire memory. The RSS is different from the current amount of memory allocated by the application, which is likely to fluctuate over the lifetime of the application. The RSS is not a cumulative metric. When the instance is stopped rss goes down to 0.

Example: 5677765543
cpu_time_ms
​integer · uint64 · required

Consumed CPU time in milliseconds.

Example: 560007005
boot_time_us
​integer · uint64 · required

The boot time of the instance in microseconds. We take a pragmatic approach is to define the boot time. We calculate this as the difference in time between the moment the virtualization toolstack is invoked to respond to a VM boot request and the moment the OS starts executing user code (i.e., the end of the guest OS boot process). This is essentially the time that a user would experience in a deployment, minus the application initialization time, which we leave out since it is independent from the OS.

Example: 560007005
net_time_us
​integer · uint64 · required

This is the time it took for the user-level application to start listening on a non-localhost port measured in microseconds. This is the time from when the instance started until it reasonably ready to start responding to network requests. This is useful for measuring the time it takes for the instance to become operationally ready.

Example: 560007005
rx_bytes
​integer · uint64 · required

Total amount of bytes received from network.

Example: 12312353
rx_packets
​integer · uint64 · required

Total count of packets received from network.

Example: 43432
tx_bytes
​integer · uint64 · required

Total amount of bytes transmitted over network.

Example: 6565643
tx_packets
​integer · uint64 · required

Total count of packets transmitted over network.

Example: 54534
nconns
​integer · uint64 · required

Number of currently established inbound connections (non-HTTP).

Example: 5
nreqs
​integer · uint64 · required

Number of in-flight HTTP requests.

Example: 12
nqueued
​integer · uint64 · required

Number of queued inbound connections and HTTP requests.

Example: 5
ntotal
​integer · uint64 · required

Total number of inbound connections and HTTP requests handled.

Example: 21
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.GetInstancesResponse

The response message for getting one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.GetTemplateInstancesResponse

The response message for getting one or more template instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.ImageSpec

ImageSpec describes an image to use for an instance.
url
​string · required

The image URL

Example: index.docker.io/library/nginx:latest
credentials
​string

Optional credentials for authenticating to an OCI registry. Only valid for OCI registry URLs; the platform rejects this field for non-OCI schemes.

Example: dXNlcjpwYXNzd29yZA==
​object

Optional HTTP headers to send when fetching the image.

Example: {"Authorization":"Bearer token123"}
pull_policy
​string · enum

Controls when the image is pulled relative to what is already cached on the node.

Enum values:
always
if_not_present
never

Instances.Instance

Instance with per-item response envelope fields merged in.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

created_at
​string · date-time · required

The time the instance was created.

state
​string · enum · required

The state of the instance. This indicates the current state of the instance, such as whether it is running, stopped, or in an error state.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
image
​string · required

The image used to create the instance. This is a reference to the Unikraft image that was used to create the instance.

Example: nginx:latest
memory_mb
​integer · uint64 · required

The amount of memory in megabytes allocated for the instance. This is the total amount of memory that is available to the instance for its operations.

Example: 1024
vcpus
​integer · uint32 · required

The number of vCPUs allocated for the instance. This is the total number of virtual CPUs that are available to the instance for its operations.

Example: 1
restart_policy
​string · enum · required

The restart configuration for the instance.

When an instance stops either because the application exits or the instance crashes, Unikraft Cloud can auto-restart your instance. Auto-restarts are performed according to the restart policy configured for a particular instance.

The policy can have the following values:

PolicyDescription
neverNever restart the instance (default).
alwaysAlways restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes).
on-failureOnly restart the instance if it crashes.

When an instance stops, the stop reason and the configured restart policy are evaluated to decide if a restart should be performed. Unikraft Cloud uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, ..., 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s the back-off delay is reset and the restart sequence ends.

The restart.attempt attribute reported in counts the number of restarts performed in the current sequence. The restart.next_at field indicates when the next restart will take place if a back-off delay is in effect.

A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.

Enum values:
never
always
on-failure
type
​string · enum · required

The type of virtual machine used to run the instance.

Enum values:
micro
full
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

private_fqdn
​string

The internal hostname of the instance. This address can be used privately within the Unikraft Cloud network to access the instance. It is not accessible from the public Internet.

Example: funky-town-g756b5d.internal
boot_memory_mb
​integer · uint64

The amount of memory in megabytes the instance boots with. Only present if memory vertical scaling is enabled for the instance.

Example: 512
min_memory_mb
​integer · uint64

The lower bound of memory vertical scaling in megabytes. Only present if memory vertical scaling is enabled for the instance.

Example: 512
max_memory_mb
​integer · uint64

The upper bound of memory vertical scaling in megabytes. Only present if memory vertical scaling is enabled for the instance.

Example: 2048
boot_vcpus
​integer · uint32

The number of vCPUs the instance boots with. Only present if vCPU vertical scaling is enabled for the instance.

Example: 1
min_vcpus
​integer · uint32

The lower bound of vCPU vertical scaling. Only present if vCPU vertical scaling is enabled for the instance.

Example: 1
max_vcpus
​integer · uint32

The upper bound of vCPU vertical scaling. Only present if vCPU vertical scaling is enabled for the instance.

Example: 4
args
​string[]

The arguments passed to the instance when it was started. This is a list of command-line arguments that were provided to the instance at startup. These arguments can be used to configure the behavior of the instance and its applications.

​object

Environment variables set for the instance.

Example: {"ENV_VAR":"value"}
start_count
​integer · uint64

The total number of times the instance has been started. This is a counter that increments each time the instance is started, regardless of whether it was manually stopped or restarted. This can be useful for tracking the usage of the instance over time and/or for debugging purposes.

Not used for template instances.

Example: 6
restart_count
​integer · uint64

The total number of times the instance has been restarted. This is a counter that increments each time the instance has been restarted. This can be useful for tracking the usage of the instance over time and/or for debugging purposes. Not used for template instances.

Example: 1
started_at
​string · date-time

The time the instance was started. This is the timestamp when the instance was last started. Not used for template instances.

stopped_at
​string · date-time

The time the instance was stopped. This is the timestamp when the instance was last stopped. If the instance is currently running, this field will be empty. Not used for template instances.

uptime_ms
​integer · uint64

The total amount of time the instance has been running in milliseconds. Not used for template instances.

Example: 8954050300
retained_until
​string · date-time

Time when the instance will be permanently deleted (for deleted instances).

start_prereq_time_us
​integer · uint64

The time taken for the start prerequisites to be fulfilled, measured in microseconds from when the instance start was requested. Prerequisites are the resources the instance needs before its VM can be launched: the kernel and image being available locally, volumes being mounted, and a template being ready to resume from. Not used for template instances.

Example: 1200
vmm_prestart_time_us
​integer · uint64

(Developer-only). The time taken between the start being requested and the moment the VMM (Virtual Machine Monitor) process is spawned, measured in microseconds. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 65000
vmm_start_time_us
​integer · uint64

(Developer-only). The time taken between the main controller and the beginning of execution of the VMM (Virtual Machine Monitor) measured in microseconds. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 70040
vmm_load_time_us
​integer · uint64

(Developer-only). The time it took the VMM (Virtual Machine Monitor) to load the instance's kernel and initramfs into VM memory measured in microseconds. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 4050
vmm_ready_time_us
​integer · uint64

(Developer-only). The time taken for the VMM (Virtual Machine Monitor) to become ready to execute the instance measured in microseconds. This is the time from when the VMM started until it was ready to execute the instance's code. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 400
boot_time_us
​integer · uint64

The boot time of the instance in microseconds. We take a pragmatic approach is to define the boot time. We calculate this as the difference in time between the moment the virtualization toolstack is invoked to respond to a VM boot request and the moment the OS starts executing user code (i.e., the end of the guest OS boot process). This is essentially the time that a user would experience in a deployment, minus the application initialization time, which we leave out since it is independent from the OS. Not used for template instances.

Example: 9000
net_time_us
​integer · uint64

This is the time it took for the user-level application to start listening on a non-localhost port measured in microseconds. This is the time from when the instance started until it reasonably ready to start responding to network requests. This is useful for measuring the time it takes for the instance to become operationally ready. Not used for template instances.

Example: 11000
template_time_us
​integer · uint64

The time taken for the instance to reach the template state, measured in microseconds from when the template was requested. Only used for template instances.

checkpoint_time_us
​integer · uint64

The time taken for the instance to reach the checkpoint state, measured in microseconds from when the checkpoint was requested. Only used for checkpoint instances.

stop_reason
​integer · uint32

The instance stop reason.

Provides reason as to why an instance is stopped or in the process of shutting down. The stop reason is a bitmask that tells you the origin of the shutdown:

Bit43210 (LSB)
Purpose[F]orced[U]ser[P]latform[A]pp[K]ernel
  • Forced: This was a force stop. A forced stop does not give the instance a chance to perform a clean shutdown. Bits 0 (Kernel) and 1 (App) can thus never be set for forced shutdowns. Consequently, there won't be an exit_code or stop_code.
  • User: Stop initiated by user, e.g. via an API call.
  • Platform: Stop initiated by platform, e.g. an autoscale policy.
  • App: The Application exited. The exit_code field will be set.
  • Kernel: The kernel exited. The stop_code field will be set.

For example, the stop reason will contain the following values in the given scenarios:

ValueBitmaskAliasesScenario
2811100FUP--Forced user-initiated shutdown.
1501111-UPAKRegular user-initiated shutdown. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
1301101-UP-KThe user initiated a shutdown but the application was forcefully killed by the kernel during shutdown. This can be the case if the image does not support a clean application exit or the application crashed after receiving a termination signal. The exit_code won’t be present in this scenario.
700111--PAKUnikraft Cloud initiated the shutdown, for example, due to scale-to-zero. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
300011---AKThe application exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
100001----KThe instance likely expierenced a fatal crash and the stop_code contains more information about the cause of the crash.
000000-----The stop reason is unknown.
Not used for template instances.
Example: 15
exit_code
​integer · uint32

The application exit code.

This is the code which the application returns upon leaving its main entry point. The encoding of the exit code is application specific. See the documentation of the application for more details. Usually, an exit code of 0 indicates success / no failure. Not used for template instances.

Example: 137
stop_code
​integer · uint32

The kernel stop code.

This value encodes multiple details about the stop irrespective of the application.

Code
MSB LSB
┌──────────────┬──────────┬──────────┬───────────┬────────┐
│ 31 ────── 24 │ 23 ── 16 │ 15 │ 14 ──── 8 │ 7 ── 0 │
├──────────────┼──────────┼──────────┼───────────┼────────┤
│ reserved[^1] │ errno │ shutdown │ initlevel │ reason │
└──────────────┴──────────┴──────────┴───────────┴────────┘
  • errno: The application errno, using Linux's errno.h values. (Optional, can be 0.)
  • shutdown: Whether the shutdown originated from the inittable (0) or from the termtable (1).
  • initlevel: The initlevel at the time of the stop.
  • reason: The reason for the stop. See StopCodeReason.
Example: 33024
​object

The scale-to-zero configuration for the instance.

With conventional cloud platforms you need to keep at least one instance running at all times to be able to respond to incoming requests. Performing a just-in-time cold boot is simply too time-consuming and would create a response latency of multiple seconds. This is not the case with Unikraft Cloud. Instances on Unikraft Cloud are able to cold boot within milliseconds, which allows us to perform low-latency scale-to-zero.

To enable scale-to-zero for an instance it is sufficient to add a scale_to_zero configuration block. Unikraft Cloud will then put the instance into standby if there is no traffic to your service within the window of a cooldown period. When there is new traffic coming in, it is automatically started again.

If you have a heavyweight application that takes long to cold boot or has bad first request latency (e.g., with JIT compilation) consider to enable stateful scale-to-zero.

​object

The service group configuration for the instance.

services
​string[]

Services exposed by this instance (format: "protocol:port").

The list of volumes attached to the instance.

The network interfaces of the instance. Not used for template instances.

tags
​string[]

The tags associated with the instance.

​object

The annotations associated with the instance.

Keys follow the Kubernetes annotation key syntax, [<prefix>/]<name>: the optional prefix is a non-wildcard DNS subdomain of at most 253 characters, and the name is at most 63 characters of [-_.a-zA-Z0-9] starting and ending with an alphanumeric. Values are unconstrained apart from ASCII control characters, which are rejected because they would corrupt the console log output annotations can be forwarded to.

An instance holds at most 256 annotations.

Example: {"my-key":"value1","example.com/annotation2":"value2"}
​object

The snapshot of the instance, if exists.

delete_lock
​boolean

If set to true, the instance cannot be deleted until the lock is removed.

Enum values:
delete-on-stop
nested-virt
​object

The current restart attempt for the instance. Not used for template instances.

Read-Only Memory (ROM) blobs to attach to the instance. Unikraft Cloud supports the ability to attach Read-Only Memory (ROM) blobs to instances. It allows you to create a general-purpose base image and then customize individual instances by attaching code or data as separate ROM blobs.

Plugins attached to the instance. Plugins let you attach small helper programs to an instance and reach each one over a direct, authenticated HTTP endpoint. Each plugin loads from its own ROM image, mounts at /uk/plugins/<plugin_name>, and is reachable at .../v1/instances/<uuid>/plugins/<plugin_name>/<path>. At most 8 plugins may be attached to an instance.

Scheduled operations for this instance.

Each schedule defines a calendar expression and an action (start, stop, delete, or exec) to perform at matching times. When the action is exec, the args field of the schedule specifies the command to run inside the instance.

​object

Automatic delete-on-idle/request-limit configuration. Not used for template instances.

Queued property changes awaiting application.

sched_priority
​string · enum

The scheduling priority for the instance. Only present for users with scheduling priority override permissions.

Enum values:
normal
medium
high
admin
Example: high
​object

Template-specific automatic delete-on-idle configuration. Not used for non-template instances.

​object

Checkpoint-specific automatic delete-on-idle configuration. Only used for checkpoint instances.

private_ip
​string

The private IP address of the instance.

Example: 10.0.0.5
gateway
​string

The default gateway configured inside the guest.

Example: 10.0.0.1
nameserver
​string

The DNS resolver configured inside the guest.

Example: 8.8.8.8
​object

The source this instance was cloned from, while the source exists.

GPUs attached to the instance. Only present for instances of type full.

Instances.InstanceAutokill

Automatic delete-on-idle/request-limit configuration for non-template instances. Not used for template instances.
time_ms
​integer · uint64

Time in milliseconds after the instance was stopped before it is deleted. A value of 0 disables time-based autokill.

num_requests
​integer · uint32

Maximum number of requests/connections the instance serves before it is deleted. A value of 0 disables request-based autokill.

Instances.InstanceCloneSource

The instance, template, or checkpoint that an instance was cloned from.
uuid
​string · uuid · required

The UUID of the source.

name
​string

The name of the source.

Example: my-template
node
​string

The name of the node the source is placed on.

Instances.InstanceFeature

string · enum
Enum values:
delete-on-stop
nested-virt

Features are specific configurations or capabilities that can be enabled for the instance.

The list of available features to enable for the instance:

FeatureDescription
delete-on-stopThe instance will be deleted when it is stopped. This is useful for instances that are not needed after they are stopped, such as temporary or ephemeral instances. Cannot be combined with a restart_policy other than never.
nested-virtExpose virtualization extensions to the guest, so that it can run virtual machines of its own. Requires the nested_virt permission.

Instances.InstanceGpu

A GPU attached to the instance.
uuid
​string · uuid · required

The UUID of the GPU.

model
​string · required

The GPU model, given as its PCI vendor and device ID in the form <vendor>:<device>.

Example: 10de:1eb8

Instances.InstanceNetworkInterface

A network interface attached to an instance.
uuid
​string · uuid · required
private_ip
​string · required

The private IP address of the network interface. This is the internal IP address that is used for communication between instances within the same network.

Example: 10.0.0.61
mac
​string · required

The MAC address of the network interface.

Example: 12:b0:a0:00:00:3d
node
​string

The name of the node the network interface is placed on.

name
​string

The interface name. If omitted, Unikraft Cloud generates one as -ethX, falling back to eth- when the instance name is too long.

Example: eth0
tap_name
​string

The TAP device to attach the interface. Provide it together with ip.

Example: tap0
autoconfig
​boolean

Whether the interface is automatically configured inside the guest (IP address, routes, etc.). When absent or true, autoconfiguration is enabled. Present and false when the guest is expected to configure the interface manually.

Example: false
​object

Relay configuration for this interface.

Instances.InstanceNetworkInterfaceRelay

An object that routes all traffic through another interface.
uuid
​string · uuid · required

UUID of the relay interface.

name
​string · required

Name of the relay interface.

Example: eth-relay
relay_dns
​boolean · required

Whether DNS traffic is relayed through this interface. Defaults to true.

Example: true
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.InstancePendingUpdate

A queued property change awaiting application on an instance.
prop
​string · enum · required

The property being updated.

Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock
op
​string · enum · required

The patch operation type.

Enum values:
set
add
del
value
​required

The new value for the property. Type depends on the property being updated.

status
​string · enum · required

The status of this update.

Enum values:
pending
failed
error
​string

Error message. Only present when status is "failed".

Instances.InstancePlugin

A helper program attached to the instance and reachable over a direct, authenticated HTTP endpoint. A plugin runs inside the instance next to the main application, loads from its own ROM image, and answers requests that the Unikraft Cloud API forwards to it.
name
​string · required

The plugin name. It becomes the <plugin_name> segment in the plugin endpoint (.../plugins/<plugin_name>/<path>). A plugin name has a maximum length of 63 characters and contains only letters (a-z, A-Z), digits (0-9), hyphen (-), and underscore (_).

Example: my-plugin
image
​string · required

The plugin's image, given as an image reference string such as user/myplugin:latest. The platform loads the image, mounts it at /uk/plugins/<plugin_name>, and runs its init program when the plugin starts.

Example: user/myplugin:latest
config
​

Arbitrary JSON configuration that the platform passes to the plugin's init program on STDIN. Any JSON value works, including a string, a number, or an object.

api_port
​integer · uint32

The port on the instance's address on which the plugin's API listens. The platform picks it when the plugin is applied, so it lets a caller that can reach the instance directly talk to the plugin without going through the platform API.

Example: 20000
​object

The plugin's authorization method. Only present when it is not the default (userdb).

Instances.InstancePluginAuthorization

The authorization method of a plugin, as reported in the instance status. The token is never returned.
type
​string · enum · required

The authorization method.

Enum values:
userdb
bearer
Example: bearer

Instances.InstanceRestartAttempt

Restart attempt information for an instance.
attempt
​integer · uint32 · required

Current restart attempt number. This is incremented each time the instance is restarted automatically by the platform.

Example: 1
next_at
​string · date-time

Timestamp of the next scheduled restart attempt.

Instances.InstanceRestartPolicy

string · enum
Enum values:
never
always
on-failure

The restart policy of an instance.

When an instance stops either because the application exits or the instance crashes, Unikraft Cloud can auto-restart your instance. Auto-restarts are performed according to the restart policy configured for a particular instance. The policy can have the following values:

PolicyDescription
neverNever restart the instance (default).
alwaysAlways restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes).
on-failureOnly restart the instance if it crashes.

When an instance stops, the stop reason and the configured restart policy are evaluated to decide if a restart should be performed. Unikraft Cloud uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, ..., 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s the back-off delay is reset and the restart sequence ends. The restart.attempt attribute reported in counts the number of restarts performed in the current sequence. The restart.next_at field indicates when the next restart will take place if a back-off delay is in effect. A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.

Instances.InstanceRom

A ROM attached to an instance.
name
​string · required

The name of the ROM to use for the instance configuration.

Example: funky-rom
image
​string

The image of the ROM to use for the instance configuration. Mutually exclusive with files.

Example: nginx:latest
at
​string

The path at which the ROM should be automatically mounted inside the instance. When set, the platform mounts the ROM device at the specified path so the guest does not need to mount it manually. When omitted, the ROM is exposed as a raw block device and the guest is responsible for mounting it.

Example: /rom0

Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

Instances.InstanceScaleToZero

Scale-to-zero defines the configuration for scaling the instance to zero. When an instance is scaled-to-zero it can be either stopped (and fully shutdown) or paused wherein the state of the instance is preserved (e.g., RAM contents) and the instance can be resumed later without losing its state, i.e. "stateful".
enabled
​boolean

Indicates whether scale-to-zero is enabled for the instance.

Example: true
policy
​string · enum

The specific policy to use for scaling the instance to zero.

Enum values:
off
on
idle
stateful
​boolean

Whether the instance should be stateful when scaled to zero. If set to true, the instance will retain its state (e.g., RAM contents) when scaled to zero. This is useful for instances that need to maintain their state across scale-to-zero operations. If set to false, the instance will lose its state when scaled to zero, and it will be restarted from scratch when scaled back up.

Example: true
cooldown_time_ms
​integer · int32

The cooldown time in milliseconds before the instance can be scaled to zero again. This is useful to prevent rapid scaling to zero and back up, which can lead to performance issues or resource exhaustion.

Example: 3000
notify_time_ms
​integer · int32

The notification time in milliseconds before the instance is scaled to zero. This allows the instance to perform any necessary cleanup or state saving before being scaled down.

Example: 1000

Instances.InstanceScaleToZeroPolicy

string · enum
Enum values:
off
on
idle

Scale-to-zero policy types to use when creating an instance.

The policy can be one of the following values:

PolicyDescription
onThe instance should be scaled-to-zero (when possible).
offThe instance should never be scaled-to-zero.
idleThe instance should be scaled-to-zero even with established but idle TCP connections.

Instances.InstanceServiceGroup

The service group configuration for the instance. This is a reference to the service group that the instance is part of. The service group defines the services (e.g. ports, connection handling) that the instance exposes and how they are configured.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

The domain configuration for the service group.

Instances.InstanceSnapshot

A snapshot reference for an instance.
uuid
​string · uuid · required

Instances.InstanceState

string · enum
Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted

The current state of an instance.

Instances.InstanceTemplateAutokill

Autokill configuration for a template instance.
time_ms
​integer · uint64

Time in milliseconds after the template was last used for cloning before it is deleted. A value of 0 disables template autokill.

Instances.InstanceType

string · enum
Enum values:
micro
full

The type of virtual machine used to run an instance.

TypeDescription
microA lightweight microVM (default). Boots in milliseconds and is suitable for most workloads.
fullA full virtual machine with broader hardware support, such as GPU passthrough. Requires a plan with full VM support.

Instances.InstanceVolume

A volume defines a storage which can be attached to the instance. Volumes can be used to store persistent data which should remain available even if the instance is stopped or restarted.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

at
​string · required

The mount point of the volume in the instance. This is the directory in the instance where the volume will be mounted.

Example: /mnt/funky-volume
readonly
​boolean · required

Whether the volume is read-only or not.

Example: true
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.ItemAutokill

Automatic delete-on-idle configuration for the template instance.
time_ms
​integer · uint64

Time in milliseconds after the template was last used for cloning before it is deleted. A value of 0 disables template autokill.

Example: 60000

Instances.MutableCheckpointInstanceOperation

string · enum
Enum values:
set
add
del

The operations available on a checkpoint instance's properties.

Instances.MutableCheckpointInstanceProperty

string · enum
Enum values:
tags
delete_lock
autokill

The mutable properties of a checkpoint instance that can be updated.

Instances.MutableInstanceOperation

string · enum
Enum values:
set
add
del

Mutable instance operations.

Instances.MutableInstanceProperty

string · enum
Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock

The mutable properties of an instance that can be updated.

Instances.MutableTemplateInstanceOperation

string · enum
Enum values:
set
add
del

Mutable template instance operations.

Instances.MutableTemplateInstanceProperty

string · enum
Enum values:
tags
delete_lock
autokill
image
roms
plugins

The mutable properties of a template instance that can be updated. Setting image, roms, or plugins updates the template in place.

Instances.NetworkInterfaceRelay

An object that routes all traffic through another interface.
relay_dns
​boolean

Whether the relay forwards DNS requests. Set to false to let the default DNS server handle them instead. Defaults to true.

Example: true
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

relay_dns
​boolean

Whether the relay forwards DNS requests. Set to false to let the default DNS server handle them instead. Defaults to true.

Example: true
name
​string

The name of the resource.

Instances.PluginAuthorization

Authorization for requests to a plugin endpoint.
type
​string · enum · required

The authorization method.

Enum values:
userdb
bearer
Example: bearer
token
​string · maxLength: 256

The token that requests must present as Authorization: Bearer <token>. Required for, and only allowed with, the bearer type.

Example: my-secret-token
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
requires: token
No specific criteria
Properties for Variant 1:
type
​enum
Enum values:
bearer

Instances.PluginAuthorizationType

string · enum
Enum values:
userdb
bearer

How requests to a plugin endpoint are authenticated.

Instances.PullPolicy

string · enum
Enum values:
always
if_not_present
never

PullPolicy defines when an image should be pulled.

Instances.Schedule

A schedule defines when an action should be performed on an instance. Each schedule specifies a name, a calendar expression following systemd calendar event syntax, and an action (start, stop, delete, or exec). Calendar expressions format: [weekday] [[year-]month-day] [hour:minute[:second]] Supported syntax: - `*` - Any value - `5` - Exact value - `1..5` - Range - `1..5/2` - Range with step - `1,2,5` - Comma-separated list Example: `*-*-* 09:00:00` - Every day at 09:00 UTC Example: `Sat,Sun *-*-* 20:00:00` - Every Saturday and Sunday at 20:00 UTC
name
​string · required

The name of the schedule.

Must be unique within an instance.

Example: daily-stop
when
​string · required

The calendar expression specifying when the action should be performed.

Uses systemd calendar event syntax. See https://www.man7.org/linux/man-pages/man7/systemd.time.7.html

action
​string · enum · required

The action to perform at the scheduled time.

Enum values:
start
stop
delete
exec
next_at
​string · date-time · readOnly

The timestamp of when the next scheduled action will occur.

This field is populated only in responses (not settable in requests). Omitted if no next execution is scheduled.

args
​string[]

The command to execute when the action is exec.

Required when action is SCHEDULE_ACTION_EXEC, ignored otherwise. Each element is a separate argument; the first element is the executable.

Example: ["/bin/sh","-c","echo hello"]

Instances.ScheduleAction

string · enum
Enum values:
start
stop
delete
exec

The action to perform on a scheduled operation.

Instances.ServiceGroupInstanceDomain

The domain configuration for the service group. Domain names are completely specified with all labels in the hierarchy of the DNS, having no parts omitted. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.
fqdn
​string · required

Publicly accessible domain name.

If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: funky-town-g756b5d.fra0.unikraft.app.
​object

The certificate associated with the domain.

The certificate is used to secure the domain with TLS/SSL. If no certificate is specified, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

Instances.StartInstanceByUUIDRequestBody

Parameters for starting the instance.
timeout_s
​integer · int64

Timeout in seconds to wait for the instance to reach running state. If you start your instance, you can wait for it to finish starting with a blocking API call if you specify a wait timeout greater than zero. No wait performed for a value of 0.

Example: 2

Instances.StartInstancesRequestItem

A single request item to start an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

timeout_s
​integer · int64

Timeout in seconds to wait for the instance to reach running state. If you start your instance, you can wait for it to finish starting with a blocking API call if you specify a wait timeout greater than zero. No wait performed for a value of 0.

Example: 2

Instances.StartInstancesResponse

The response message for starting one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.StartInstancesResponseStartedInstance

Per-item result for a start instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · required

The current state of the instance after this request.

previous_state
​string · required

The previous state of the instance before it was started.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.StopInstanceByUUIDRequestBody

Parameters for stopping the instance.
force
​boolean

Whether to immediately force stop the instance.

Example: true
drain_timeout_ms
​integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired. The maximum timeout may vary. Use -1 for the largest possible value. Ignored if force is set.

Note: This endpoint does not block. Use the wait endpoint for the instance to reach the stopped state.

Example: 550
quick
​boolean

Whether to perform a quick shutdown. This flag is overridden by force.

Example: false
ifstate
​string

Only stop the instance if it is in this state.

Example: running
dump
​boolean

If set, forces the VMM to shutdown immediately and generate a coredump. Can only be used in conjunction with force.

Example: false

Instances.StopInstancesRequestItem

A single request item to stop an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

force
​boolean

Whether to immediately force stop the instance.

Example: true
drain_timeout_ms
​integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired. The maximum timeout may vary. Use -1 for the largest possible value. Ignored if force is set.

Note: This endpoint does not block. Use the wait endpoint for the instance to reach the stopped state.

Example: 550
quick
​boolean

Whether to perform a quick shutdown. This flag is overridden by force.

Example: false
ifstate
​string

Only stop the instance if it is in this state.

Example: running
dump
​boolean

If set, forces the VMM to shutdown immediately and generate a coredump. Can only be used in conjunction with force.

Example: false

Instances.StopInstancesResponse

The response message for stopping one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.StopInstancesResponseStoppedInstance

Per-item result for a stop instances operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
previous_state
​string · enum · required

The previous state of the instance before the stop operation was invoked.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.SuspendInstanceByUUIDRequestBody

Parameters for suspending the instance.
drain_timeout_ms
​integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.

Example: 550

Instances.SuspendInstancesRequestItem

A single request item to suspend an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

drain_timeout_ms
​integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.

Example: 550

Instances.SuspendInstancesResponse

The response message for suspending one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.SuspendInstancesResponseSuspendedInstance

Per-item result for a suspend instances operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
previous_state
​string · enum · required

The previous state of the instance before the suspend operation was invoked.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Instances.TemplateAutokill

Automatic delete-on-idle configuration for the template instance. Only applies when `prepare` is set.
time_ms
​integer · uint64

Time in milliseconds after the template was last used for cloning before it is deleted. A value of 0 disables template autokill.

Example: 60000

Instances.UpdateCheckpointInstanceByUUIDRequestBody

Request body for updating a single checkpoint instance by UUID.
prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
autokill
Example: tags
op
​string · enum · required

The operation to perform on the property.

Enum values:
set
add
del
Example: add
id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "autokill": object with time_ms field

Instances.UpdateCheckpointInstancesRequestItem

A single update operation to be applied to a checkpoint instance.
prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
autokill
Example: tags
op
​string · enum · required

The operation to perform on the property.

Enum values:
set
add
del
Example: add
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "autokill": object with time_ms field

Instances.UpdateCheckpointInstancesResponse

The response message for updating one or more checkpoint instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.UpdateCheckpointInstancesResponseCheckpointInstance

Per-item result for an update checkpoint instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

The client-provided ID from the request.

Instances.UpdateInstanceByUUIDRequestBody

prop
​string · enum · required

The property to modify.

Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock
op
​string · enum · required

The operation to perform on the property.

Enum values:
set
add
del
id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": image reference string, or object with image url, credentials, headers and pull policy
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields) for SET/ADD, or array of schedule names for DEL. Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "plugins": array of plugin objects (with name, image, and optional config and authorization fields) for SET/ADD. The deprecated rom field is accepted in place of image.
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")
  • For "annotations": object (for SET/ADD) or string/array of strings (for DEL)

Instances.UpdateInstancesRequestItem

A single update operation to be applied to an instance.
prop
​string · enum · required

The property to modify.

Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock
op
​string · enum · required

The operation to perform on the property.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": image reference string, or object with image url, credentials, headers and pull policy
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields) for SET/ADD, or array of schedule names for DEL. Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "plugins": array of plugin objects (with name, image, and optional config and authorization fields) for SET/ADD. The deprecated rom field is accepted in place of image.
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")
  • For "annotations": object (for SET/ADD) or string/array of strings (for DEL)

Instances.UpdateInstancesResponse

The response message for updating one or more instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.UpdateInstancesResponseUpdatedInstance

Per-item result for an update instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

The client-provided ID from the request.

Instances.UpdateTemplateInstanceByUUIDRequestBody

prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
autokill
image
roms
plugins
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

A client-provided identifier for tracking this operation in the response.

value
​

The value for the update operation. The type depends on the property and operation:

  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "autokill": object with time_ms field
  • For "image": image reference string or object (SET only)
  • For "roms": array of ROM objects (SET only)
  • For "plugins": array of plugin objects (SET only)

Instances.UpdateTemplateInstancesRequestItem

A single template instance update request item.
prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
autokill
image
roms
plugins
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

value
​

The value for the update operation. The type depends on the property and operation:

  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "autokill": object with time_ms field
  • For "image": image reference string or object (SET only)
  • For "roms": array of ROM objects (SET only)
  • For "plugins": array of plugin objects (SET only)

Instances.UpdateTemplateInstancesResponse

The response message for updating one or more template instance(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.UpdateTemplateInstancesResponseTemplateInstance

Per-item result for an update template instances operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

Client-provided operation ID.

Instances.WaitInstanceByUUIDRequestBody

Wait parameters.
state
​string · enum · required

The desired state to wait for. Default is running.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
timeout_s
​integer · int64

Timeout in seconds to wait for the instance to reach the desired state. If the timeout is reached, the request will fail with an error. A value of -1 means to wait indefinitely until the instance reaches the desired state. No wait performed for a value of 0.

Example: 2

Instances.WaitInstancesRequestItem

A single request item to wait for an instance's state.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

state
​string · enum

The desired state to wait for. Default is running.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
timeout_s
​integer · int64

Timeout in seconds to wait for the instance to reach the desired state. If the timeout is reached, the request will fail with an error. A value of -1 means to wait indefinitely until the instance reaches the desired state. No wait performed for a value of 0.

Example: 2

Instances.WaitInstancesResponse

The response message for waiting for one or more instance(s) to reach a certain state given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Instances.WaitInstancesResponseWaitedInstance

Per-item result for a wait instances operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Node.DataLicense

License information (admin only).
serial
​string · required

The serial number of the license certificate, hex-encoded.

valid
​boolean · required

Whether the license is currently valid.

features
​string[]

List of enabled features.

Node.HealthState

string · enum
Enum values:
unknown
healthy
degraded

The health state reported by a single health checker.

Node.HealthzResponse

Standard response envelope wrapping all API responses.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Node.HealthzResponseData

Additional data returned by the health check.
​object

The health state of each registered checker, keyed by checker name. Valid keys are "images", "systemd", and "user-defined"; a checker's key is only present if it is enabled. Checkers report only their aggregate state; per-check detail (e.g. which default image is missing, or which user-defined script failed) is not exposed here.

​object
​object

License information (admin only).

Services.ConnectionHandler

string · enum
Enum values:
tls
http
redirect

Connection handlers to use for the service.

Handlers define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing. You configure the handlers for every published service port individually.

There are currently 3 supported handlers:

HandlerDescription
tlsTerminate the TLS connection at the Unikraft Cloud gateway using our wildcard certificate issued for the kraft.cloud domain. The gateway forwards the unencrypted traffic to your application.
httpEnable HTTP mode on the load balancer to load balance on the level of individual HTTP requests. In this mode, only HTTP connections are accepted. If this option is not set the load balancer works in TCP mode and distributes TCP connections.
redirectRedirect traffic from the source port to the destination port.

Note that there is a set of constraints when publishing ports:

  • Port 80: MUST have "http" and MUST not have "tls" set;
  • Port 443: MUST have http and tls set;
  • The redirect handler can only be set on port 80 (HTTP) to redirect to port 443 (HTTPS);
  • All other ports MUST have tls and MUST not have http set.

Services.CreateServiceGroupRequest

The request message for creating a new service group.
​Services.Service[] · required

Services to expose. At least one service is required.

name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

Description of domains associated with the service group.

soft_limit
​integer · uint64

The soft limit is used by the Unikraft Cloud load balancer to decide when to wake up another standby instance.

For example, if the soft limit is set to 5 and the service consists of 2 standby instances, one of the instances receives up to 5 concurrent requests. The 6th parallel requests wakes up the second instance. If there are no more standby instances to wake up, the number of requests assigned to each instance will exceed the soft limit. The load balancer makes sure that when the number of in-flight requests goes down again, instances are put into standby as fast as possible.

Example: 1
hard_limit
​integer · uint64

The hard limit defines the maximum number of concurrent requests that an instance assigned to the this service can handle.

The load balancer will never assign more requests to a single instance. In case there are no other instances available, excess requests fail (i.e., they are blocked and not queued).

Example: 100
​object

Automatic delete-on-idle configuration.

Services.CreateServiceGroupRequestAutokill

Autokill configuration when creating a service group.
time_ms
​integer · uint64

Time in milliseconds after the service group becomes empty before it is deleted. A value of 0 disables autokill.

Services.CreateServiceGroupRequestDomain

A domain to attach when creating a service group.
name
​string · required

Publicly accessible domain name. If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: example.com.
​object

Use an existing certificate for the domain. If this field is specified, the domain must be associated with a valid certificate.

Services.CreateServiceGroupResponse

The response message for creating a new service group.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Services.DeleteServiceGroupsResponse

The response message for deleting of one or more service group(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Services.DeleteServiceGroupsResponseDeletedServiceGroup

Per-item result for a delete service groups operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Services.Domain

A domain name. Domain names are completely specified with all labels in the hierarchy of the DNS, having no parts omitted. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.
fqdn
​string · required

Publicly accessible domain name. If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: example.com.
​object

Use an existing certificate for the domain. If this field is specified, the domain must be associated with a valid certificate.

Services.GetServiceGroupsResponse

The response message for getting one or more service group(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Services.MutableServiceGroupOperation

string · enum
Enum values:
set
add
del

The mutable operations available on a service group's properties.

Services.MutableServiceGroupProperty

string · enum
Enum values:
services
domains
soft_limit
hard_limit
autokill

Mutable service group properties.

Services.Service

A service connects a public-facing port to an internal destination port on which an application instance listens on. Additional handlers can be defined for each published port in order to define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing.
port
​integer · uint32 · required

This is the public-facing port that the service will be accessible from on the Internet.

Example: 443
destination_port
​integer · uint32

The port number that the instance is listening on. This is the internal port which Unikraft Cloud will forward traffic to.

Example: 8080
protocol
​Services.ServiceProtocol · enum

Protocol for a service.

Enum values:
tcp
udp
ip
​string

Connection handlers to use for the service. Handlers define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing. You configure the handlers for every published service port individually.

Enum values:
tls
http
redirect

Services.ServiceGroup

A service group on Unikraft Cloud is used to describe how your application exposes its functionality to the outside world. Once defined, assigning an instance to the service will make it accessible from the Internet. An application, running as an instance, may expose one or more ports, e.g. it listens on port 80 because your application exposes a HTTP web service. This, along with a set of additional metadata defines how the "service" is configured and accessed. For example, a service may be configured to use TLS, or be bound to a specific domain name. When an instance is assigned to a service group, it immediately becomes accessible over the Internet on the exposed public port, using the set DNS name, and is routed to the set destination port. Note: If you do not specify a DNS name when you create a service and you indicate that the application exposes some ports, Unikraft Cloud will generates a random DNS name for you. Unikraft Cloud also supports custom domains like www.example.com and wildcard domains like *.example.com.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

created_at
​string · date-time · required

The time the service was created.

persistent
​boolean · required

Indicates if the service will stay remain even after the last instance detached. If this is set to false, the service will be deleted when the last instance detached from it. If this is set to true, the service will remain and can be reused by other instances. This is useful if you want to keep the service configuration, e.g., the published ports, handlers, and domains, even if there are no instances assigned to it.

Example: true
autoscale
​boolean · required

Indicates if the service has autoscale enabled. See the associated autoscale documentation for more information about how to set this up. Autoscale policies can be set up after the service has been created.

Example: true
soft_limit
​integer · uint64 · required

The soft limit is used by the Unikraft Cloud load balancer to decide when to wake up another standby instance. For example, if the soft limit is set to 5 and the service consists of 2 standby instances, one of the instances receives up to 5 concurrent requests. The 6th parallel requests wakes up the second instance. If there are no more standby instances to wake up, the number of requests assigned to each instance will exceed the soft limit. The load balancer makes sure that when the number of in-flight requests goes down again, instances are put into standby as fast as possible.

Example: 1
hard_limit
​integer · uint64 · required

The hard limit defines the maximum number of concurrent requests that an instance assigned to the this service can handle. The load balancer will never assign more requests to a single instance. In case there are no other instances available, excess requests fail (i.e., they are blocked and not queued).

Example: 100
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

List of published network ports for this service and the destination port to which Unikraft Cloud will forward traffic to. Additional handlers can be defined for each published port in order to define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing.

List of domains associated with the service. Domains are used to access the service over the Internet.

List of instances assigned to the service.

​object

Automatic delete-on-idle configuration.

Services.ServiceGroupAutokill

Autokill configuration for a service group.
time_ms
​integer · uint64

Time in milliseconds after the service group becomes empty before it is deleted. A value of 0 disables autokill.

Services.ServiceGroupInstance

An instance belonging to a service group.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Services.ServiceProtocol

string · enum
Enum values:
tcp
udp

Protocol for a service.

Services.UpdateServiceGroupByUUIDRequestBody

prop
​string · enum · required

The property to modify.

Enum values:
services
domains
soft_limit
hard_limit
autokill
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Services.UpdateServiceGroupsRequestItem

A single update operation to be applied to a service group.
prop
​string · enum · required

The property to modify.

Enum values:
services
domains
soft_limit
hard_limit
autokill
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Services.UpdateServiceGroupsResponse

The response message for updating one or more service group(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Services.UpdateServiceGroupsResponseUpdatedServiceGroup

Per-item result for an update service groups operation.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

The client-provided ID from the request.

message
​string

An optional message providing additional information about the status.

error
​integer · int32

An optional error code providing additional information about the status.

Users.Quotas

Quotas with per-item response envelope fields merged in.
uuid
​string · uuid · required

The UUID of the quota.

​object · required

Used quota.

​object · required

Configured quota limits.

​object · required

Additional limits.

status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

Users.QuotasLimits

Additional resource limits.
min_memory_mb
​integer · int64 · required

Minimum amount of memory assigned to live instances in megabytes

Example: 16
max_memory_mb
​integer · int64 · required

Maximum amount of memory assigned to live instances in megabytes

Example: 2048
min_volume_mb
​integer · int64 · required

Minimum size of a volume in megabytes

Example: 1
max_volume_mb
​integer · int64 · required

Maximum size of a volume in megabytes

Example: 1024
min_autoscale_size
​integer · int64 · required

Minimum size of an autoscale group

Example: 1
max_autoscale_size
​integer · int64 · required

Maximum size of an autoscale group

Example: 16
min_vcpus
​integer · int64 · required

Minimum number of vCPUs

Example: 2
max_vcpus
​integer · int64 · required

Maximum number of vCPUs

Example: 4

Users.QuotasResponse

The response message for getting the quota of a user given their UUID.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Users.QuotasStats

Quota statistics for resource usage.
instances
​integer · int64 · required

Number of instances.

live_instances
​integer · int64 · required

Number of instances that are not in the stopped state.

live_vcpus
​integer · int64 · required

Number of vCPUs.

live_memory_mb
​integer · int64 · required

Amount of memory assigned to instances that are not in the stopped state in megabytes.

service_groups
​integer · int64 · required

Number of service groups.

services
​integer · int64 · required

Number of published network ports over all existing services.

volumes
​integer · int64 · required

Number of volumes.

total_volume_mb
​integer · int64 · required

Total size of all volumes in megabytes.

Users.ResumeUsersRequestItem

A single request item to resume a user account.
uuid
​string · uuid · required

The UUID of the user.

Users.ResumeUsersResponse

The response message for resuming one or more user account(s) given their UUID(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Users.ResumeUsersResponseResumedInstance

An instance that a resume users operation restored.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
previous_state
​string · enum · required

The previous state of the instance before the resume operation was invoked.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
on_resume
​string · enum · required

What the resume operation did with this instance.

Enum values:
standby
start
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Users.ResumeUsersResponseResumedUser

Per-item result for a resume users operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

suspended
​boolean · required

Whether the user account is still suspended after this request, for example because it was suspended again concurrently.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

The instances of the user that were restored, as recorded when the user was suspended. Instances that had nothing to restore are not listed. An instance that failed to start keeps its record, so a later resume tries again.

Users.SuspendUserByUUIDRequestBody

Parameters for suspending a user account.
suspend_instances
​boolean

Whether to also bring all instances of the user to rest. Autostart is disabled, running instances are suspended (or stopped if they cannot be suspended, or if they only return to standby and are not stateful), and pending restarts are cancelled. Instances that are draining, stopping, or in a start-stop cycle finish that transition first. Booting instances are brought to rest once they are running. Without this flag only the account is suspended and its instances are left as they are.

Example: true

Users.SuspendUsersRequestItem

A single request item to suspend a user account.
uuid
​string · uuid · required

The UUID of the user.

suspend_instances
​boolean

Whether to also bring all instances of the user to rest. Autostart is disabled, running instances are suspended (or stopped if they cannot be suspended, or if they only return to standby and are not stateful), and pending restarts are cancelled. Instances that are draining, stopping, or in a start-stop cycle finish that transition first. Booting instances are brought to rest once they are running. Without this flag only the account is suspended and its instances are left as they are.

Example: true

Users.SuspendUsersResponse

The response message for suspending one or more user account(s) given their UUID(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Users.SuspendUsersResponseSuspendedInstance

An instance that a suspend users operation brought to rest.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The current state of the instance.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
previous_state
​string · enum · required

The previous state of the instance before the suspend operation was invoked.

Enum values:
stopped
starting
running
draining
stopping
template
standby
deleted
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

on_resume
​string · enum

What resuming the user will do with this instance. Absent if the instance was already at rest and resuming the user leaves it unchanged.

Enum values:
standby
start

Users.SuspendUsersResponseSuspendedUser

Per-item result for a suspend users operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

suspended
​boolean · required

Whether the user account is suspended after this request.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

The instances of the user that were brought to rest. Only present if suspend_instances was set in the request.

Users.UserResumeAction

string · enum
Enum values:
standby
start

What resuming a user does with an instance that the suspension of the user brought to rest.

ActionDescription
standbyAutostart is enabled again. The instance is in standby and starts on the next incoming request.
startThe instance is started.

Volumes.AttachVolumeByUUIDRequestBody

​object · required

UUID or name of the instance to attach the volume to.

at
​string · required

Path of the mountpoint.

The path must be absolute, not contain . and .. components, and not contain colons (:). The path must point to an empty directory. If the directory does not exist, it is created.

Example: /mnt/my-volume
readonly
​boolean

Whether the volume should be mounted read-only.

Example: false

Volumes.AttachVolumesRequestItem

A single request item to attach a volume to an instance.
​object · required

UUID or name of the instance to attach the volume to.

at
​string · required

Path of the mountpoint.

The path must be absolute, not contain . and .. components, and not contain colons (:). The path must point to an empty directory. If the directory does not exist, it is created.

Example: /mnt/my-volume
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

readonly
​boolean

Whether the volume should be mounted read-only.

Example: false

Volumes.AttachVolumesResponse

The response message for attaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.AttachVolumesResponseAttachedVolume

Per-item result for an attach volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.CloneVolumeByUUIDRequestBody

vol_name
​string

The name of the new cloned volume. If not provided, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.

Example: funky-vol-t7qumh5j
quota_policy
​string · enum

The quota policy for the new cloned volume. If not provided, the quota policy of the source volume is used.

Enum values:
static
dynamic
tags
​string[]

A list of tags to assign to the new cloned volume.

access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx

Volumes.CloneVolumesRequestItem

A single request item to clone a volume.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

vol_name
​string

The name of the new cloned volume. If not provided, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.

Example: funky-vol-t7qumh5j
quota_policy
​string · enum

The quota policy for the new cloned volume. If not provided, the quota policy of the source volume is used.

Enum values:
static
dynamic
tags
​string[]

A list of tags to assign to the new cloned volume.

access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx

Volumes.CloneVolumesResponse

The response message for cloning one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.CloneVolumesResponseVolume

Per-item result for a clone volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The state of the volume.

Enum values:
uninitialized
initializing
available
idle
mounted
busy
error
template
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.CreateTemplateVolumesResponse

The response message for converting one or more volume(s) to templates.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.CreateTemplateVolumesResponseTemplateVolume

Per-item result for a create template volume operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The state of the volume.

Enum values:
uninitialized
initializing
available
idle
mounted
busy
error
template
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.CreateVolumeRequest

The request message for creating a volume.
name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

size_mb
​integer · uint64
host_path
​string

An identifier for a resource — either a name or a UUID, but not both.

quota_policy
​Volumes.VolumeQuotaPolicy · enum

Quota policy for a volume.

Enum values:
static
dynamic
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: size_mb
type = object · requires: host_path
type = object · requires: template
Properties for Variant 1:
size_mb
​integer · uint64 · required
name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

host_path
​string

An identifier for a resource — either a name or a UUID, but not both.

quota_policy
​Volumes.VolumeQuotaPolicy · enum

Quota policy for a volume.

Enum values:
static
dynamic
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object

Volumes.CreateVolumeResponse

The response message for creating a volume.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.CreateVolumeResponseVolume

Per-item result for a create volume operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

state
​string · enum · required

The state of the volume.

Enum values:
uninitialized
initializing
available
idle
mounted
busy
error
template
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.DeleteTemplateVolumesResponse

The response message for deleting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.DeleteTemplateVolumesResponseTemplateVolume

Per-item result for a delete template volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.DeleteVolumesResponse

The response message for deleting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.DeleteVolumesResponseDeletedVolume

Per-item result for a delete volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.DetachVolumeByUUIDRequestBody

​object

UUID or name of the instance to detach the volume from. If not specified, the volume is detached from all instances.

Volumes.DetachVolumesRequestItem

A single request item to detach a volume from an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

​object

UUID or name of the instance to detach the volume from. If not specified, the volume is detached from all instances.

Volumes.DetachVolumesResponse

The response message for detaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.DetachVolumesResponseDetachedVolume

Per-item result for a detach volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.GetTemplateVolumesResponse

The response message for getting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.GetVolumesResponse

The response message for getting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.MutableTemplateVolumeOperation

string · enum
Enum values:
set
add
del

Mutable template volume operations.

Volumes.MutableTemplateVolumeProperty

string · enum
Enum values:
tags
delete_lock

Mutable template volume properties.

Volumes.MutableVolumeOperation

string · enum
Enum values:
set
add
del

Mutable volume operations.

Volumes.MutableVolumeProperty

string · enum
Enum values:
size_mb
tags
quota_policy
delete_lock

Mutable volume properties.

Volumes.UpdateTemplateVolumeByUUIDRequestBody

prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Volumes.UpdateTemplateVolumesRequestItem

A single update operation to be applied to a template volume.
prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Volumes.UpdateTemplateVolumesResponse

The response message for updating one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.UpdateTemplateVolumesResponseTemplateVolume

Per-item result for an update template volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

The client-provided ID from the request.

Volumes.UpdateVolumeByUUIDRequestBody

prop
​string · enum · required

The property to modify.

Enum values:
size_mb
tags
quota_policy
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Volumes.UpdateVolumesRequestItem

A single update operation to be applied to a volume.
prop
​string · enum · required

The property to modify.

Enum values:
size_mb
tags
quota_policy
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

A client-provided identifier for tracking this operation in the response.

Example: op-1
value
​

The value for the update operation. The type depends on the property and operation:

  • For "image": string
  • For "args": string or array of strings
  • For "env": object (for SET/ADD) or string/array of strings (for DEL)
  • For "memory_mb": integer
  • For "vcpus": integer
  • For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
  • For "tags": array of strings
  • For "delete_lock": boolean
  • For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
  • For "autokill": object with time_ms and num_requests fields
  • For "hostname": string (valid DNS label)
  • For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
  • For "dependencies": array of instance identifiers (name or UUID)
  • For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Volumes.UpdateVolumesResponse

The response message for updating one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

A list of errors which may have occurred during the request.

Volumes.UpdateVolumesResponseUpdatedVolume

Per-item result for an update volumes operation.
status
​string · enum · required

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

id
​string

The client-provided ID from the request.

Volumes.Volume

A volume represents a storage device that can be attached to an instance.
uuid
​string · uuid · required

The UUID of the resource.

name
​string · required

The human-readable name of the resource.

created_at
​string · date-time · required

The time the volume was created.

state
​string · enum · required

Current state of the volume.

Enum values:
uninitialized
initializing
available
idle
mounted
busy
error
template
size_mb
​integer · uint64 · required

The size of the volume in megabytes.

Example: 64
persistent
​boolean · required

Indicates if the volume will stay alive when the last instance is deleted that this volume is attached to.

Example: true
quota_policy
​string · enum · required

Either static or dynamic reservation.

Enum values:
static
dynamic
status
​string · enum

Indicates whether the operation was successful for this item.

Enum values:
success
error
partial_success
message
​string

An optional message providing additional information.

error
​integer · int32

An optional error code.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

List of instances that this volume is attached to.

List of instances that have this volume mounted. This does not apply to template volumes.

tags
​string[]

The tags associated with the volume. Maximum 16 tags are allowed, and each tag may not be longer than 256 characters.

delete_lock
​boolean

If set to true, the volume cannot be deleted.

Example: false
free_mb
​integer · uint32

The amount of free space in the volume in megabytes.

Example: 32
filesystem
​string

The filesystem type of this volume. Without custom configuration, this is either ext4 or virtiofs.

Example: ext4
host_path
​string

Host path backing this managed volume. This field is only available for managed volumes and users with appropriate permissions.

Example: /usr/lib/unikraft/volumes/my-vol
access_mode
​string · enum

The access mode of the volume, controlling volume sharing behavior. Defaults to rwo if not specified.

Enum values:
rwo
rox
rwx
uid
​integer · uint32

Guest UID for managed volumes (host_path mode only).

gid
​integer · uint32

Guest GID for managed volumes (host_path mode only).

​object

Optional script arguments that were applied to the custom volume filesystem initialization scripts.

Example: {"arg1":"value1","arg2":"value2"}

Volumes.VolumeAccessMode

string · enum
Enum values:
rwo
rox
rwx

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Volumes.VolumeInstanceID

An instance a volume is attached to.
uuid
​string · uuid · required

The UUID of the instance. This is a unique identifier for the instance that is generated when the instance is created. The UUID is used to reference the instance in API calls and can be used to identify the instance in all API calls that require an instance identifier.

Example: 12345678-90ab-cdef-1234-567890abcdef
name
​string

The name of the instance. This is a human-readable name that can be used to identify the instance. The name must be unique within the context of your account. If no name is specified, a random name is generated for you. The name can also be used to identify the instance in API calls.

Example: funky-vol-g7gum5cj
node
​string

The name of the node the instance is placed on.

Volumes.VolumeInstanceMount

An instance mount of a volume.
uuid
​string · uuid · required

The UUID of the instance that the volume is mounted in.

name
​string · required

The name of the instance that the volume is mounted in.

readonly
​boolean · required

Whether the volume is mounted read-only or read-write.

node
​string

The name of the node the resource is placed on. Only present on metros that span multiple nodes.

Volumes.VolumeQuotaPolicy

string · enum
Enum values:
static
dynamic

Quota policy for a volume.

Volumes.VolumeState

string · enum
Enum values:
uninitialized
initializing
available
idle
mounted
busy
error
template

VolumeState defines the state of a volume at a given moment.