API – Dicer

API

The gRPC API every client uses: the service dicerd.v1.DaemonService, and the messages and enums it takes and returns. It is generated from proto/dicerd/v1, whose generated code is what clients call; see Using the API.

DaemonService

DaemonService manages virtual machines on a single host.

There is no notion of a cluster, a node or placement: the daemon owns the machine it runs on. To manage several hosts, run a daemon on each and point a client at whichever one you mean.

Creating an instance records its definition; it does not boot it. Use StartInstance for that. The two are separate so a definition can be written, reviewed and version-controlled before anything runs.

Resources are addressed by name or ID wherever a request has a name field. Methods follow the resource-oriented design of https://google.aip.dev: standard methods return the resource they act on, and deletes return Empty.

A failed call ends with a status whose code says what kind of failure it was, and whose message says it for a person:

NOT_FOUND: the resource named does not exist.
ALREADY_EXISTS: a resource with that name exists already.
INVALID_ARGUMENT: the request is malformed, whatever the host’s state.
FAILED_PRECONDITION: the resource is in the wrong state for the call, such as deleting a running instance.
RESOURCE_EXHAUSTED: the host has too little left: CPU or memory for an instance, addresses on a network.
UNAVAILABLE: something the daemon needs cannot be reached: a registry, a guest’s agent. Trying again may work.
PERMISSION_DENIED: the guest refused, such as a file it protects.
UNIMPLEMENTED: the daemon, or an instance’s guest agent, is too old for the call.
INTERNAL: anything else: the daemon failed.

