kibotos.ctrl.v1 types

command_id is the stop command; GetWorkspaceCommand returns its result.

durability is the result of the stop once it completed, and UNSPECIFIED while it is still running.

transferred_bytes and total_bytes are raw counters, zero when unknown. A Workspace can wait on a first cold delivery, so the caller needs to distinguish progress from a stall. They carry no artifact identity.

Guest RAM. It must be a whole number of MiB and at least 128 MiB, so the requested value is exactly what the execution receives. The upper bound is available capacity and is judged when an execution is placed.

Capacity of the Workspace's writable filesystem layer, which is also the disk capacity a placement reserves for it. There is one number, not a separate scheduling declaration: what is reserved is what the layer gets. In a creation request, zero delegates the choice to the storage profile of whatever runs the Workspace. A non-zero request must be a whole number of MiB. A returned Workspace reports the capacity it asked for; the capacity its layer actually has is the BEST_EFFORT retention tier's capacity_bytes, which is absent until the layer exists. ResizeWorkspaceWritableLayer is the only way this value changes after creation, and it only moves upward.

Required for BOUND and must be empty for NEW and NONE requests. Stored bindings carry the exact Volume ID for BOUND.

Absolute guest path the Volume is mounted at. Empty selects the default /data; it must be empty for NONE. Stored bindings always carry the exact path.

delete_with_workspace is a property of the binding, not of the Volume: DeleteWorkspace physically deletes the Volume when it is on and only releases the binding when it is off. A NEW request defaults it on, a BOUND request defaults it off, and NONE must leave it unset. Releasing the binding through UpdateWorkspaceVolumeBinding always keeps the Volume, whatever this says. A Volume a NEW request asked for that no launch has finished creating holds nothing to keep: DeleteWorkspace deletes it whatever this says. DeleteWorkspace touches only a Volume still bound to the Workspace it deletes. A failed RestoreWorkspace that holds no execution releases the imported Volume whatever this says. Stored bindings always carry an explicit value.

revision is assigned by the server: it starts at 1 when the Workspace is created and increases by one each time the content changes. It is independent of Workspace.generation. The server ignores the value in a request, and two requests that differ only here are the same command.

allow and deny narrow PUBLIC_INTERNET by destination address. Each entry is one address or one CIDR in canonical text: no host bits set in a CIDR, no leading zeros, IPv6 in compressed lowercase form, no zone. An entry acts only on its own address family, so 0.0.0.0/0 leaves IPv6 open. A destination in allow is admitted even when deny also covers it; a destination only in deny is refused, whether it would leave directly or through an Egress; anything else follows the mode. For traffic that leaves directly the hard deny of private, local and platform ranges always wins, so entries in those ranges are valid and act only on traffic forwarded through an Egress. DNS queries to the link DNS address are never narrowed. DENY_ALL accepts no entries. The server keeps both lists in the order given, and a change to either one is a content change.

egresses send part of PUBLIC_INTERNET through caller-owned Egresses. A new TCP connection the deny list does not refuse and whose destination an entry's destinations cover leaves through that entry's Egress, without the hard deny check; an ICMP echo request to such a destination is refused at once with administratively prohibited; everything else leaves directly. DNS queries to the link DNS address are not forwarded by destination; only resolvers sends them through an Egress. When forwarding fails the guest connection is reset and never falls back to leaving directly. At most one entry is accepted, and DENY_ALL accepts none. Adding, removing or replacing an entry, or changing its destinations, is a content change. A connection whose path the change moves keeps its old path for the drain_seconds of that UpdateWorkspaceNetworkPolicy call.

resolvers lists the upstreams the link DNS address forwards the guest's queries to, in place of the deployment resolvers. At most one entry is accepted, and DENY_ALL accepts none. When an upstream is unavailable the query is answered with SERVFAIL and never falls back to the deployment resolvers. Adding, removing or replacing an entry, or changing its path, is a content change.

resolver_id must name a Resolver that exists; a missing or deleted one is not_found.

path is required.

egress_id must name an Egress that exists; a missing or deleted one is not_found.

