NodeRegistrationService

本页列出 kibotos.operator.v1 中 NodeRegistrationService 的方法及每个方法用到的消息与枚举，由 operator.proto 及其注释生成，注释保持英文。多个服务共用的消息与枚举见 kibotos.operator.v1 类型。

NodeRegistrationService is the Operator-only view and desired-state surface for nodes admitted to this control plane. It is never mounted on the Native Workspace endpoint and does not expose transport or provider locators.

ListNodeRegistrations复制标题链接

GetNodeRegistration复制标题链接

DrainNode复制标题链接

CancelNodeDrain复制标题链接

IsolateNode复制标题链接

IsolateNode records that the operator has made this node unable to write to any of its storage pools: its host is powered off, or it is cut off from its pools. ctrl cannot verify the claim, so this is an assertion by the operator and the operator carries its consequence: a node that is in fact still writing corrupts the block files it has open. It is refused while the node still has a live control session.

In one transaction ctrl then releases every use right the node held, in every pool, shared or not, and every Allocation charged to it; every Workspace whose execution was on the node fails as unavailable and retryable, and commands still addressed to the node fail. A Workspace whose objects are in a pool another node reaches can then start on that node. Its data is crash-consistent: writes still in the old host's page cache may be lost. A Workspace whose objects are in a pool only this node reaches can start again once this node, or another host reaching that pool, is back.

RetireNode复制标题链接

RetireNode ends a node for good: a host that is gone or will not serve again. It takes a node that is DRAINED or whose current incarnation is isolated, and refuses any other as failed_precondition. A replay of the same command answers the same result.

In one transaction the node stops being a member of every pool and its pending enrollment grants are revoked. Its registration stays as a tombstone reading RETIRED; it can never register again, and enrolling, draining or isolating the same node_id is refused. A new host takes a new node_id. A pool the node alone reached is left with no member until another host declares it, and its objects wait for that host.

ListStoragePools复制标题链接

GetStoragePool复制标题链接

GetStoragePool reads one storage pool, with the same content ListStoragePools gives for it. A pool no node has ever declared is not_found.

SetStoragePoolCapacity复制标题链接

SetStoragePoolCapacity replaces the capacity placement admits new Volumes and retained layers against in one pool. It takes effect for the next placement on every node that reaches the pool, without a node restart; lowering it below what is already reserved stops new objects there and evicts nothing. It requires the pool version the caller read, and a replay of the same command returns the current pool without writing again. A pool no node has ever declared is not_found.

DeclareStoragePoolLost复制标题链接

DeclareStoragePoolLost records that a pool's storage is gone and will not come back. ctrl cannot verify the claim, so the operator carries its consequence. It takes a pool every member of which has its current incarnation isolated, or that has no member, and refuses any other as failed_precondition naming the members still in the way. A replay of the same command answers the same result.

In one transaction the pool's Volumes become VOLUME_STATE_LOST, its reservation is released and the removals waiting on it are dropped. A Workspace bound to a lost Volume fails to start until it is bound to another. A Workspace whose writable layer was in the pool starts with a new layer and reports RESET with RETENTION_RESET_REASON_LAYER_UNAVAILABLE. The pool id never comes back into use: a node still declaring it reports it unavailable, even with the original disk.

ListWorkspacePlacements复制标题链接

ListWorkspacePlacements pages the Workspaces whose current Instance holds an unreleased Allocation, narrowed to one node, one Workspace or one Instance: where each executes now, and with which Instance. A Workspace that is stopped, deleted or not placed yet has no row. A node or Workspace that does not exist is not_found; an Instance that is not current anywhere yields an empty page, because it cannot be told apart from one that never existed. It reads ctrl's records and never calls a node.

WorkspacePlacement复制标题链接

WorkspacePlacement is where one Workspace executes now.

GetOvercommitDefaults复制标题链接

GetOvercommitDefaults returns the cluster-wide overcommit ratios. A node's schedulable CPU and memory are the host resources it reports times the ratio in effect for it: its own override, or else this default.

SetOvercommitDefaults复制标题链接

SetOvercommitDefaults replaces both cluster-wide ratios. Nodes take the new schedulable resources without a restart; lowering them below what is already reserved stops new placement there and evicts nothing.

SetNodeOvercommit复制标题链接

SetNodeOvercommit replaces one node's overrides. A ratio left out clears that override, so the node follows the cluster-wide default again.

MoveVolume复制标题链接

MoveVolume moves a Volume to another storage pool. Its ID, content, capacity and binding stay the same. A node that reaches both pools copies the blocks the Volume's filesystem uses, and ctrl then records the Volume in the target pool; the copy left in the source pool is removed after.