Method	Request	Response	Description
`CreateInstance`	`CreateInstanceRequest`	`Instance`	CreateInstance records an instance definition without starting it, unless start is set.
`UpdateInstance`	`UpdateInstanceRequest`	`Instance`	UpdateInstance modifies the definition of a stopped instance.
`RenameInstance`	`RenameInstanceRequest`	`Instance`	RenameInstance changes a stopped instance’s name. The instance keeps its ID, its disks and its address; only what people call it changes.
`StartInstance`	`StartInstanceRequest`	`Instance`	StartInstance boots a defined instance.
`StopInstance`	`StopInstanceRequest`	`Instance`	StopInstance shuts a running instance down, keeping its definition, overlay disk and address.
`PauseInstance`	`PauseInstanceRequest`	`Instance`	PauseInstance halts a running instance’s vCPUs, keeping it resident.
`ResumeInstance`	`ResumeInstanceRequest`	`Instance`	ResumeInstance continues a paused instance.
`DeleteInstance`	`DeleteInstanceRequest`	`google.protobuf.Empty`	DeleteInstance removes an instance and its overlay disk. It refuses a running instance unless force is set.
`ListInstances`	`ListInstancesRequest`	`ListInstancesResponse`	ListInstances returns every defined instance.
`GetInstance`	`GetInstanceRequest`	`Instance`	GetInstance returns one instance.
`GetInstanceLogs`	`GetInstanceLogsRequest`	stream `InstanceLogChunk`	GetInstanceLogs streams an instance’s log. The guest’s console is kept with the instance, so it can be read after a stop to explain one.
`CreateSnapshot`	`CreateSnapshotRequest`	`Snapshot`	CreateSnapshot freezes a running or paused instance to disk: its memory, its device state and a copy of its overlay disk. A running instance is paused for as long as it takes and resumed afterwards.
`ListSnapshots`	`ListSnapshotsRequest`	`ListSnapshotsResponse`	ListSnapshots returns an instance’s snapshots, oldest first.
`GetSnapshot`	`GetSnapshotRequest`	`Snapshot`	GetSnapshot returns one snapshot.
`DeleteSnapshot`	`DeleteSnapshotRequest`	`google.protobuf.Empty`	DeleteSnapshot removes a snapshot.
`RestoreSnapshot`	`RestoreSnapshotRequest`	`Instance`	RestoreSnapshot puts a stopped instance back to the moment a snapshot was taken and resumes it. Anything written to its disk since is discarded.
`ExecInstance`	stream `ExecInstanceRequest`	stream `ExecInstanceResponse`	ExecInstance runs a command inside a running instance. The first client message must be an ExecInstanceStart; subsequent messages carry stdin data or terminal resize events.
`CopyToInstance`	stream `CopyToInstanceRequest`	`google.protobuf.Empty`	CopyToInstance writes a file or directory into a running instance. The first message must be a CopyToInstanceStart; the rest carry a tar archive of it, in chunks, which lands at the path as cp would put it.
`CopyFromInstance`	`CopyFromInstanceRequest`	stream `CopyFromInstanceResponse`	CopyFromInstance reads a file or directory out of a running instance, as a tar archive in chunks.
`CreateNetwork`	`CreateNetworkRequest`	`Network`	CreateNetwork defines a host-local network. Its bridge is brought up when the first instance on it starts.
`ListNetworks`	`ListNetworksRequest`	`ListNetworksResponse`	ListNetworks returns every network.
`GetNetwork`	`GetNetworkRequest`	`Network`	GetNetwork returns one network.
`DeleteNetwork`	`DeleteNetworkRequest`	`google.protobuf.Empty`	DeleteNetwork removes a network that no instance references.
`ListNetworkAllocations`	`ListNetworkAllocationsRequest`	`ListNetworkAllocationsResponse`	ListNetworkAllocations reports which addresses are assigned on a network. Allocation itself is a side effect of starting an instance and has no separate RPC.
`CreateVolume`	`CreateVolumeRequest`	`Volume`	CreateVolume provisions a persistent block volume.
`ListVolumes`	`ListVolumesRequest`	`ListVolumesResponse`	ListVolumes returns every volume.
`GetVolume`	`GetVolumeRequest`	`Volume`	GetVolume returns one volume.
`DeleteVolume`	`DeleteVolumeRequest`	`google.protobuf.Empty`	DeleteVolume removes a volume that no instance references.
`PullImage`	`PullImageRequest`	stream `PullImageProgress`	PullImage fetches an OCI image and converts it to a bootable root filesystem, reporting progress as it goes. The last message carries the image, which is ready to boot.
`ListImages`	`ListImagesRequest`	`ListImagesResponse`	ListImages returns every pulled image.
`GetImage`	`GetImageRequest`	`Image`	GetImage returns one pulled image.
`DeleteImage`	`DeleteImageRequest`	`google.protobuf.Empty`	DeleteImage removes a pulled image. It refuses an image an instance is defined to boot from, unless force is set.
`PruneImages`	`PruneImagesRequest`	`PruneImagesResponse`	PruneImages removes every image no instance is defined to boot from.
`ImportKernel`	`ImportKernelRequest`	`Kernel`	ImportKernel records a guest kernel by URL. It is downloaded the first time an instance boots with it.
`ListKernels`	`ListKernelsRequest`	`ListKernelsResponse`	ListKernels returns every imported kernel.
`GetKernel`	`GetKernelRequest`	`Kernel`	GetKernel returns one kernel.
`DeleteKernel`	`DeleteKernelRequest`	`google.protobuf.Empty`	DeleteKernel removes a kernel that no instance references.
`GetHostInfo`	`GetHostInfoRequest`	`GetHostInfoResponse`	GetHostInfo reports what the daemon is: its version, the hypervisors it carries, and how it is reached.
`GetResources`	`GetResourcesRequest`	`GetResourcesResponse`	GetResources reports how much CPU and memory instances may be given, how much they hold, and how full the data directory’s disk is.
`GetEvents`	`GetEventsRequest`	stream `GetEventsResponse`	GetEvents streams what has happened to the resources on this host: the history kept, oldest first, in batches, then, with follow, each new event as it happens, none missed between the two. A follower that does not keep up is disconnected with RESOURCE_EXHAUSTED rather than slowing the host.

Messages

CopyFromInstanceRequest

Field	Type	Description
`name`	`string`	The instance to copy from.
`path`	`string`	The file or directory to read. A relative path is taken from the guest’s root directory.

CopyFromInstanceResponse

Field	Type	Description
`data`	`bytes`	The next chunk of the tar archive.

CopyToInstanceRequest

Field	Type	Description
`start`	`CopyToInstanceStart`	One of `payload`.
`data`	`bytes`	One of `payload`. The next chunk of the tar archive.

CopyToInstanceStart

CopyToInstanceStart is the first message on a CopyToInstance stream.

Field	Type	Description
`name`	`string`	The instance to copy into.
`path`	`string`	Where the archive’s contents go inside it: into it, if it is a directory; in its place, if it is a file; at it, if nothing is there. A relative path is taken from the guest’s root directory.

CreateInstanceRequest

