Instances

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

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"}).

The arguments to pass to the instance when it starts.

Environment variables to set for the instance.

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

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.

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.

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.

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

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

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.

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

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

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.

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.

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.

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.

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 to associate with the instance.

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.

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.

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

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.

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

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.

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.

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.

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.

The default gateway to configure inside the guest.

The DNS resolver to configure inside the guest.

Network interfaces to attach to the instance.

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.

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.

The property to modify.

The operation to perform on the property.

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

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

The property to modify.

The operation to perform.

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

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)

The property to modify.

The operation to perform on the property.

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

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)

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

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