The move is refused, and the Volume stays where it is, unless the Volume is AVAILABLE, the Workspace it is bound to, if any, has no execution (STOPPED, or FAILED with its execution released, as a start finds it), some node reaches both pools, and after the move some node still reaches the Workspace's Volume and writable layer together: failed_precondition. A target pool without room for the Volume's capacity is resource_exhausted; the Volume reserves its capacity in both pools until the move settles. A Volume or Workspace with a command in progress, and a target pool still keeping an earlier copy of the Volume for removal, answer unavailable until that is over. A Volume already in the target pool is answered at once.

The call waits for the move to settle, at most one minute and never past the request deadline. A move still copying then answers unavailable with the StoragePoolObject as it stands in the error details; the same command_id waits again, and once the move settled answers its outcome. A move that fails leaves the Volume in its pool, with the failure in the error. While the Volume moves, the Workspace it is bound to does not start, and the Volume is not resized, bound, released, deleted or exported: each answers unavailable until the move settles.

MoveWritableLayer复制标题链接

MoveWritableLayer moves a Workspace's writable layer to another storage pool, under the same rules as MoveVolume: the layer must have been placed by an earlier start, the Workspace must have no execution, and its layer and Volume must still share a node after the move. The layer's content moves unchanged, so the Workspace continues from it on its next start as it would have in the source pool.

ListStoragePoolObjects复制标题链接

ListStoragePoolObjects pages the Volumes and writable layers that live in one pool and are not deleted, those StoragePool counts in volume_count and retained_layer_count. An object moving out is listed with the pool it moves to; an object moving in is listed in its source pool until the move settles. A pool no node has ever declared is not_found.

GetStoragePoolObject复制标题链接

GetStoragePoolObject reads one Volume, or one Workspace's writable layer, where it lives, as ListStoragePoolObjects lists it. A Volume that does not exist, is deleted or has not been placed yet, and a Workspace that does not exist, is deleted or whose writable layer was never placed, are not_found.

CreateWorkspaceOnNode复制标题链接

CreateWorkspaceOnNode is CreateWorkspace with its placement fixed to one node. The node is the only candidate: it must meet every constraint an ordinary placement checks, drain included, and when it does not the creation fails as an ordinary placement that found no node fails. No other node is chosen instead. Only this placement is fixed: the Workspace keeps no record of the node, and its later starts are placed as usual.

The command is the Workspace command the embedded request names: its command_id, replay, GetWorkspaceCommand and errors follow the Workspace API, and a retry or a restarted ctrl still places it on this node only. The node is part of the command's input, so the same command_id with another node, or sent to CreateWorkspace, is already_exists. A node that was never registered is not_found, and no command is admitted.

StartWorkspaceOnNode复制标题链接

StartWorkspaceOnNode is StartWorkspace with its placement fixed to one node, under the rules of CreateWorkspaceOnNode. A Workspace whose Volume or writable layer lives in a pool the node does not reach fails to start as unavailable.

消息与枚举复制标题链接

NodeRegistrationService 的多个方法用到以下消息与枚举。

NodeResources复制标题链接

NodeSessionSummary复制标题链接

NodeClockObservation复制标题链接

NodeClockObservation is how far the node's wall clock is from ctrl's, as ctrl measured it around one call on the control session.

NodeObservationSummary复制标题链接

observation_version is the version of this observation snapshot. It is not the registration record version; NodeRegistration carries that separately under its own name so the two cannot be confused at a call site.

NodeRegistration复制标题链接

registration_version is this record's optimistic concurrency version. The nested observation carries its own version under a different name.

NodeMemoryTight复制标题链接

OvercommitDefaults复制标题链接

Overcommit ratios are in thousandths: 1000 is 1x and 4500 is 4.5x. CPU and memory ratios both lie in [1, 16000].

NodeOvercommit复制标题链接

NodeOvercommit is the ratio in effect for each resource on one node and where it comes from.

OvercommitRatio复制标题链接

NodeHostUsage复制标题链接

NodeHostUsage is the node's latest usage sample as ctrl received it. Each measurement is absent when the node could not read it. Ratios are in basis points: 10000 is 100 percent.

StoragePool复制标题链接

StoragePool is one storage location declared by the nodes that reach it. Volumes and retained layers live in a pool, and a Workspace runs only on a node that reaches every pool its objects live in.

StoragePoolAttachment复制标题链接

StoragePoolAttachment is one (node, pool) pair. It is read from both ends: a pool lists the nodes that reach it, and a node lists the pools it declares, so both identities are present.

StoragePoolObject复制标题链接

StoragePoolObject is a Volume or a Workspace's writable layer, and the pool it lives in.

NodeAdmission复制标题链接

NodeRegistrationStatus复制标题链接

NodeClockSynchronization复制标题链接

NodeClockSynchronization is what the node host's kernel reports about its clock. UNSPECIFIED means the node could not read it.

OvercommitSource复制标题链接

StoragePoolObjectKind复制标题链接