Field	Type	Description
`name`	`string`
`image_ref`	`string`
`hypervisor_type`	`HypervisorType`	Unspecified means Cloud Hypervisor.
`hypervisor_version`	`string`	A version that hypervisor ships; the newest by default.
`kernel_name`	`string`	Empty means the daemon’s default kernel: see GetHostInfoResponse.default_kernel.
`kernel_args`	`string`
`vcpus`	`int32`
`memory_bytes`	`int64`
`disk_bytes`	`int64`
`network_name`	`string`	Empty means the daemon’s default network: see GetHostInfoResponse.default_network.
`static_ip`	`string`
`mounts`	repeated `Mount`
`env`	repeated `CreateInstanceRequest.EnvEntry`
`cmd`	repeated `string`
`labels`	repeated `CreateInstanceRequest.LabelsEntry`
`hostname`	`string`
`restart_policy`	`RestartPolicy`
`health_check`	`HealthCheck`
`init_mode`	`InitMode`	How the guest starts the command. Unspecified means auto.
`start`	`bool`	Boots the instance immediately after defining it.
`ports`	repeated `PortMapping`
`remove_on_exit`	`bool`	Deletes the instance once it stops, whether its guest ended on its own or someone stopped it. The daemon does the deleting, so it happens even if whoever asked for it has gone. An instance that its restart policy will start again is not deleted.

CreateInstanceRequest.EnvEntry

Field	Type	Description
`key`	`string`
`value`	`string`

CreateInstanceRequest.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

CreateNetworkRequest

Field	Type	Description
`name`	`string`
`subnet`	`string`
`gateway`	`string`
`mtu`	`int32`
`nameservers`	repeated `string`
`isolated`	`bool`

CreateSnapshotRequest

Field	Type	Description
`instance`	`string`	The instance to snapshot.
`name`	`string`	The snapshot’s name. Generated from the current time when empty.

CreateVolumeRequest

Field	Type	Description
`name`	`string`
`size_bytes`	`int64`

DeleteImageRequest

Field	Type	Description
`ref`	`string`
`force`	`bool`	Removes the image even if an instance is defined to boot from it. That instance will pull it again on its next start.

DeleteInstanceRequest

Field	Type	Description
`name`	`string`
`force`	`bool`	Stops a running instance before deleting it.

DeleteKernelRequest

Field	Type	Description
`name`	`string`

DeleteNetworkRequest

Field	Type	Description
`name`	`string`

DeleteSnapshotRequest

Field	Type	Description
`instance`	`string`
`name`	`string`

DeleteVolumeRequest

Field	Type	Description
`name`	`string`

DiskUsage

DiskUsage is how full the filesystem holding the data directory is, and how much has been promised on it. Disks are sparse, so provisioned may be far more than the filesystem’s size without anything being wrong – until the guests fill them.

Field	Type	Description
`path`	`string`	The data directory.
`total_bytes`	`int64`
`free_bytes`	`int64`	What can still be written.
`provisioned_bytes`	`int64`	The sizes of every instance’s overlay disk and every volume, added up.

Event

Event is one thing that happened to one resource on this host.

Field	Type	Description
`time`	`google.protobuf.Timestamp`
`kind`	`EventKind`
`id`	`string`	The resource’s ID, which tells apart resources that had the same name at different times. Empty for a resource known only by its name, such as an image.
`name`	`string`
`action`	`EventAction`
`message`	`string`	What happened, in a line, for a person.
`attributes`	repeated `Event.AttributesEntry`	What happened, for a program: exit_code, restart_count, digest.

Event.AttributesEntry

Field	Type	Description
`key`	`string`
`value`	`string`

ExecInstanceRequest

Field	Type	Description
`start`	`ExecInstanceStart`	One of `payload`.
`stdin`	`bytes`	One of `payload`.
`resize`	`ExecInstanceResize`	One of `payload`.

ExecInstanceResize

ExecInstanceResize resizes the remote terminal window.

Field	Type	Description
`rows`	`uint32`
`cols`	`uint32`

ExecInstanceResponse

Field	Type	Description
`stdout`	`bytes`	One of `payload`.
`stderr`	`bytes`	One of `payload`.
`exit_code`	`int32`	One of `payload`. The command’s exit status. Always the last message on the stream.

ExecInstanceStart

ExecInstanceStart is the first message on an ExecInstance stream.