destinations has 1 to 256 entries, each in the text of allow and deny and acting only on its own address family. Entries may name private and hard deny ranges. They are matched as a set, so order and duplicates do not change which connections are forwarded; the server keeps them in the order given, and reordering them is a content change but moves no connection.

egresses has one entry for each Egress the applied policy references, and is empty when it references none.

draining_revision is the earliest policy revision whose connections are still open on a path a later revision moved them off; they close when the drain_seconds of that change runs out. Zero when none are left.

resolvers has one entry for each entry of the applied policy's resolvers, identified by resolver_id and path, and is empty when it references none.

applied_revision is the Egress revision new connections use. A value below Egress.revision means the update has not taken effect here yet; until it does, new connections keep using applied_revision.

draining_revision is the earliest earlier revision of this Egress that still carries open connections; they close when the drain_seconds of the update that replaced it runs out. Zero when none are left.

applied_revision is the Resolver revision new queries use. A value below Resolver.revision means the update has not taken effect here yet.

At most one Volume. The binding is set at creation and can be replaced through UpdateWorkspaceVolumeBinding while the Workspace holds no execution.

launch_ref is the opaque identity of one exact launch: a Launch revision is immutable, but which one this Workspace is bound to can advance. An explicit StartWorkspace rebinds it to the current Platform default of the PlatformKey it is already on; every other path into a running state keeps the stored value. Its representation and backing artifact locations remain private.

network_policy always carries mode and revision. It is the expectation; Workspace.network_policy_status is the observation.

resources_revision starts at one and increases every time the stored resources change. It is the CAS token UpdateWorkspaceMemory expects.

launch_binding_version starts at one and advances only when an explicit start rebinds launch_ref. Comparing it across a stop/start says whether this Workspace changed Platform, without resolving launch_ref.

binding_revision starts at one and increases every time the stored Volume binding changes. It is the CAS token UpdateWorkspaceVolumeBinding expects and moves independently of resources_revision.

network_policy may be omitted; an omitted or unspecified mode is DENY_ALL.

capacity_bytes is the capacity this tier's storage was confirmed to have. Only the BEST_EFFORT tier reports it, and only once its layer exists: a Workspace that has never started has a requested capacity and no confirmed one. It is the observation a caller compares against the request in spec.resources.ephemeral_disk_bytes.

Empty means the Workspace has no promised persistent path (NONE). A bound Volume yields exactly one value: its mount_path.

The number of times this Workspace has run. It starts at one when the first execution is available and increases after each successful start. It never exposes an implementation-private resource identity.

Exactly one PROMISED, BEST_EFFORT, and NONE entry is returned. The path shape is [mount_path] (empty and NOT_DECLARED without a Volume), /, and [/tmp, /run], respectively.

delivery is present while a Workspace waits for its Template artifacts to become locally usable. That wait is a transfer whose duration is proportional to artifact bytes, so "still arriving" must be distinguishable from "stuck" and from "failed". It is absent once the Workspace is available, and it carries no placement or infrastructure identity.

network_policy_status is present only while a verified policy is in force for the current execution. applied_revision below spec.network_policy.revision means a change was issued and not confirmed.

labels and annotations are caller-owned key-value data. ctrl never interprets either: it does not schedule, authorize, or bill on them. Both are visible to every caller that can read the resource, so neither may carry bearer credentials, keys, or values derived from them. Keys follow the Kubernetes qualified-name rules for both; label values follow the Kubernetes label-value rules, annotation values are any UTF-8 string without U+0000. Only labels can be selected on (label_selector); annotations are stored and returned verbatim and never indexed.

labels_revision starts at one and increases every time the stored labels change. It is the CAS token UpdateWorkspaceLabels expects and moves independently of every other revision.

annotations_revision is the same for annotations and UpdateWorkspaceAnnotations.

guest_observation is what the host running the current execution last reported about its guest. It is absent when there is no current execution or the host has not reported one yet. It is an observation, not a state: an UNRESPONSIVE guest leaves state, admission and expiration unchanged, and the guest may recover. Force stop recovers a guest that does not.

last_stop is present while the Workspace is STOPPING or STOPPED and names the stop that took it there. Start and delete clear it. A Workspace stopped by a release that did not record it has none.