Field	Type	Description
`name`	`string`	The instance to run the command in.
`command`	repeated `string`	The command and its arguments. Defaults to /bin/sh.
`tty`	`bool`	Whether to allocate a pseudo-terminal.
`cwd`	`string`	The working directory inside the guest.
`timeout_seconds`	`int32`	Kills the command after this many seconds. Zero means no limit.
`rows`	`uint32`	The initial terminal size, when tty is set.
`cols`	`uint32`
`env`	repeated `ExecInstanceStart.EnvEntry`	Environment variables added to the command’s environment.

ExecInstanceStart.EnvEntry

Field	Type	Description
`key`	`string`
`value`	`string`

GetEventsRequest

GetEventsRequest picks events: every one, unless narrowed.

Field	Type	Description
`kind`	`EventKind`	Unspecified picks every kind.
`id`	`string`
`name`	`string`	The resource’s name. An image’s may be given as it is pulled: busybox:latest picks the events about docker.io/library/busybox:latest.
`since`	`google.protobuf.Timestamp`	Only events at or after this time.
`limit`	`int32`	Only the last this many events of the history. Zero means all of it.
`follow`	`bool`	Keep streaming new events after the history.

GetEventsResponse

GetEventsResponse is a batch of events, oldest first.

Field	Type	Description
`events`	repeated `Event`
`caught_up`	`bool`	Set on the last batch of the history, sent even if the history is empty: what follows, if the request follows, is new. A client can lay out the history as a whole before it shows any of it.

GetHostInfoRequest

GetHostInfoResponse

Field	Type	Description
`version`	`string`
`hostname`	`string`
`hypervisors`	repeated `HypervisorInfo`	The hypervisors this daemon can start instances with.
`api_addresses`	repeated `string`	The addresses the API is served on over TCP, for a client being pointed at this daemon. Empty if it is not served over TCP.
`default_kernel`	`string`	The kernel an instance created without one boots with: the one the daemon’s configuration names, or else the only kernel there is. Empty if there is no such kernel, and an instance must name one.
`default_network`	`string`	The network an instance created without one attaches to, chosen as the default kernel is.

GetImageRequest

Field	Type	Description
`ref`	`string`

GetInstanceLogsRequest

Field	Type	Description
`name`	`string`
`source`	`LogSource`
`tail_lines`	`int32`	Limits the output to the last lines. Zero means all of it.
`follow`	`bool`	Keeps the stream open, sending new output until the instance stops.

GetInstanceRequest

Field	Type	Description
`name`	`string`

GetKernelRequest

Field	Type	Description
`name`	`string`

GetNetworkRequest

Field	Type	Description
`name`	`string`

GetResourcesRequest

GetResourcesResponse

Field	Type	Description
`cpu`	`ResourceCapacity`	vCPUs, counted in vCPUs.
`memory`	`ResourceCapacity`	Guest memory, counted in bytes.
`disk`	`DiskUsage`	The filesystem holding the data directory. Reported, not enforced.
`instances`	repeated `InstanceResources`	The instances holding CPU and memory – those starting, running or paused – in name order.

GetSnapshotRequest

Field	Type	Description
`instance`	`string`
`name`	`string`

GetVolumeRequest

Field	Type	Description
`name`	`string`

Health

Health is what an instance’s health check has found. An unhealthy instance is restarted if its restart policy would restart it after a failure, and otherwise left running.

Field	Type	Description
`status`	`HealthStatus`
`failing_streak`	`int32`	How many probes in a row have failed.
`last_check_time`	`google.protobuf.Timestamp`
`last_output`	`string`	What the last probe said. Truncated.
`check`	`HealthCheck`	The check being run: the instance’s, or its image’s, with the defaults filled in.

HealthCheck

HealthCheck is how an instance’s health is checked: one probe, run inside the guest by its agent, and when to run it. Unset timings take the defaults: every 10s, a 5s timeout, no start period and 3 retries.

Field	Type	Description
`exec`	`HealthCheckExec`	One of `probe`. Healthy when the command exits 0.
`http`	`HealthCheckHTTP`	One of `probe`. Healthy when a GET on the guest’s loopback address answers 2xx or 3xx.
`tcp`	`HealthCheckTCP`	One of `probe`. Healthy when a connection to the guest’s loopback address opens.
`interval`	`google.protobuf.Duration`	The time between the end of one probe and the start of the next.
`timeout`	`google.protobuf.Duration`	How long a probe may take; one that overruns has failed.
`start_period`	`google.protobuf.Duration`	How long after a start failures do not count.
`retries`	`int32`	How many failures in a row make the instance unhealthy.
`disabled`	`bool`	Switches health checking off, the image’s check included. Nothing else may be set with it.

HealthCheckExec

Field	Type	Description
`command`	repeated `string`

HealthCheckHTTP

Field	Type	Description
`port`	`uint32`
`path`	`string`	Defaults to /.

HealthCheckTCP

Field	Type	Description
`port`	`uint32`

HypervisorInfo

HypervisorInfo is a hypervisor the daemon carries, and the versions of it an instance may name.

Field	Type	Description
`type`	`HypervisorType`
`versions`	repeated `string`	The versions available, the one an instance gets by default first.
`is_default`	`bool`	Whether this is the hypervisor an instance gets when it names none.

Image

Image is a pulled, converted image. Pulling is synchronous, so an image either exists and is bootable or the pull returned an error; there is no state to report.

Field	Type	Description
`name`	`string`
`digest`	`string`
`size_bytes`	`int64`
`create_time`	`google.protobuf.Timestamp`
`update_time`	`google.protobuf.Timestamp`
`health_check`	`HealthCheck`	The HEALTHCHECK the image declares, which instances of it run unless they set their own. Unset if it declares none.
`last_used_time`	`google.protobuf.Timestamp`	When the image was last pulled or in use: by an instance defined to boot from it, a running guest or a snapshot. Garbage collection judges it by this.

ImportKernelRequest

Field	Type	Description
`name`	`string`
`url`	`string`
`arch`	`Architecture`
`sha256`	`string`	The expected SHA-256 of the download, hex-encoded. Verified when set.

Instance

Instance combines an instance’s definition with its observed runtime state. Fields from state onwards are output only and are empty when the instance is not running.

Field	Type	Description
`id`	`string`
`name`	`string`
`hostname`	`string`
`image_ref`	`string`
`hypervisor_type`	`HypervisorType`
`hypervisor_version`	`string`	A version that hypervisor ships; the newest by default.
`kernel_name`	`string`
`kernel_args`	`string`
`vcpus`	`int32`
`memory_bytes`	`int64`
`disk_bytes`	`int64`
`network_name`	`string`
`static_ip`	`string`
`mounts`	repeated `Mount`
`env`	repeated `Instance.EnvEntry`
`cmd`	repeated `string`
`labels`	repeated `Instance.LabelsEntry`
`restart_policy`	`RestartPolicy`
`create_time`	`google.protobuf.Timestamp`
`update_time`	`google.protobuf.Timestamp`
`state`	`InstanceState`
`state_error`	`string`
`hypervisor_pid`	`int64`
`vsock_cid`	`int64`
`ip`	`string`
`mac`	`string`
`start_time`	`google.protobuf.Timestamp`
`ports`	repeated `PortMapping`
`exit_code`	optional `int32`	One of `_exit_code`. The exit code the guest reported when it last ended on its own: its workload’s, or 0 for a guest that powered itself off. Unset if it has not ended since it was last started, or ended without saying how.
`finish_time`	`google.protobuf.Timestamp`	When the guest last ended on its own.
`restart_count`	`int32`	How many times in a row the restart policy has started the instance again. A start a user asks for resets it.
`next_restart_time`	`google.protobuf.Timestamp`	When a Restarting instance is due to start again.
`health_check`	`HealthCheck`	How the instance’s health is checked, overriding its image’s. Unset means the image’s, if it declares one.
`health`	`Health`	What the health check of the running instance has found. Unset if it is not running, or has no check.
`init_mode`	`InitMode`	How the guest starts the command. See CreateInstanceRequest.init_mode.
`remove_on_exit`	`bool`	Whether the instance is deleted once it stops. See CreateInstanceRequest.remove_on_exit.

Instance.EnvEntry

Field	Type	Description
`key`	`string`
`value`	`string`

Instance.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

InstanceLogChunk

Field	Type	Description
`data`	`bytes`

InstanceResources

InstanceResources is what one instance holds.

Field	Type	Description
`name`	`string`
`state`	`InstanceState`
`vcpus`	`int32`
`memory_bytes`	`int64`

Kernel

Kernel is a guest kernel image available to instances.

Field	Type	Description
`id`	`string`
`name`	`string`
`arch`	`Architecture`
`url`	`string`
`sha256`	`string`
`create_time`	`google.protobuf.Timestamp`
`update_time`	`google.protobuf.Timestamp`

ListImagesRequest

ListImagesResponse

Field	Type	Description
`images`	repeated `Image`