egress_observations reports faults of the Egresses themselves, one entry for each Egress the current execution forwards through that is failing. It is empty when none is. It is an observation, not a state: it never changes state, and reading it never asks the host. A destination the Egress reports unreachable or refused is the result of one connection and is not an Egress fault.

resolver_observations reports faults of the upstream leg of the policy's resolvers, one entry for each failing entry, identified by resolver_id and path. It is empty when none is. A fault of the Egress a query goes through is reported in egress_observations, not here. It is an observation, not a state: it never changes state, and reading it never asks the host. An NXDOMAIN or SERVFAIL the upstream answers is a DNS result and not an upstream fault.

failing_since is when this run of consecutive failures began, on the clock of the host that observed it.

observed_at is when ctrl recorded this report, on ctrl's own clock.

failing_since is when this run of consecutive failures began, on the clock of the host that observed it.

observed_at is when ctrl recorded this report, on ctrl's own clock.

observed_at is when ctrl recorded this report, on ctrl's own clock.

unresponsive_since is present only for UNRESPONSIVE: the first of the failed probes, on the clock of the host that probed.

error is the latest probe failure; empty for RESPONDING.

rebooted means the guest answered with a boot other than the one that started this execution.

memory_condition is the guest's latest judgment of its processes' memory. It is UNSPECIFIED, meaning unknown, whenever condition is not RESPONDING.

memory_saturated_since is present only for SATURATED: when it began, on the clock of the host that probed.

memory_kill_count is how many of the processes the guest killed since it booted because they stayed saturated. It is zero for a guest that predates this report, which never kills. Unlike memory_condition it stands while the guest does not respond.

latest_memory_kill describes the latest of those kills; absent while memory_kill_count is zero.

restart_count is how many times this execution's guest reset itself and came back within the same execution. A later execution starts from zero. While the guest is coming back there is no observation at all, so it reads again once the guest answers.

last_reset_at is present only when restart_count is not zero: when the guest last reset its machine, on the clock of the host that saw it.

killed_at is on the clock of the host that probed the guest.

command is the process's name as the guest kernel keeps it, without its arguments, and is at most a few dozen bytes.

full_stall_permille is the share of the window, in thousandths, during which every process was stalled waiting for memory, when the guest decided.

window is the span full_stall_permille covers.

saturated_for is how long saturation had lasted when the guest decided.

storage_pool names the storage this Volume lives in. Where a Volume lives decides where the Workspace bound to it can run, so a deployment that splits its storage exposes that choice here. An empty value in a creation request selects the deployment's default pool; a returned spec always names the resolved pool. It changes only when the deployment's operator moves the Volume to another pool, so a caller reads it from the Volume instead of keeping its own copy. Requires the volume.storage_pool capability.

In a creation request, zero delegates capacity selection to the configured storage profile. In a returned Volume it is never zero: it is the capacity the Volume actually has. ResizeVolume is the only way it changes, and it only ever grows. The historical result of the original CreateVolume keeps the value that creation returned.

bound_workspace_id names the non-deleted Workspace whose spec binds this Volume. Empty when the Volume is free. Whether that Workspace deletes the Volume with itself is a property of its binding, not of the Volume.

labels and annotations have the same meaning, rules, and limits as on Workspace. Both remain readable after the Volume is deleted.

labels_revision is the CAS token UpdateVolumeLabels expects.

annotations_revision is the CAS token UpdateVolumeAnnotations expects.

observation is what the current holder of this Volume last reported about it. It is diagnostic: state is changed only by commands, and no admission reads the observation. It is kept as it was while nothing holds the Volume, so observed_at says how current it is. GetVolume and ListVolumes return it; command responses do not. Absent until a holder first reports.

observed_at is when ctrl recorded this report, on ctrl's own clock.

reason and message say why a DAMAGED Volume is damaged. Both are empty for a HEALTHY one.

input_offset is the number of input bytes the process has accepted, on a SendInput that carried input_offset and failed.

command_settled says this answer is the recorded result of the command it names: sending the same command_id again replays it, whatever retryable says, so trying again takes a new command_id. A retryable failure without it has no recorded result, and the same command_id reaches the command.

Positive duration from native admission, including creation time.

Starts at one and remains present when the policy is cleared or consumed.