ListInstancesRequest

ListInstancesResponse

Field	Type	Description
`instances`	repeated `Instance`

ListKernelsRequest

ListKernelsResponse

Field	Type	Description
`kernels`	repeated `Kernel`

ListNetworkAllocationsRequest

Field	Type	Description
`name`	`string`

ListNetworkAllocationsResponse

Field	Type	Description
`allocations`	repeated `NetworkAllocation`

ListNetworksRequest

ListNetworksResponse

Field	Type	Description
`networks`	repeated `Network`

ListSnapshotsRequest

Field	Type	Description
`instance`	`string`

ListSnapshotsResponse

Field	Type	Description
`snapshots`	repeated `Snapshot`

ListVolumesRequest

ListVolumesResponse

Field	Type	Description
`volumes`	repeated `Volume`

Mount

Mount attaches a volume, a host file or a tmpfs at target in the guest.

Field	Type	Description
`type`	`MountType`
`source`	`string`	The volume’s name for a volume. For a file, the host file’s absolute path: the daemon reads it when the instance starts and puts a copy on the guest’s config disk, so a change reaches the guest at its next start. A tmpfs has none.
`target`	`string`	The absolute path the mount appears at in the guest.
`read_only`	`bool`	A volume every instance attaching it mounts read-only can be shared.

Network

Network is a host-local bridge with NAT to the uplink.

Field	Type	Description
`id`	`string`
`name`	`string`
`subnet`	`string`
`gateway`	`string`
`bridge`	`string`
`mtu`	`int32`
`nameservers`	repeated `string`
`isolated`	`bool`	Stops instances on the network reaching each other; each can still reach the gateway and, through NAT, the outside.
`total_ips`	`int64`
`free_ips`	`int64`
`create_time`	`google.protobuf.Timestamp`
`update_time`	`google.protobuf.Timestamp`

NetworkAllocation

NetworkAllocation is an address assigned to an instance.

Field	Type	Description
`instance_id`	`string`
`instance_name`	`string`
`ip`	`string`
`mac`	`string`
`tap_device`	`string`

PauseInstanceRequest

Field	Type	Description
`name`	`string`

PortMapping

PortMapping publishes a guest port on the host, so the guest can be reached from outside it. It is applied each time the instance starts. Traffic to the host’s loopback addresses is not forwarded.

Field	Type	Description
`host_ip`	`string`	The host address to publish on. Empty means every address the host has.
`host_port`	`uint32`
`guest_port`	`uint32`
`protocol`	`Protocol`

PruneImagesRequest

PruneImagesResponse

Field	Type	Description
`images`	repeated `Image`	The images that were removed.
`reclaimed_bytes`	`int64`	The disk space their disks and cached layers gave back.

PullImageProgress

Field	Type	Description
`stage`	`PullStage`
`downloaded_bytes`	`int64`	Compressed layer bytes fetched and expected. Both are zero outside the downloading stage, and the total counts only what is actually fetched: a layer already held is not downloaded again.
`total_bytes`	`int64`
`image`	`Image`	Set on the final message only, when the image is ready to boot.

PullImageRequest

Field	Type	Description
`ref`	`string`

RenameInstanceRequest

Field	Type	Description
`name`	`string`
`new_name`	`string`	The name to give it, which no other instance may have.

ResourceCapacity

ResourceCapacity is how much of one resource instances may be given, and how much they hold. A start that would take allocated past allocatable is refused.

Field	Type	Description
`host`	`int64`	What the host has: its logical CPUs, or its memory.
`reserved`	`int64`	What is kept back from instances for the host itself.
`overcommit`	`double`	How far what remains is stretched: 4 lets four vCPUs share each CPU.
`allocatable`	`int64`	What instances may be given in total: (host - reserved) * overcommit.
`allocated`	`int64`	What instances hold.
`available`	`int64`	What is left for further instances: allocatable - allocated, or 0.

RestartPolicy

RestartPolicy is what the daemon does when an instance ends without being asked to: when its workload exits, its guest resets or its hypervisor dies. Restarts back off exponentially, from a second up to five minutes; an instance that stays up for ten minutes starts the count again.

Field	Type	Description
`mode`	`RestartMode`
`max_retries`	`int32`	For on-failure, how many restarts in a row are made before the instance is left Failed. 0 means no limit.

RestoreSnapshotRequest

Field	Type	Description
`instance`	`string`
`name`	`string`

ResumeInstanceRequest

Field	Type	Description
`name`	`string`

Snapshot

Snapshot is a point-in-time copy of an instance: the guest’s memory and device state, plus the overlay disk as it was at that moment.

Field	Type	Description
`name`	`string`
`instance_name`	`string`
`hypervisor_type`	`HypervisorType`	The hypervisor that took it, and the version of it. Restoring needs the same version, since snapshot formats are specific to it.
`hypervisor_version`	`string`
`memory_bytes`	`int64`	The guest memory the snapshot was taken with.
`size_bytes`	`int64`	What the snapshot occupies on disk, which on a copy-on-write filesystem may be far less than the guest’s memory and disk together.
`create_time`	`google.protobuf.Timestamp`

StartInstanceRequest

Field	Type	Description
`name`	`string`

StopInstanceRequest

Field	Type	Description
`name`	`string`

UpdateInstanceRequest

UpdateInstanceRequest changes the fields that are set: an optional field that is present, an enum that is not unspecified, a message that is present, and a repeated or map field that is not empty, which replaces the existing value whole.

Field	Type	Description
`name`	`string`
`image_ref`	optional `string`	One of `_image_ref`.
`hypervisor_type`	`HypervisorType`
`hypervisor_version`	optional `string`	One of `_hypervisor_version`.
`kernel_name`	optional `string`	One of `_kernel_name`.
`kernel_args`	optional `string`	One of `_kernel_args`.
`vcpus`	optional `int32`	One of `_vcpus`.
`memory_bytes`	optional `int64`	One of `_memory_bytes`.
`disk_bytes`	optional `int64`	One of `_disk_bytes`.
`network_name`	optional `string`	One of `_network_name`.
`static_ip`	optional `string`	One of `_static_ip`.
`hostname`	optional `string`	One of `_hostname`.
`restart_policy`	`RestartPolicy`
`health_check`	`HealthCheck`
`init_mode`	`InitMode`
`remove_on_exit`	optional `bool`	One of `_remove_on_exit`.
`mounts`	repeated `Mount`
`env`	repeated `UpdateInstanceRequest.EnvEntry`
`cmd`	repeated `string`
`labels`	repeated `UpdateInstanceRequest.LabelsEntry`
`ports`	repeated `PortMapping`

UpdateInstanceRequest.EnvEntry

Field	Type	Description
`key`	`string`
`value`	`string`

UpdateInstanceRequest.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

Volume

Volume is a persistent block device that outlives the instances using it.

Field	Type	Description
`id`	`string`
`name`	`string`
`size_bytes`	`int64`
`create_time`	`google.protobuf.Timestamp`
`update_time`	`google.protobuf.Timestamp`

Enums

Architecture

Architecture is the CPU architecture a kernel is built for.

Value	Number	Description
`ARCHITECTURE_UNSPECIFIED`	0
`ARCHITECTURE_X86_64`	1
`ARCHITECTURE_AARCH64`	2

EventAction

EventAction is what happened to the resource.

Value	Number	Description
`EVENT_ACTION_UNSPECIFIED`	0
`EVENT_ACTION_CREATED`	1	Any kind of resource.
`EVENT_ACTION_UPDATED`	2
`EVENT_ACTION_DELETED`	3
`EVENT_ACTION_STARTED`	4	An instance.
`EVENT_ACTION_STOPPED`	5
`EVENT_ACTION_PAUSED`	6
`EVENT_ACTION_RESUMED`	7
`EVENT_ACTION_EXITED`	8	The guest ended cleanly, of its own accord.
`EVENT_ACTION_DIED`	9	The guest ended in failure.
`EVENT_ACTION_RESTARTING`	10	The restart policy will start the instance again.
`EVENT_ACTION_RENAMED`	11
`EVENT_ACTION_HEALTHY`	12	The health check reached a verdict.
`EVENT_ACTION_UNHEALTHY`	13
`EVENT_ACTION_SNAPSHOT_CREATED`	14
`EVENT_ACTION_SNAPSHOT_RESTORED`	15
`EVENT_ACTION_SNAPSHOT_DELETED`	16
`EVENT_ACTION_PULLED`	17	An image.
`EVENT_ACTION_COLLECTED`	18	Garbage collection removed the image.

EventKind

EventKind is the kind of resource an event is about.

Value	Number	Description
`EVENT_KIND_UNSPECIFIED`	0
`EVENT_KIND_INSTANCE`	1
`EVENT_KIND_IMAGE`	2

HealthStatus

HealthStatus is what an instance’s health check has found.

Value	Number	Description
`HEALTH_STATUS_UNSPECIFIED`	0
`HEALTH_STATUS_STARTING`	1	No verdict yet: the workload is in its start period, or has not been probed.
`HEALTH_STATUS_HEALTHY`	2	The last probe passed.
`HEALTH_STATUS_UNHEALTHY`	3	The check’s retries have failed in a row.

HypervisorType

HypervisorType is the virtual machine monitor an instance runs on.

Value	Number	Description
`HYPERVISOR_TYPE_UNSPECIFIED`	0
`HYPERVISOR_TYPE_CLOUD_HYPERVISOR`	1	Cloud Hypervisor, the default.
`HYPERVISOR_TYPE_FIRECRACKER`	2

InitMode

InitMode is how the guest starts an instance’s command.

Value	Number	Description
`INIT_MODE_UNSPECIFIED`	0
`INIT_MODE_AUTO`	1	Systemd if the command resolves to the systemd binary in the image, exec otherwise. The default.
`INIT_MODE_EXEC`	2	The command runs as PID 1 of its own PID namespace, as a container runs it.
`INIT_MODE_SYSTEMD`	3	The command, systemd, is the machine’s PID 1.

InstanceState

InstanceState is where an instance is in its lifecycle.

Value	Number	Description
`INSTANCE_STATE_UNSPECIFIED`	0
`INSTANCE_STATE_STOPPED`	1	Defined but not running. A new instance starts here.
`INSTANCE_STATE_STARTING`	2	A start is in progress.
`INSTANCE_STATE_RUNNING`	3	The guest is running.
`INSTANCE_STATE_PAUSED`	4	The guest’s vCPUs are halted, and it is kept resident.
`INSTANCE_STATE_STOPPING`	5	A stop is in progress.
`INSTANCE_STATE_RESTARTING`	6	The instance ended without being asked to, and its restart policy will start it again at next_restart_time. It holds nothing meanwhile.
`INSTANCE_STATE_FAILED`	7	The last operation failed; state_error says why.

LogSource

LogSource is one of the logs an instance produces.

Value	Number	Description
`LOG_SOURCE_UNSPECIFIED`	0	Defaults to the guest’s console.
`LOG_SOURCE_GUEST`	1	The guest’s serial console: the kernel’s boot messages, dicer-init’s, and whatever the workload writes to the console.
`LOG_SOURCE_HYPERVISOR`	2	The hypervisor’s own log, which explains a guest that never booted. It is discarded when the instance stops.

MountType

MountType is what a Mount attaches.

Value	Number	Description
`MOUNT_TYPE_UNSPECIFIED`	0
`MOUNT_TYPE_VOLUME`	1	A named volume: persistent storage, as a disk of its own.
`MOUNT_TYPE_FILE`	2	A copy of a host file, read at each start.
`MOUNT_TYPE_TMPFS`	3	An empty in-memory filesystem, lost when the guest stops.

Protocol

Protocol is the transport a port mapping forwards.

Value	Number	Description
`PROTOCOL_UNSPECIFIED`	0	Means TCP.
`PROTOCOL_TCP`	1
`PROTOCOL_UDP`	2

PullStage

PullStage is the part of a pull that is currently working.

Value	Number	Description
`PULL_STAGE_UNSPECIFIED`	0
`PULL_STAGE_RESOLVING`	1	Asking the registry what the reference points at.
`PULL_STAGE_DOWNLOADING`	2	Fetching the layers, the only stage with a byte count.
`PULL_STAGE_UNPACKING`	3	Writing those layers out as a root filesystem.
`PULL_STAGE_CONVERTING`	4	Packing that filesystem into the disk a guest boots from.

RestartMode

RestartMode is when an instance that ended without being asked to is started again.

Value	Number	Description
`RESTART_MODE_UNSPECIFIED`	0
`RESTART_MODE_NO`	1	Leave the instance as it ended. The default.
`RESTART_MODE_ON_FAILURE`	2	Restart it unless it ended cleanly, by its workload exiting 0 or its guest powering off.
`RESTART_MODE_UNLESS_STOPPED`	3	Restart it however it ended, and start it when the daemon starts, unless a user stopped it.
`RESTART_MODE_ALWAYS`	4	Restart it however it ended, and start it when the daemon starts, even if a user stopped it.

Daemon configuration