Skip to content

Node API

This page is for authors of clients of the node API, the API chalkd serves on every node; most readers want chalkctl, its client, instead. chalkd serves the API on TCP port 50000 over TLS, as a Connect service that also answers gRPC and gRPC-Web.

Beside NodeService, which every image serves, chalkd serves the API of each layer the image carries: KubernetesService on images with the Kubernetes layer, RouterService on images with the router layer. On an image without the layer their methods fail with UNIMPLEMENTED.

Each method names the modes it is available in and the least role it needs, which Roles and credentials explains, followed by its request and response messages. The messages that fields of other messages hold are under Messages, and the enumerations under Enums. proto3 fields have no defaults: a field a message leaves out reads as the zero value of its type, such as an empty string, false, 0 or an unset message. Of the fields whose type names a oneof, a message sets at most one.

The definition is api/chalkos/node/v1/node.proto, package chalkos.node.v1.

NodeService

NodeService is the API chalkd serves on each node. Each method's comment names the modes it is available in, maintenance mode, normal mode or both, and the least role a client certificate needs to call it: reader, operator or admin, where each role may call what the roles before it may. The API of each layer the image carries, such as chalkos.kubernetes.v1.KubernetesService, is served beside it.

chalkd also serves the API to the console on the machine's screen, through the socket /run/chalkd/console.sock, which root alone reaches, without TLS. The console holds no certificate; each method's comment says whether the console may call it, and chalkd refuses it PERMISSION_DENIED otherwise. The console's actions are refused while the image turns them off with chalkos.console.actions.enable.

Info

Info describes the node and the agent. Available in maintenance and normal mode to readers. The console may call it.

Request: InfoRequest. Response: InfoResponse.

InfoRequest

The request of Info.

No fields.

InfoResponse

The response of Info.

Field Type Description
mode Mode Mode chalkd serves the node in.
image_id string Image ID of the running image, such as "chalkos".
installer bool Whether the node runs the installer, which writes a node's image to another disk.
boot_disk string Device of the disk the node booted from; empty on the installer booted from a CD.
tpm bool Whether the kernel found a TPM, as /sys/class/tpm lists one.
secure_boot SecureBoot State of Secure Boot.
fingerprint string SHA-256 of the certificate chalkd serves, in lower-case hex.
hostname string Host name of the node, as the kernel holds it.
image string The name of the running image, as its os-release names it; empty on the installer.
platform string The platform the running image was built for, such as metal or kvm; empty on the installer, which installs images of every platform.
root_hash bytes The verity root hash of the store the node runs, as its kernel command line's usrhash= names it, which identifies the running image; empty when it could not be read.
revision string The git revision the running image was built from, as the node's record of the images it installed names it; empty when it does not know it.
tag string The git tag the running image was built from, as the node's record of the images it installed names it; empty when it does not know it.
layers list of string The layers the running image carries beside the base every image has, such as "kubernetes", in name order; empty on the installer and on an image of the base alone.
node_name string The node's name, as its node certificate names it; empty in maintenance mode and on the installer.

Field types: Mode, SecureBoot.

Disks

Disks lists the node's disks and their partitions. Available in maintenance and normal mode to readers. The console may call it.

Request: DisksRequest. Response: DisksResponse.

DisksRequest

The request of Disks.

No fields.

DisksResponse

The response of Disks.

Field Type Description
disks list of Disk The node's disks, by kernel name.

Field types: Disk.

Contract

Contract returns the config contract of the image the node runs: its name and the platform it was built for, its layers, the schemas of the config kinds it accepts and its layers' facts, such as the Kubernetes image.json, which chalkctl checks config against before it delivers it. The installer refuses it: config is for the image it installs, whose contract comes with that image. Available in maintenance and normal mode to readers.

Request: ContractRequest. Response: ContractResponse.

ContractRequest

The request of Contract.

No fields.

ContractResponse

The response of Contract: the config contract of the image the node runs.

Field Type Description
schemas map of bytes The image's schemas by file name, as /etc/chalkos/schemas holds them.
image string The image's name, as its os-release names it.
platform string The platform the image was built for, as its os-release names it.
layer_facts list of google.protobuf.Any The facts of the image's layers, such as chalkos.kubernetes.v1.ImageFacts, which config is translated with; empty for an image whose layers have none.
layers list of string The layers the image carries beside the base every image has, such as "kubernetes", in name order.

Install

Install turns a node in maintenance mode into an installed node and reboots it. The first message carries the header; when the node is the installer, the image's store data, hash tree, UKI and boot loader follow as chunks, unless the header's source names an image in a registry, which the installer pulls. The installer has the image's own checker check the config once the image's store is on the target disk, before it writes STATE or the boot loader; a refusal fails the precondition and leaves a target that boots nothing. An install the installer did not finish continues when run again, from either. Available in maintenance mode to admins.

Request: a stream of InstallRequest. Response: InstallResponse.

InstallRequest

A message of the Install stream: the header first, then the image's chunks.

Field Type Description
header InstallHeader, oneof message The install's header, in the stream's first message.
chunk ImageChunk, oneof message The next bytes of the image's parts, in every message after the first.

Field types: InstallHeader, ImageChunk.

InstallResponse

The response of Install, which the node sends before it reboots.

No fields.

ApplyConfig

ApplyConfig replaces the config of an installed node, or delivers it payloads of its layers, such as a Kubernetes share, a node certificate or OS CAs. Destructive storage changes are refused; additive ones are applied live. With try, the config is on trial: the node rolls it back by itself, as RollbackConfig does, unless ConfirmConfig confirms it in time. While a config is on trial, the node refuses every ApplyConfig, an Upgrade and a RollbackImage with FAILED_PRECONDITION. A trial whose node runs the config from before it again, as after a rollback at the deadline that failed after it wrote the config, is finished first, by a delivery of that config, and the change goes ahead; while an Upgrade, a RollbackImage or the rollback at a trial's deadline holds the lock that delivery needs, the change is refused with ABORTED. A trial whose node runs neither config ends, and the change goes ahead. A trial record the node cannot read refuses the change with INTERNAL until RollbackConfig removes it. Config for the running image goes to the image staged in the inactive slot too, or replaces the pending config, as ApplyConfigRequest.config describes. Available in normal mode to admins.

Request: ApplyConfigRequest. Response: ApplyConfigResponse.

ApplyConfigRequest

The request of ApplyConfig: a config, or layer payloads, a node certificate or OS CAs to deliver.

Field Type Description
fallback_secret string Recovery key or password enrolled on the encrypted volumes the config adds; required when it adds one and the node's fallback is not none.
node_certificate bytes A new node certificate for the node, followed by the certificate of the node CA that issued it (PEM), which chalkd serves from then on; empty keeps the node's.
node_key bytes PEM key of node_certificate; empty keeps the node's.
trust bytes The OS CAs the node trusts from now on (PEM), as InstallHeader.ca_certificate holds them; empty keeps the node's. They must verify the node's certificate, the caller's and a control plane's node CA. Not together with a node certificate.
config string The node's config, as InstallHeader.config holds it, checked against the running image's schemas. It replaces the node's config as a whole. Empty keeps the node's config and storage, for a request that delivers only layer payloads, a node certificate or OS CAs.

Without staged, the config is for the running image and for the image staged in the inactive slot, staged or active, as BootStatus.staged names it, unless that image is the known-good one a rollback staged, which keeps the config it last ran. Both images check the config, the staged one with its own checker as for staged, before anything changes, and a refusal of either refuses the request. The running image applies the config, and then the staged image's config slot is written. When that write fails, the slot keeps its earlier config and the request fails naming it; the request sent again writes it. On a node without a staged image that holds a pending config, the config replaces the pending config, unchecked, once the running image applied it, so the next upgrade boots the config delivered last. With try, the staged image's slot or the pending config is written once ConfirmConfig confirms the trial. | | staged | bool | Whether the config is for the image in the inactive slot, staged or active, as BootStatus.staged names it: chalkd checks it against that image and keeps it in that image's config slot, changing nothing the running image runs but the machine's storage. The config meets that image's change rules, compared with the running slot's config and the machine as for the running image, and the storage changes they accept are made at once, with fallback_secret. It takes the config and the fallback secret alone. Without an image staged, chalkd parses the config and keeps it as the node's pending config, unchecked, in place of any it held: the next upgrade checks it against its image and boots that image with it, unless the upgrade carries config of its own. A pending config takes no fallback secret; the upgrade that adds an encrypted volume carries it. | | layers | list of google.protobuf.Any | Payloads of the image's layers, such as a new chalkos.kubernetes.v1.Share replacing the node's, each kept by the layer whose type it is; the node refuses a payload no layer of its image takes. Empty keeps the layers' payloads. | | try | google.protobuf.Duration | How long the config is on trial: the node rolls it back by itself, as RollbackConfig does, unless ConfirmConfig confirms it within the duration, and a boot before that restores the config from before it. A trial takes config for the running image alone, without staged, layer payloads, a node certificate or OS CAs, and lasts at most 24 hours. The node refuses it with FAILED_PRECONDITION for a config that changes the node's storage, which a rollback cannot undo, for the config it runs already and on a node without config. Unset applies the config for good. | | ignore_units | list of string | With try, systemd units the health check that ConfirmConfig waits for leaves out, besides those the image ignores, such as demo.service: a unit that failed before the trial and is not the trial's concern. Each must be a unit name. The node keeps them with the trial. | | dry_run | bool | Whether the node only checks the request: it runs every check a delivery runs, the image's renderers and their checks among them, refuses the request as the delivery would, and otherwise answers with the delivery's plan and storage changes. With try, it checks the trial's conditions too. It changes nothing: no config, storage, layer payload, certificate or effect. With staged, the staged image checks the config; without an image staged, the response names the config it would hold pending, and nothing is kept. Without staged, the staged image checks the config too, and the response names its slot as the delivery would write it, or the pending config the delivery would replace. | | discard_pending | bool | Whether chalkd drops the node's pending config, which staged without an image staged keeps. It goes with staged alone, without config. The response names the config dropped. | | ignore_readiness | bool | For a config delivery to the running image, ignore failed runtime readiness probes: an ignored readiness failure is a warning, and its effect continues. Validation, prerequisite actions and the trial's confirmation still apply, and a later rollback runs its readiness probes as usual. |

ApplyConfigResponse

The response of ApplyConfig: what the delivery changed on the node.

Field Type Description
changes list of StorageChange Storage changes that were applied; for a dry run, those the delivery would apply.
restarted_units list of string Units the delivery restarted, as the image's effects say.
warnings list of string Why an effect ran with an unevaluated rule or a forced readiness failure, without the values the rule or probe read.
plan Plan For a dry run, what the delivery would do; unset otherwise.
pending PendingConfig The node's pending config: the config a request with staged keeps, or for a dry run would keep, on a node without an image staged; for discard_pending, the config dropped, unset when the node held none. For config to the running image on a node without an image staged that holds a pending config, the config that replaced it, or without since the one a dry run or a trial's confirmation would replace it with. Unset for other requests.
staged StagedSlot For config to the running image while an image other than the known-good one is staged in the inactive slot: that image's config slot, which its checker passed, as the delivery wrote it, as a dry run would write it, or as a trial's confirmation writes it. The storage changes its config makes on top of the running image's are among changes. Unset otherwise.

Field types: StorageChange, Plan, PendingConfig, StagedSlot.

GetConfig

GetConfig returns the config a slot keeps, the running image's, its previous one or the staged image's, as it was delivered, with secret values replaced by their hashes. Available in normal mode to admins.

Request: GetConfigRequest. Response: GetConfigResponse.

GetConfigRequest

The request of GetConfig.

Field Type Description
staged bool Whether the response holds the staged image's config instead of the running one's; without an image staged, the node's pending config.
previous bool Whether the response holds the running image's previous config, which RollbackConfig delivers again, instead of the one it runs. Not together with staged.

GetConfigResponse

The response of GetConfig: the config one slot keeps.

Field Type Description
documents string The slot's documents as delivered, one JSON document each separated by ---, as ApplyConfigRequest.config holds them. The values of Secrets and of the Secret objects a document embeds, such as a Kubernetes Secret, are replaced by the lower-case hex SHA-256 of the value. config_version is the hash of these documents.
version string The slot's version, as StatusResponse.config_version gives it.

ResetVolume

ResetVolume wipes one volume and creates it again as the delivered config defines it. It refuses VAR, a volume the config no longer has and a volume the config moves to another disk. Available in normal mode to admins.

Request: ResetVolumeRequest. Response: ResetVolumeResponse.

ResetVolumeRequest

The request of ResetVolume.

Field Type Description
volume string Name of the volume to reset.
fallback_secret string Recovery key or password enrolled on the volume when it is encrypted; required then, unless the node's fallback is none.
config string The node's config, as ApplyConfigRequest.config holds it, checked against the running image's schemas; the volume is created as it defines. Required.

ResetVolumeResponse

The response of ResetVolume, once the volume is created again.

No fields.

Status

Status reports the state of an installed node: its config versions, storage, failed units, certificates, trust, clock, boot and outputs; each layer's own state is its service's Status. Available in normal mode to readers. The console may call it.

Request: StatusRequest. Response: StatusResponse.

StatusRequest

The request of Status.

Field Type Description
check_health bool Whether to check the health of the boot the node runs and report it in BootStatus.health. The node runs the checks a boot's health check runs, the image's layers included, which may take a few seconds; a client that waits for a node it rebooted asks for it.

StatusResponse

The response of Status: the state of an installed node.

Field Type Description
disks list of DiskStatus The disks of the node's storage, by name, as the boot's storage setup left them.
volumes list of VolumeStatus The volumes of the node's storage, by name.
failed_units list of string Names of the systemd units that failed.
certificates list of CertificateStatus Every certificate the node holds or issues, with its expiry and what needs doing about it.
time TimeStatus How the node keeps its clock.
trust list of TrustStatus What the node trusts and issues with, by fingerprint.
boot BootStatus The image the node booted, and what upgrades installed beside it.
platform string The platform the running image was built for.
config_version string The version of the config stored in the running image's slot: SHA-256, in lower-case hex, of the documents GetConfigResponse.documents holds, in canonical JSON, ordered by apiVersion, kind and name. Empty on a node that runs no config.
staged_config_version string The version of the config kept for the image in the inactive slot, BootStatus.staged, as config_version gives the running one's; empty without a staged image or config for it.
outputs list of OutputStatus The image's outputs, by name.
previous_config_version string The version of the running image's previous config, which RollbackConfig delivers again, as config_version gives the running one's; empty while the node keeps none, as after an install or an upgrade.
trial ConfigTrial The config on trial, while one is; unset otherwise.
trial_error string Why the record of a config's trial cannot be read, while it cannot; trial is unset then. The node refuses every other change until RollbackConfig rolls the config back, which removes the record. Empty otherwise.
pending_config PendingConfig The config the node holds pending for its next upgrade, unchecked; unset without one.
config_activation ConfigActivation Progress of live activation for the running image. Older nodes omit this field.

Field types: DiskStatus, VolumeStatus, CertificateStatus, TimeStatus, TrustStatus, BootStatus, OutputStatus, ConfigTrial, PendingConfig, ConfigActivation.

Logs

Logs streams the journal of the current boot, or of one unit in it. Available in maintenance and normal mode to readers. The console may call it.

Request: LogsRequest. Response: a stream of LogsResponse.

LogsRequest

The request of Logs.

Field Type Description
unit string Unit whose journal to stream; empty streams the whole boot.
follow bool Whether the stream goes on with new entries until the client cancels it.
lines uint32 How many of the boot's last entries the stream starts with, as journalctl --lines takes it; zero starts with the boot's first entry.

LogsResponse

A message of the Logs stream.

Field Type Description
line string One journal entry, as journalctl's short-iso output prints it.

Reboot

Reboot reboots the node once the response is sent. Available in maintenance and normal mode to operators. The console may call it while the image allows the console's actions.

Request: RebootRequest. Response: RebootResponse.

RebootRequest

The request of Reboot.

No fields.

RebootResponse

The response of Reboot, which the node sends before it reboots.

No fields.

Upgrade

Upgrade installs a new image into the node's inactive slot and stages it there, then activates it as ActivateImage does, so it boots next, counting the image's boot tries until a boot is found healthy, and reboots the node when asked to. With the header's stage_only it stops once the image is staged. The first message carries the header; the store, its hash tree and the UKI follow as chunks, unless the header's source names an image in a registry, which the node pulls. Available in normal mode to operators. Delivering config or a fallback secret with the upgrade needs the admin role, as ApplyConfig does; without them the node gives the image its pending config, else carries the running image's config over. The node checks that the image is of its platform, and, once the store is written and before the image is staged, that the image's own checker accepts the config it keeps for the image. It does not check that the image is one to trust: without Secure Boot, an operator can run any image as root, with STATE and VAR unsealed, as their keys are sealed to PCR 7 alone. Secure Boot is what limits upgrades to images signed for db.

Request: a stream of UpgradeRequest. Response: UpgradeResponse.

UpgradeRequest

A message of the Upgrade stream: the header first, then the image's chunks.

Field Type Description
header UpgradeHeader, oneof message The upgrade's header, in the stream's first message.
chunk ImageChunk, oneof message The next bytes of the image's parts, in every message after the first.

Field types: UpgradeHeader, ImageChunk.

UpgradeResponse

The response of Upgrade.

Field Type Description
already_installed bool Whether the node runs the image already, so nothing changed.
entry string The file name of the UKI that boots the image next, with its tries; while the image is staged alone, the name its UKI has until ActivateImage.
rebooting bool Whether the node reboots into the image.
already_staged bool Whether the inactive slot held the image already, staged or active, as an earlier upgrade with stage_only or without a reboot left it; the image was not written again, and the config the upgrade carries, or the running image's, replaced the config kept for it.
pending PendingOutcome What the upgrade did with the config the node held pending as it began; unset when it held none.
active bool Whether the image boots next; false while it is staged alone, as stage_only leaves it.

Field types: PendingOutcome.

ActivateImage

ActivateImage makes the image staged in the node's inactive slot boot next: it gives the image's UKI its boot entry's name, one generation above the others, with the tries the UKI asks for, so boot counting falls back to the running image should its boots fail. It checks the UKI again as an upgrade checks a new one, as the firmware's db may have changed since, and runs no check of the config: the image's own checker passed its config slot before the image was staged. It answers already_active while the image boots next, and already_installed while the node runs it, so a request sent twice activates once. It is refused with FAILED_PRECONDITION when no image is staged, when the staged image has another root hash, and when STATE keeps no config slot of the image. An activation that fails leaves the UKI under its staged name, and the node keeps booting the running image. Available in normal mode to operators.

Request: ActivateImageRequest. Response: ActivateImageResponse.

ActivateImageRequest

The request of ActivateImage.

Field Type Description
root_hash bytes The verity root hash of the staged image's store, as BootStatus.staged gives it. The node refuses another. Required.

ActivateImageResponse

The response of ActivateImage.

Field Type Description
entry string The file name of the UKI that boots the image next, with its tries.
already_active bool Whether the image boots next already, from entry, so nothing changed.
already_installed bool Whether the node runs the image already, so nothing changed.

Diagnostics

Diagnostics lists the diagnostics the image declares: read-only commands of the image, such as ip route get, that RunDiagnostic runs. Available in maintenance and normal mode to readers. The console may call it.

Request: DiagnosticsRequest. Response: DiagnosticsResponse.

DiagnosticsRequest

The request of Diagnostics.

No fields.

DiagnosticsResponse

The response of Diagnostics.

Field Type Description
diagnostics list of Diagnostic The image's diagnostics, in name order.

Field types: Diagnostic.

RunDiagnostic

RunDiagnostic runs one of the image's diagnostics with the arguments given and streams what its command prints on standard output and standard error, then how it ended. It is refused with PERMISSION_DENIED unless the caller also has the diagnostic's own role, and with INVALID_ARGUMENT unless each argument is of its parameter's type and every parameter without a default or optional is given. chalkd runs the command as a transient systemd unit under a user of its own, on a read-only file system, with no capabilities but those the diagnostic names, for at most its timeout, and stops a command that prints more than 1 MiB. Four run at a time. The console runs the diagnostics of readers and operators. Available in maintenance and normal mode to readers. The console may call it.

Request: RunDiagnosticRequest. Response: a stream of RunDiagnosticResponse.

RunDiagnosticRequest

The request of RunDiagnostic.

Field Type Description
name string Name of the diagnostic, as Diagnostics lists it.
arguments map of string The value of each parameter given, by parameter name.

RunDiagnosticResponse

A message of the RunDiagnostic stream: output as the command prints it, then how it ended.

Field Type Description
stdout bytes, oneof output Bytes the command printed on standard output.
stderr bytes, oneof output Bytes the command printed on standard error.
exit DiagnosticExit, oneof output How the command ended; the stream's last message.

Field types: DiagnosticExit.

RollbackConfig

RollbackConfig delivers the running image's previous config again: the config the image ran before the delivery that replaced it, which the node keeps until the next delivery replaces it in turn. It goes through ApplyConfig's checks and steps: the image's change rules compared with the config the node runs and the machine, storage changes, outputs and effects, so a refusal names the rule. The config it replaces becomes the previous one, so a second rollback undoes the first. Only the config documents return: the OS CAs, the node certificate and the layers' payloads stay as they are. An upgrade's image starts without a previous config. During a trial it takes only the version from before the trial, ConfigTrial.previous_version, rolls the config on trial back at once and ends the trial. Once a rollback at the trial's deadline wrote that config and failed after, the node runs it already: RollbackConfig then delivers it again, which finishes the rollback, and ends the trial. A trial record the node cannot read names no version: RollbackConfig rolls back to the version asked for, or delivers it again when the node runs it already, and removes the record once that went through. Status reports no trial then, so once a rollback at the deadline wrote the config from before the trial, previous_config_version is the config on trial, and config_version is the version that finishes the rollback. Available in normal mode to admins. The console may call it while the image allows the console's actions.

Request: RollbackConfigRequest. Response: RollbackConfigResponse.

RollbackConfigRequest

The request of RollbackConfig.

Field Type Description
version string The version of the previous config to deliver again, as StatusResponse.previous_config_version gives it, or during a trial its ConfigTrial.previous_version. The node refuses another with FAILED_PRECONDITION, so a request sent twice rolls back once. Required.

RollbackConfigResponse

The response of RollbackConfig: what delivering the previous config changed, as ApplyConfigResponse says it.

Field Type Description
changes list of StorageChange Storage changes that were applied.
restarted_units list of string Units the delivery restarted, as the image's effects say.
warnings list of string Why the rule of an effect could not be evaluated, without the values it read; the delivery took the effect all the same.

Field types: StorageChange.

RollbackImage

RollbackImage makes the previous image boot next again: the image an upgrade replaced, whose store the inactive slot still holds, whose UKI is on the ESP and whose config slot STATE keeps, until the next upgrade writes the slot. The node writes no store: it checks the image's UKI as an upgrade checks a new one and renames it to the next generation with the tries it asks for, so boot counting falls back to the running image should its boots fail. While the running image's boot has not been found healthy, the name carries no tries instead: the image stays the node's known-good entry. The image boots with the config it last ran. The node reboots into it when asked to. Refused with FAILED_PRECONDITION when the node keeps no previous image, as while an upgrade's image is staged. Available in normal mode to operators. The console may call it while the image allows the console's actions.

Request: RollbackImageRequest. Response: RollbackImageResponse.

RollbackImageRequest

The request of RollbackImage.

Field Type Description
root_hash bytes The verity root hash of the previous image's store, as BootStatus.previous gives it. The node refuses another, and answers already_installed while it runs the image and already_staged while the image boots next, so a request sent twice rolls back once. Required.
reboot bool Whether the node reboots into the image once it boots next.

RollbackImageResponse

The response of RollbackImage.

Field Type Description
already_installed bool Whether the node runs the image already, so nothing changed.
entry string The file name of the UKI that boots the image next, with its tries while it has them.
rebooting bool Whether the node reboots into the image.
already_staged bool Whether the image boots next already, from entry, as a rollback without a reboot left it.

ConfirmConfig

ConfirmConfig ends the trial of a config that ApplyConfig delivered with try, and the node keeps the config from then on. The node must be healthy as the health check of a boot finds it: chalkd serves, no unit of the boot failed but those the image ignores, and the image's layers find their services healthy. It answers UNAVAILABLE while the node is not, and when the trial changed while the node's health was checked, as when the rollback at the deadline was tried meanwhile, so a client asks again. It answers FAILED_PRECONDITION when no trial of the version is open, unless the node runs that version, so a request sent twice confirms once. It answers FAILED_PRECONDITION too when the node no longer runs the version on trial, and after the deadline, unless the rollback at the deadline failed: while ConfigTrial.error is set, a confirmation ends the trial and the rollback's retries. Once such a rollback failed after it changed the node, it answers FAILED_PRECONDITION all the same: the node keeps trying to finish the rollback, and RollbackConfig to the trial's previous version finishes it at once. It answers INTERNAL when the node cannot read the trial's record, which RollbackConfig removes. A confirmation also writes what the trial's delivery held back until then: the config slot of the image staged in the inactive slot, or the pending config the config on trial replaces. Available in normal mode to admins.

Request: ConfirmConfigRequest. Response: ConfirmConfigResponse.

ConfirmConfigRequest

The request of ConfirmConfig.

Field Type Description
version string The version of the config on trial, as ConfigTrial.version gives it. Required.

ConfirmConfigResponse

The response of ConfirmConfig, once the trial ended.

Field Type Description
warnings list of string What the confirmation could not write of what the trial's delivery held back: the config slot of the staged image or the pending config, and why. The trial ended all the same, and the config delivered again writes it.

EnrollSecureBoot

EnrollSecureBoot writes Secure Boot keys into firmware in Setup Mode, as signed updates of its variables that the client made: it appends to db, then to KEK, and writes PK last, which ends Setup Mode. It refuses firmware that is not in Setup Mode, and updates that do not write EFI signature lists of X.509 certificates to KEK and PK, and of X.509 certificates and SHA-256 digests of images to db, signed by the KEK and PK they bring. Unless forced, it also refuses keys under which Secure Boot would refuse the boot loader and UKI the node booted, and keys under which db would allow neither by digest nor by a Microsoft CA that signs option ROMs the drivers the TPM event log lists in PCR 2, the option ROMs of graphics and network cards, or dbx would revoke them. A node that runs from its own disk recreates STATE on its next boot, as the TPM no longer unseals it once the keys change PCR 7. Once the keys are written, the node answers and reboots. Available in maintenance mode to admins.

Request: EnrollSecureBootRequest. Response: EnrollSecureBootResponse.

EnrollSecureBootRequest

The request of EnrollSecureBoot: the signed updates of db, KEK and PK, each an EFI_VARIABLE_AUTHENTICATION_2 descriptor followed by EFI signature lists, as SetVariable takes it without the attributes.

Field Type Description
db bytes The update of db, appended, signed by a certificate of the KEK update: certificates, and SHA-256 digests of images such as option ROMs.
kek bytes The update of KEK, appended, signed by the PK update's certificate.
pk bytes The update of PK, signed by its own certificate.
force bool Write the keys even if Secure Boot would refuse the boot loader or UKI the node booted, or a driver measured into PCR 2, under them.

EnrollSecureBootResponse

The response of EnrollSecureBoot, which the node sends before it reboots.

Field Type Description
db_before list of string The subjects of the X.509 certificates in db before the update, then its SHA-256 digests of images, each as sha256:<hex>.
db_after list of string The subjects of the X.509 certificates in db after the update, then its SHA-256 digests of images, each as sha256:<hex>.
kek_before list of string The subjects of the X.509 certificates in KEK before the update.
kek_after list of string The subjects of the X.509 certificates in KEK after the update.
drivers_unchecked string Why the node did not check that Secure Boot allows the drivers measured into PCR 2 under the new db, else empty: as a rule, the machine has no TPM, so no event log lists them, or its event log holds no SHA-256 digests.

SecureBootDrivers

SecureBootDrivers lists the UEFI drivers the firmware loaded from outside its own firmware, as a rule the option ROMs of graphics and network cards, as the TPM event log records their measurements into PCR 2: the SHA-256 Authenticode digest of each, which db holds to allow it under Secure Boot, and where the firmware found it. Available in maintenance mode to readers.

Request: SecureBootDriversRequest. Response: SecureBootDriversResponse.

SecureBootDriversRequest

The request of SecureBootDrivers.

No fields.

SecureBootDriversResponse

The response of SecureBootDrivers.

Field Type Description
drivers list of SecureBootDriver The drivers measured into PCR 2, in the order the firmware loaded them.
no_event_log string Why the node has no event log to read the drivers from, else empty: as a rule, the machine has no TPM, or its event log holds no SHA-256 digests.

Field types: SecureBootDriver.

Shutdown

Shutdown powers the node off once the response is sent, as Reboot reboots it. Available in maintenance and normal mode to operators. The console may call it while the image allows the console's actions.

Request: ShutdownRequest. Response: ShutdownResponse.

ShutdownRequest

The request of Shutdown.

No fields.

ShutdownResponse

The response of Shutdown, which the node sends before it powers off.

No fields.

Messages

These messages are held by fields of other messages.

BGPPeerStatus

One BGP session: a BGPPeer's address, or one of its interfaces.

Field Type Description
name string Name of the BGPPeer document.
neighbor string The interface the session runs on, for a peer of interface or interfaces, or the neighbour's address.
state string The session's BGP state: Idle, Connect, Active, OpenSent, OpenConfirm or Established.
uptime_seconds uint64 How long the session has been established, in seconds; 0 while it is not.
prefixes_received uint32 Routes the node accepted from the neighbour, of every family.
prefixes_sent uint32 Routes the node sends the neighbour, of every family.
bfd string The state of the session's BFD: up, down, admin-down or unknown; empty for a peer without bfd.
vrf string The VRF the session runs in: the name of its VRF document, or default.

BGPStatus

BGPStatus is the state of the configured speaker, independent of other node services.

Field Type Description
peers list of BGPPeerStatus Sessions ordered by VRF, BGPPeer name and neighbour. Empty when there are none.
error string Why the sessions could not be read, or empty when FRR answered.

Field types: BGPPeerStatus.

BootHealth

The health of the boot a node runs.

Field Type Description
healthy bool Whether the node passes the checks of a boot's health check: chalkd serves, and the first of the image's layers that runs decides or else the config was applied and no unit of the boot failed, besides those the image ignores.
error string Why the node is not healthy; empty when it is.
settled bool Whether the boot has settled: systemd finished starting it, the system running or degraded, and the image's health timeout, the time a counted boot has to become healthy, passed since. Until then the image's layers may still be starting; a boot that is not healthy once it settled is likely to stay so, and a client stops waiting for it once it stays unhealthy for a while, as a single check of a layer may fail on a healthy node.

BootImage

An image a UKI on the ESP boots.

Field Type Description
root_hash bytes The verity root hash of the image's store, from the usrhash= of the UKI or, for the running image, of the kernel command line; it identifies the image.
generation uint64 The generation of the UKI's boot entry, from its file name, <image ID>_<generation>.efi; systemd-boot boots the highest first. Zero when the name gives none or the entry is unknown.
revision string The git revision the image was built from, as the node's record of the images it installed names it; empty when it does not know it.
tag string The git tag the image was built from, as the node's record of the images it installed names it; empty when it does not know it.

BootStatus

The images on the node's ESP and how the running one booted.

Field Type Description
running BootImage The image the node runs.
entry string File name of the UKI the node booted, in the ESP's /EFI/Linux, with its tries counter while it has one.
blessed bool Whether the boot was found healthy and marked good, or not counted by the boot loader at all; false while the boot loader counts the boot's tries.
staged BootImage The image in the inactive slot that an upgrade staged, or that an upgrade or a rollback made boot next, as staged_state tells; unset without one.
failed BootImage The image whose boots used up their tries without being found healthy, from which the node fell back; unset without one. The failed UKI stays until the next upgrade.
journal list of string The last lines chalkd and the health check logged during the failed image's last boot, as the check recorded them on VAR; empty without that record.
error string Why the boot could not be read; empty when it was. The running image's root hash is set when the kernel command line could be read.
previous BootImage The image RollbackImage boots: the one an upgrade replaced, whose UKI is on the ESP and whose config slot STATE keeps; unset without one, as after an install, while another image is staged, or after a fallback.
rollback BootImage The image the last RollbackImage rolled back to, while the node runs it or boots it next; unset otherwise, and once an upgrade replaced it. A client that rolls back several nodes to one image knows by it which of them a rollback got there already.
staged_state SlotState Whether the image staged boots next; unspecified without one.
boot_id string The ID of the boot the node runs, as the kernel's random boot_id gives it, another for each boot: a client that rebooted the node tells the new boot from the one before by it, also when both run one image. Empty when it could not be read.
health BootHealth The health of the boot the node runs, as the health check of a boot finds the node now; unset unless the request asked for it. blessed tells of the boot entry, which stays blessed across boots and is not counted again; this tells of the boot itself, also of an uncounted one.
staged_known_good bool Whether the image staged is the node's known-good image: active and uncounted, as a rollback from a boot that was not found healthy stages it, while the boot the node runs is counted. Until that boot is found healthy the node falls back to that image, which keeps the config it last ran: a delivery leaves its config slot as it is, and config apply --staged refuses other config for it. False without an image staged.

Field types: BootImage, SlotState, BootHealth.

CertificateStatus

A certificate the node holds or issues with.

Field Type Description
name string What the certificate is: "node" and "OS CA" on every node; a layer adds its own, such as "node CA" on a node that issues node certificates or "kubelet client".
not_after google.protobuf.Timestamp When the certificate expires; unset when the expiry is unknown.
problem string Why a renewal fails, such as "renewal failing: <reason>; expires <date>", or a warning, such as "less than a third of its lifetime remains" or "the node certificate expires on <date>; this image cannot renew it on its own; run chalkctl node renew <node>"; empty when there is nothing to do. A command it advises names the node, or says <node> when the node cannot tell its name.
fingerprint string The SHA-256 fingerprint of the certificate, in lower-case hex.
issuer string The SHA-256 fingerprint of the certificate that issued it, in lower-case hex; empty when the node does not hold that one.

ConfigActivation

The latest live config delivery and the last version whose live activation finished.

Field Type Description
target_version string The version that the latest delivery attempted to activate.
completed_version string The last completed version, empty when none was recorded.
state ActivationState The state of the latest delivery's activation.
step string The latest activation step started, if any.
failed_step string The first recorded failed step, if any.
from_earlier_boot bool The completed version was recorded before this boot.
attempt_from_earlier_boot bool The latest attempted delivery was recorded before this boot.
unwritten bool chalkd could not write the record the last time it tried, so it may tell of an earlier delivery or of none; the journal says why.

Field types: ActivationState.

ConfigTrial

A config on trial, which the node rolls back by itself at the deadline unless ConfirmConfig confirms it first.

Field Type Description
version string The version of the config on trial, as StatusResponse.config_version gives it.
previous_version string The version of the config the node ran before, which the rollback delivers again.
deadline google.protobuf.Timestamp When the node rolls the config back, unless it is confirmed first.
error string Why the last attempt to roll the config back failed, which the node tries again each minute: the rollback at the deadline, or a delivery of previous_version, which the node runs already, that finishes a rollback or a trial whose delivery failed before it wrote the config. It also holds why the node could not read the trial's config slot at the deadline, which it tries again as well. Empty while none failed. While it is set, ConfirmConfig still confirms the config and stops the retries, unless rollback_changed is set.
ignore_units list of string The units the trial's health check leaves out besides those the image ignores, as ApplyConfigRequest.ignore_units named them.
rollback_changed bool Whether an attempt to roll the config back failed after it changed the node, as when a rollback at the deadline wrote the config and a restart failed after. A failed delivery of previous_version that finishes a rollback sets it too. ConfirmConfig refuses then; the node keeps trying to finish the rollback each minute, and RollbackConfig to previous_version finishes it at once.

Diagnostic

A diagnostic the image declares.

Field Type Description
name string Name RunDiagnostic takes, such as "route-get".
description string One sentence on what the diagnostic shows.
parameters list of DiagnosticParameter Its parameters: those a call must give, then the others, each in the order its command names them.
role string Least role that runs it: reader, operator or admin.
timeout string How long it may run before systemd stops it, such as "10s".

Field types: DiagnosticParameter.

DiagnosticExit

How a diagnostic's command ended.

Field Type Description
code int32 Its exit status, while stopped is empty.
stopped string Why the command ended without exiting by itself, else empty: "timeout" once it ran longer than the diagnostic's timeout, "output-limit" once it printed more than 1 MiB, of which the stream holds the first 1 MiB, or systemd's result of its unit, such as "signal".

DiagnosticParameter

A parameter of a diagnostic.

Field Type Description
name string Name the arguments of RunDiagnostic give it by.
type string What its value is: address, prefix, hostname, interface, int, enum or pattern.
description string One sentence on the value.
optional bool Whether a call may leave it out.
default_value string The value it takes when a call leaves it out; empty when leaving it out drops the arguments of the command that name it.
min int64 or unset Least value of an int parameter, when it has one.
max int64 or unset Greatest value of an int parameter, when it has one.
values list of string The values of an enum parameter.
regex string The RE2 regular expression a pattern parameter's value matches whole.

Disk

A disk of the node, as sysfs and the udev database describe it.

Field Type Description
name string Kernel name, such as nvme0n1.
device string Device node, such as /dev/nvme0n1.
model string Model, from udev's ID_MODEL with spaces for underscores, or else from sysfs.
size uint64 Size in bytes.
serial string Serial number, from udev's ID_SERIAL_SHORT, or else ID_SERIAL.
wwn string World Wide Name, from udev's ID_WWN; empty for a disk without one.
type string Kind of disk: nvme, ssd or hdd.
path string Path of the disk's connection, from udev's ID_PATH.
partitions list of Partition The disk's partitions, by number.
usage string How chalkos uses the disk: "boot" for the boot disk, "disk <name>" for a pinned disk of the node's storage, empty when chalkos does not use it.

Field types: Partition.

DiskReference

A disk by /dev path, or by a selector whose set fields must all match.

Field Type Description
path string Path of the disk below /dev, such as /dev/disk/by-id/…; set without the selector fields.
model string Glob the disk's model matches, such as "Samsung SSD 870*".
serial string The disk's serial number.
wwn string The disk's World Wide Name.
size string Comparison the disk's size meets, such as ">= 1T"; without an operator, the size it equals.
type string Kind of disk: nvme, ssd or hdd.

DiskStatus

A disk of the node's storage, as the boot's storage setup left it.

Field Type Description
name string The disk's name in the node's storage: system for the system disk, or the name of the Volume that has the disk to itself.
device string Device node the disk was found at, such as /dev/nvme0n1; empty when it was not found.
error string Why the disk's volumes could not be created or opened at boot; empty when they were.

ImageChunk

A piece of an image's parts, which follow the header back to back in the header's order.

Field Type Description
data bytes The next bytes of the parts; a chunk may end inside a part or span two. chalkctl sends 1 MiB per chunk.

ImageContract

The contract of the image an installer writes, as its image directory holds it.

Field Type Description
system_definitions map of string The image's repart definitions of the system region (ESP, slots A and B, STATE) by file name, which the installer lays out the target disk with. Each image chooses its partition sizes, so the installer's own may not fit.
schemas map of bytes The image's schemas by file name, as its image directory's schemas/ holds them, which the installer translates the config with to lay out the target disk.
layer_facts list of google.protobuf.Any The facts of the image's layers, such as chalkos.kubernetes.v1.ImageFacts; empty for an image whose layers have none.

ImageHeader

An image as install and upgrade send it. Its parts follow the header as chunks, in this order: the store data, the hash tree, the UKI and, when the header names one, the boot loader, unless the request's source names where the node pulls them from.

Field Type Description
image_id string The image's ID, as its os-release names it.
root_hash bytes The verity root hash of the image's store.
store ImagePart The store data, which the root hash covers.
hash_tree ImagePart The store's verity hash tree.
uki ImagePart The signed UKI that boots the image.
boot_loader ImagePart The signed systemd-boot, which firmware starts from the ESP's removable-media path.
architecture string The architecture the image runs on, as systemd and os-release name it: x86-64 or arm64. A node refuses an image of another architecture than its own.
platform string The platform the image is built for, as its os-release names it, such as metal or kvm. A node refuses an upgrade to an image of another platform than its own, and the installer translates the config for the platform the image names.
revision string The git revision the image was built from, as its directory's metadata.json names it; empty when the build named none. The node records it to show beside the image's root hash; nothing compares it.
tag string The git tag the image was built from, as its directory's metadata.json names it; empty when the build named none. The node records it as it does revision.

Field types: ImagePart.

ImagePart

The size and SHA-256 of a part of an image.

Field Type Description
size uint64 Size in bytes.
sha256 bytes SHA-256 of the part's bytes.

ImageSource

Where a node takes an image's parts from when they do not follow the header as chunks.

Field Type Description
oci RegistryImage, oneof source A chalkos image in an OCI registry, which the node pulls.

Field types: RegistryImage.

InPlace

The target of an install in place, which the node's own image runs from its boot disk.

No fields.

InstallHeader

What an install delivers: the node's credentials and config, the target and the image.

Field Type Description
node_certificate bytes PEM certificate chalkd serves once the node is installed.
node_key bytes PEM key of node_certificate.
ca_certificate bytes PEM certificates of the OS CAs the node trusts, the one that issues client certificates and the node CA first, then those still trusted while it rotates.
fallback_secret string Recovery key or password enrolled as the second keyslot of every encrypted volume; empty when the node's fallback is none.
in_place InPlace, oneof target Target of a node whose image already runs from its boot disk.
disk DiskReference, oneof target Target disk, which the installer lays out and writes the streamed image to.
image ImageHeader The image the installer writes to the target disk; it must name the boot loader. Installer only.
wipe_disk bool Whether the installer may replace what the target disk holds, including an installed node.
config string The node's config: YAML documents separated by ---. The image the node boots checks them as a set, fills in their defaults and translates them into what the node applies at boot, which STATE keeps with them: in place the running image, from the installer the image's own checker, once its store is on the target disk. Required.
contract ImageContract, oneof origin The contract of an image whose parts follow the header as chunks. Installer only: in place, chalkd checks the config against the running image.
source ImageSource, oneof origin An image in a registry, which the installer pulls. Its contract layer holds the image's contract, and the request carries nothing after the header. Installer only.
layers list of google.protobuf.Any Payloads of the installed image's layers, such as chalkos.kubernetes.v1.Share, which the node keeps on STATE. The node refuses a payload no layer takes.

Field types: InPlace, DiskReference, ImageHeader, ImageContract, ImageSource.

OutputStatus

The state of one output of the running image.

Field Type Description
name string The output's name, as the image declares it.
hash string The SHA-256 of the names and contents of the files the node serves, in lower-case hex; empty while it serves none, as after a render that failed at boot.
error string Why the output's last render or check failed, at a delivery or at boot; empty once one passed. What the program wrote to standard error is in the node's journal alone.

Partition

A partition of a disk, as sysfs and the udev database describe it.

Field Type Description
device string Device node, such as /dev/nvme0n1p3.
number uint32 Partition number.
size uint64 Size in bytes.
type string GPT partition type UUID, in lower case.
label string GPT partition name.
uuid string GPT partition UUID, in lower case.
content string File system or other content blkid found, such as ext4 or crypto_LUKS.

PendingConfig

Config a node holds for its next upgrade, kept unchecked until that upgrade checks it against the image it installs.

Field Type Description
version string The config's version, as StatusResponse.config_version gives the running one's.
since google.protobuf.Timestamp When the node stored it; unset for a dry run, which stores nothing.

PendingOutcome

What an upgrade did with the node's pending config.

Field Type Description
version string The pending config's version.
fate PendingFate Whether the image took it, the upgrade's config replaced it, or the node keeps it.

Field types: PendingFate.

Plan

What a delivery would do, as a dry run plans it before anything changes.

Field Type Description
version string The version of the config the delivery would run, as StatusResponse.config_version gives it; empty for a request without config.
replaces string The version of the config the delivery would replace; empty for a request without config or a node without one.
outputs list of string Names of the image's outputs whose rendered files, or the Secrets their documents reference, would change, sorted.
effects list of PlannedEffect The effects the delivery would take, by name. An effect whose rule compares the node's facts after the delivery with those before it is planned with the facts as they are, which the delivery has not changed yet.

Field types: PlannedEffect.

PlannedEffect

An effect a delivery would take.

Field Type Description
name string Name of the effect, as the image declares it.
fired_by list of string What fires it: "output <name>", "kind <name>" or "rule".
actions list of string What it does, in the order the node does it: "reload <units>", "run <command>", "restart <units>" and "chalkd <action>".

RegistryImage

A chalkos image in an OCI registry.

Field Type Description
reference string The image's repository and manifest digest, repository@sha256:…, as chalkctl resolved the inventory's reference. The node pulls that manifest and refuses it unless its config is the image the header describes and its store, hash-tree, UKI and, for an install, boot-loader layers have the header's sizes and SHA-256 sums. An upgrade pulls through the Mirror and authenticates with the Registry documents of the config the request delivers, or without one of the running config; an install through those of the config the request delivers. It tries each endpoint of the Mirror of the reference's host, then the host, each with the Registry of its own host, and pulls anonymously from a host without one.

SecureBootDriver

A UEFI driver the firmware measured into PCR 2.

Field Type Description
sha256 bytes The SHA-256 Authenticode digest of the driver's image.
device_path string Where the firmware found the image, as UEFI writes device paths, such as PciRoot(0x0)/Pci(0x3,0x0)/Offset(0x10a00,0x2f9ff), or the size of a path of other nodes.

StagedSlot

The config slot of the image staged in the inactive slot, as config delivered to the running image writes it.

Field Type Description
version string The version of the config the slot holds once written, as StatusResponse.staged_config_version gives it.
replaces string The version of the config the slot held before; empty when it held none.

StorageChange

A change a delivery made to the node's storage.

Field Type Description
volume string Name of the volume that changed.
reason string What changed, such as "new volume", "new volume on new disk <disk>", "larger: 200G instead of 100G" or "mounted at /data instead of null".

TimeStatus

How the node keeps its clock, as chrony reports it.

Field Type Description
synchronised bool Whether chrony synchronises the clock with a server.
source string The server the clock follows.
offset_seconds double How far the clock is from the server's time, in seconds; positive when it is ahead.
error string Why chrony's state could not be read; empty when it was.

TrustStatus

What the node trusts of one kind, and what it issues with.

Field Type Description
name string What is trusted: "OS CA" on every node; a layer adds what it trusts, such as "Kubernetes CA" on a node with Kubernetes.
fingerprints list of string The SHA-256 fingerprints of what is trusted, in lower-case hex: of certificates and of public keys in DER, and of encryption keys hashed apart from both. The one that issues or signs comes first.
issuing string The fingerprint of the value the node issues, signs or encrypts with; empty where it does none of these.

UpgradeHeader

What an upgrade delivers: the image and, optionally, the node's config for it.

Field Type Description
image ImageHeader The image to install. The node refuses another ID or platform than its own, and an image that names a boot loader: an upgrade leaves the boot loader as it is.
reboot bool Whether the node reboots into the image once it is installed.
config string The node's config for the image, as ApplyConfigRequest.config holds it. The node checks it against the image's schemas and change rules as ApplyConfig does: it refuses what the rules refuse, such as a storage change that takes a reset or a reinstall, or a change of a fixed Kubernetes setting, makes the storage changes they accept, such as a new volume, at once, and keeps the config in the image's config slot. Empty takes the node's pending config, which ApplyConfigRequest.staged keeps, or without one carries the running image's config over, checked against the image the same way. Once the upgrade staged the image, and activated it unless stage_only is set, the node drops its pending config, used or not; an upgrade that fails keeps it. Only the admin role may set it.
fallback_secret string Recovery key or password enrolled on the encrypted volumes the config adds, as ApplyConfigRequest.fallback_secret is; required when it adds one and the node's fallback is not none. Only the admin role may set it.
source ImageSource Where the node takes the image's parts from. Absent, they follow the header as chunks; for an image in a registry, the node pulls them and the request carries nothing after the header.
stage_only bool Whether the node stops once the image is staged: its store written, its config checked by the image's own checker and kept in its config slot, its UKI on the ESP under a name the boot loader does not boot. ActivateImage makes it boot next. An image that boots next already stays so. The node refuses it together with reboot.

Field types: ImageHeader, ImageSource.

VolumeStatus

A volume of the node's storage.

Field Type Description
name string The volume's name: var for VAR, or the name of its Volume document.
disk string Name of the disk the volume is on, as DiskStatus.name gives it.
mount_point string Where the config mounts the volume; empty for a volume it leaves unmounted.
present bool Whether the volume's partition exists.
mounted bool Whether the volume is mounted at its mount point.
encryption string How the volume is encrypted: tpm2, or none.
size_bytes uint64 The size of the volume's file system in bytes, while it is mounted; zero otherwise.
used_bytes uint64 The bytes the volume's file system uses, while it is mounted; zero otherwise.

Enums

ActivationState

The state of a live config activation.

Name Number Description
ACTIVATION_STATE_UNSPECIFIED 0 Not reported.
ACTIVATION_STATE_UNKNOWN 1 The node could not read its activation record.
ACTIVATION_STATE_UNRECORDED 2 No activation is recorded for the config the running image's slot stores.
ACTIVATION_STATE_IN_PROGRESS 3 chalkd is activating the target version now.
ACTIVATION_STATE_INTERRUPTED 4 The activation stopped part way, as when chalkd or the node stopped during it.
ACTIVATION_STATE_FAILED 5 The activation failed at its failed step.
ACTIVATION_STATE_COMPLETE 6 The target version is activated.

Mode

The mode chalkd serves the node in.

Name Number Description
MODE_UNSPECIFIED 0 No mode; chalkd never reports it.
MODE_MAINTENANCE 1 The node is not installed: chalkd serves a self-signed certificate.
MODE_NORMAL 2 The node is installed: chalkd serves its node certificate and requires client certificates.

PendingFate

The fate of a pending config in an upgrade.

Name Number Description
PENDING_FATE_UNSPECIFIED 0 No fate; chalkd never reports it.
PENDING_FATE_TAKEN 1 The image boots next with it, which it checked first, and the node dropped it.
PENDING_FATE_REPLACED 2 The image boots next with the config the upgrade carried, and the node dropped it.
PENDING_FATE_KEPT 3 The node keeps it for a later upgrade: the upgrade wrote no config slot, as for an image the node runs already or the known-good image a rollback staged with the config it last ran, or the node failed to remove it, which its journal records.

SecureBoot

The state of Secure Boot, as the firmware's EFI variables SecureBoot and SetupMode give it.

Name Number Description
SECURE_BOOT_UNSPECIFIED 0 No state; chalkd never reports it.
SECURE_BOOT_DISABLED 1 Secure Boot is off, or its EFI variables cannot be read.
SECURE_BOOT_ENABLED 2 Secure Boot is on: the firmware starts only binaries that db allows.
SECURE_BOOT_SETUP_MODE 3 The firmware accepts new Secure Boot keys without authentication.

SlotState

The state of the image in the node's inactive slot.

Name Number Description
SLOT_STATE_UNSPECIFIED 0 No image is staged.
SLOT_STATE_STAGED 1 The image's store is written and its own checker accepted its config, which STATE keeps in its config slot; its UKI is on the ESP under a name the boot loader does not boot. ActivateImage makes it boot next; a reboot boots the running image again.
SLOT_STATE_ACTIVE 2 The image boots next: its UKI has its boot entry's name, counted after an upgrade and uncounted after a rollback from a boot that was not found healthy.

The definition is api/chalkos/kubernetes/v1/kubernetes.proto, package chalkos.kubernetes.v1.

KubernetesService

KubernetesService is the API of the node's Kubernetes side. Each method's comment names the modes it is available in and the least role a client certificate needs, as on NodeService. Only nodes call RenewNodeCertificate, with the node role. On an image without the Kubernetes layer every method fails with UNIMPLEMENTED, before the mode and the role are checked.

Status

Status reports the state of the node's Kubernetes: its part in the cluster, its preparation, its etcd membership, its Node, VIPs, control plane and the revoked nodes. Available in normal mode to readers, on images with the Kubernetes layer. The console may call it.

Request: StatusRequest. Response: StatusResponse.

StatusRequest

The request of Status.

No fields.

StatusResponse

The response of Status: the state of the node's Kubernetes.

Field Type Description
kind string The node's part in the cluster: controlplane or worker.
state string What the node waits for or is: "no share", "preparing" while its Kubernetes files are prepared, or why their preparation failed, such as "preparation failed: no ipv4 node address matches validSubnets 10.0.0.0/8 (the node has ...)"; then on a control-plane node "waiting for bootstrap or for the cluster at <endpoint>", what joining that cluster does or waits for, such as "joining the cluster at <endpoint>: etcd member <id> catches up" or a stale member and how to remove it, "bootstrapped" or "etcd data missing: restore etcd or reinstall the node"; "joined" on a worker, followed by ": the Node has no <family> pod range; ..." when the control plane allocated it no pod range of one of the worker's families.
phase Phase Where the node stands, as state describes it in words. Clients decide on the phase; state is for people to read.
node_ready string The status of the Node's Ready condition (True, False or Unknown), or why it could not be read.
vip string On a bootstrapped control-plane node of a cluster with VIPs: "holder" while the node holds them, "standby" otherwise. Empty on other nodes.
control_plane string On a bootstrapped control-plane node: "current" once its API server and etcd serve the certificates the node holds now and the API server answers ready, otherwise what is not so, such as "the API server serves certificates the node replaced". Empty on other nodes.
control_plane_current bool Whether control_plane is "current": the node's API server and etcd serve the certificates the node holds now and the API server answers ready. False on other nodes.
revoked_nodes list of RevokedNode On a bootstrapped control-plane node: the nodes revoked in the cluster, in name order, as the ConfigMap kube-system/chalkos-revoked-nodes lists them. Empty when none is revoked, and when they could not be read, which revoked_nodes_error tells apart.
revoked_nodes_error string On a bootstrapped control-plane node: why the revoked nodes could not be read; empty when they were.
api_server_version string The Kubernetes version of the API server the node's running config names, from the tag of the Cluster document's images.apiServer, such as 1.37.2. Every node reports it, a worker too, whose config names the cluster's API server as the control planes' does.
kubelet_version string The release of the running image's kubelet, as its image.json names it, such as 1.37.1.
control_plane_pods string On a bootstrapped control-plane node: "current" once the static pods of kube-apiserver, kube-controller-manager and kube-scheduler run the images the node's running config names and are Ready, as their mirror pods in kube-system show it; otherwise what is not so, such as "kube-scheduler runs registry.k8s.io/kube-scheduler:v1.37.1, not registry.k8s.io/kube-scheduler:v1.37.2" or "kube-apiserver is not Ready". Empty on other nodes.
control_plane_pods_current bool Whether control_plane_pods is "current". False on other nodes.
node_ready_reason string The reason the kubelet gives the Node's Ready condition, such as KubeletNotReady. Empty while the condition gives none, and when node_ready says why the Node could not be read.
node_ready_message string The message the kubelet gives the Node's Ready condition, such as "container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not initialized" on a node whose cluster has no CNI yet. Empty while the condition gives none, and when node_ready says why the Node could not be read.
pods_not_running list of NodePod The pods on the node that do not run: those whose phase is neither Running nor Succeeded, and running pods with a container that waits, as one in CrashLoopBackOff. A failed pod of a Job is left out, as it records a run that ended. Pending pods come first, then running ones, then failed ones and those of an unknown phase, each in namespace and name order, and the first 20 of them alone; pods_not_running_total counts them all. Read with the kubelet's credentials, as node_ready is. Empty while every pod runs and when they could not be read, which pods_error tells apart.
pods_error string Why the node's pods could not be read; empty when they were.
pods_not_running_total uint32 How many pods on the node do not run, of which pods_not_running lists the first 20.

Field types: Phase, RevokedNode, NodePod.

BGPStatus

BGPStatus reports the node's local BGP sessions without contacting Kubernetes. Available in normal mode to readers, on images with the Kubernetes layer. The console may call it.

Request: BGPStatusRequest. Response: BGPStatusResponse.

BGPStatusRequest

The request of BGPStatus.

No fields.

BGPStatusResponse

The response of BGPStatus.

Field Type Description
bgp chalkos.node.v1.BGPStatus The local speaker's status. Unset while BGP is disabled or there is no BGPSpeaker.

Bootstrap

Bootstrap initialises etcd on a control-plane node, starts the control plane and applies chalkos's add-ons and the objects of the node's Addon documents. It is refused on a node that is bootstrapped or holds etcd data, so no second cluster is ever initialised. Available in normal mode to admins, on images with the Kubernetes layer.

Request: BootstrapRequest. Response: BootstrapResponse.

BootstrapRequest

The request of Bootstrap.

No fields.

BootstrapResponse

The response of Bootstrap, once the add-ons are applied.

Field Type Description
applied uint32 Objects applied: chalkos's add-ons and those of the node's Addon documents.

EtcdMembers

EtcdMembers lists etcd's members as the node's own member sees them, with their health. It answers on control-plane nodes that are etcd members. Available in normal mode to readers, on images with the Kubernetes layer.

Request: EtcdMembersRequest. Response: EtcdMembersResponse.

EtcdMembersRequest

The request of EtcdMembers.

No fields.

EtcdMembersResponse

The response of EtcdMembers.

Field Type Description
members list of EtcdMember etcd's members, as etcd lists them.

Field types: EtcdMember.

EtcdRemoveMember

EtcdRemoveMember removes another node's etcd member. It is refused when the voters left would have fewer healthy members than their quorum, unless forced, and for the node's own member, which EtcdLeave removes. Available in normal mode to admins, on images with the Kubernetes layer.

Request: EtcdRemoveMemberRequest. Response: EtcdRemoveMemberResponse.

EtcdRemoveMemberRequest

The request of EtcdRemoveMember.

Field Type Description
member string The member's name or its ID in hex.
force bool Whether the member is removed even when the voters left would have no healthy quorum.

EtcdRemoveMemberResponse

The response of EtcdRemoveMember.

Field Type Description
removed EtcdMember The member that was removed, without its health.

Field types: EtcdMember.

EtcdLeave

EtcdLeave takes the node out of etcd: it releases the VIPs, removes its own member, if etcd still has it, with the same quorum guard, stops its control plane, deletes its etcd data and unpins its addresses. The node joins the cluster again only once it is reinstalled. A bootstrapped node whose own member does not answer leaves only when forced. Available in normal mode to admins, on images with the Kubernetes layer.

Request: EtcdLeaveRequest. Response: EtcdLeaveResponse.

EtcdLeaveRequest

The request of EtcdLeave.

Field Type Description
force bool Whether the node leaves through the other members also when its own etcd member does not answer, as on a node that lost its pinned address.

EtcdLeaveResponse

The response of EtcdLeave, once the node is out of etcd.

No fields.

RenewNodeCertificate

RenewNodeCertificate issues the calling node a node certificate from the node CA, for exactly the names of the node certificate it authenticated with. It answers on control-plane nodes and refuses a revoked node. Available in normal mode to nodes, on images with the Kubernetes layer.

Request: RenewNodeCertificateRequest. Response: RenewNodeCertificateResponse.

RenewNodeCertificateRequest

The request of RenewNodeCertificate.

Field Type Description
certificate_request bytes PKCS #10 certificate request (DER) signed with the node's new key, which never leaves the node. Only its key is used; the names come from the caller's certificate.

RenewNodeCertificateResponse

The response of RenewNodeCertificate.

Field Type Description
certificate_chain bytes The new node certificate followed by the certificate of the node CA that issued it (PEM).

RotationStep

RotationStep runs a step of a CA or key rotation that the node's Kubernetes side carries out; chalkctl rotate calls it. Available in normal mode to admins, on images with the Kubernetes layer.

Request: RotationStepRequest. Response: RotationStepResponse.

RotationStepRequest

The request of RotationStep.

Field Type Description
step RotationStep The step to run.

Field types: RotationStep.

RotationStepResponse

The response of RotationStep; each step sets the fields it reports.

Field Type Description
restarted list of string The workloads restarted, as namespace/kind/name.
token_secrets list of string The Secrets of type kubernetes.io/service-account-token, as namespace/name.
rewritten uint64 How many objects were updated.
encrypted list of EncryptedObjects The objects etcd holds by resource and key.
not_waited list of string The workloads restarted but not waited for, as namespace/kind/name: their rollout does not complete by itself (an OnDelete update strategy, a StatefulSet's partition, a paused Deployment).

Field types: EncryptedObjects.

DrainNode

DrainNode cordons a node of the cluster for an upgrade and evicts its pods through the eviction API, which keeps them within their PodDisruptionBudgets. DaemonSet pods, static pods and pods without a controller stay; they run again on the node once it is back. Pods with emptyDir volumes are evicted only when the request accepts losing that data. Pods that terminate already, as those an earlier drain evicted, are not evicted again, but the call returns only once they and the pods it evicted have stopped. A node that was cordoned already stays cordoned and unmarked; one this call cordons is marked chalkos.dev/upgrade-cordon. It answers on bootstrapped control-plane nodes. Available in normal mode to operators, on images with the Kubernetes layer. An eviction refused for good, or one a PodDisruptionBudget holds back until the timeout, fails the call with FAILED_PRECONDITION; pods that did not stop in time, or whose evictions the API server kept failing, with DEADLINE_EXCEEDED.

Request: DrainNodeRequest. Response: DrainNodeResponse.

DrainNodeRequest

The request of DrainNode.

Field Type Description
node string The node's name in Kubernetes.
timeout_seconds uint32 How long to wait for the pods to be evicted and gone, in seconds; zero waits five minutes.
delete_emptydir_data bool Whether pods with emptyDir volumes are evicted too, which loses their data.

DrainNodeResponse

The response of DrainNode: the pods evicted and the pods that stay.

Field Type Description
marked bool Whether the node is marked as cordoned for an upgrade, by this call or an earlier one.
evicted list of string The pods evicted, as namespace/name.
kept list of string The DaemonSet, static and finished pods, which stay on the node, as namespace/name.
unmanaged list of string The pods without a controller, which stay and which nothing starts again elsewhere, as namespace/name. The node lifecycle controller deletes them for good when the node stays down longer than their tolerations allow.

UncordonNode

UncordonNode makes a node DrainNode cordoned schedulable again and removes the mark; it leaves a node cordoned otherwise as it is. It answers on bootstrapped control-plane nodes. Available in normal mode to operators, on images with the Kubernetes layer.

Request: UncordonNodeRequest. Response: UncordonNodeResponse.

UncordonNodeRequest

The request of UncordonNode.

Field Type Description
node string The node's name in Kubernetes.

UncordonNodeResponse

The response of UncordonNode.

Field Type Description
uncordoned bool Whether the node was cordoned for an upgrade and is schedulable again.

RevokeNode

RevokeNode cuts a node off the cluster by name: it lists the node in the ConfigMap kube-system/chalkos-revoked-nodes, applies the API server's admission policy chalkos-revoked-nodes, which then denies the node's writes, and deletes its Node object. Control planes then refuse to renew its node certificate. A node revoked already keeps the time of its first revocation. A call that fails after listing the node says so; calling again finishes it. A node not revoked yet is refused with FAILED_PRECONDITION while the policy's map of revoked nodes would grow too long for the API server to compile with it. It answers on bootstrapped control-plane nodes. Available in normal mode to admins, on images with the Kubernetes layer.

Request: RevokeNodeRequest. Response: RevokeNodeResponse.

RevokeNodeRequest

The request of RevokeNode.

Field Type Description
node string The node's name in Kubernetes, which its node certificate carries too.

RevokeNodeResponse

The response of RevokeNode.

Field Type Description
revoked_at google.protobuf.Timestamp When the node was revoked: now, or at an earlier revocation.
node_deleted bool Whether the call deleted the node's Node object; false when the cluster had none.

UnrevokeNode

UnrevokeNode removes a node from the revoked nodes and applies the admission policy without it, so a node of that name may join again. The old node's certificates work again too, unless the CAs they chain to were rotated after the revocation: the call is refused with FAILED_PRECONDITION while the OS CA or the Kubernetes CA predates it, unless forced. A call that fails after removing the node says so; calling again applies the policy. It answers on bootstrapped control-plane nodes. Available in normal mode to admins, on images with the Kubernetes layer.

Request: UnrevokeNodeRequest. Response: UnrevokeNodeResponse.

UnrevokeNodeRequest

The request of UnrevokeNode.

Field Type Description
node string The node's name in Kubernetes.
force bool Whether the node is unrevoked although the CAs its old certificates chain to predate the revocation.

UnrevokeNodeResponse

The response of UnrevokeNode.

Field Type Description
revoked_at google.protobuf.Timestamp When the node was revoked; unset when the time it is listed with cannot be read, which counts every CA as made before the revocation.
stale_cas list of string The CAs issued before the revocation, by the names chalkctl rotate takes: os-ca, kubernetes-ca. The old node's certificates work again until they expire or these CAs are rotated. Empty when both were rotated after the revocation.

Messages of chalkos.kubernetes.v1

These messages are held by fields of other messages.

EncryptedObjects

How many objects of one resource etcd holds under one key.

Field Type Description
resource string The resource, such as secrets.
key string The name of the key the objects are encrypted with; empty for objects stored unencrypted.
objects uint64 Number of objects.

EtcdMember

A member of etcd.

Field Type Description
id uint64 The member's ID.
name string The node's name; empty while a member that was added has not started.
peer_urls list of string URLs the other members reach the member at.
learner bool Whether the member is a learner: a member without a vote, as a joining control-plane node is until it catches up.
unhealthy string Why the member did not answer; empty when it is healthy.

ImageFacts

The Kubernetes facts of an image, as its contract carries them in its layer facts.

Field Type Description
image_json bytes The image's Kubernetes facts: the release of the image's kubelet and the pod network it ships.

NodePod

A pod on the node that does not run.

Field Type Description
namespace string The pod's namespace.
name string The pod's name.
phase string The pod's phase: Pending, Running, Failed or Unknown.
reason string Why it does not run: the reason an init container gives that waits or failed, prefixed Init:, such as Init:CrashLoopBackOff, else the reason a waiting container gives, such as ImagePullBackOff, else the pod's own, such as Evicted; empty when none gives one.

NotEtcdMember

The error detail of a request that needs an etcd member, from a control-plane node that is none, as before it joined the cluster or after it left etcd. The request fails with FAILED_PRECONDITION, and another control-plane node may answer it. EtcdMembers, EtcdRemoveMember, RotationStep, DrainNode, UncordonNode, RevokeNode and UnrevokeNode give it.

No fields.

RevokedNode

A node revoked in the cluster.

Field Type Description
name string The node's name in Kubernetes.
revoked_at google.protobuf.Timestamp When the node was revoked; unset when the time it is listed with cannot be read.

Share

A node's Kubernetes share, as ApplyConfig and Install deliver it in their layers.

Field Type Description
share bytes The share (JSON): the CAs and keys for a control-plane node, the CA certificate and a kubelet client certificate for a worker.

Enums of chalkos.kubernetes.v1

Phase

Where a node stands in its Kubernetes cluster. On a control-plane node it follows the node's etcd membership.

Name Number Description
PHASE_UNSPECIFIED 0 No phase; chalkd never reports it.
PHASE_PREPARING 1 The node has no share yet, or its Kubernetes files are being prepared, or their preparation failed.
PHASE_WAITING 2 A control-plane node that is no etcd member and has not started joining. It waits for a bootstrap or for the cluster, or tries to reach the cluster to join it.
PHASE_JOINING 3 A control-plane node that started joining the cluster and has not finished. It may be an etcd member already.
PHASE_BOOTSTRAPPED 4 A control-plane node that is an etcd member: it initialised etcd or finished joining.
PHASE_ETCD_DATA_MISSING 5 A bootstrapped control-plane node whose etcd data is missing, as after VAR was reset. Its control plane does not start until etcd is restored or the node is reinstalled.
PHASE_LEFT 6 A control-plane node that left etcd. It joins the cluster again only once reinstalled.
PHASE_JOINED 7 A worker node whose Kubernetes files are prepared: its kubelet joins the cluster.

RotationStep

A step of a CA or key rotation that RotationStep runs.

Name Number Description
ROTATION_STEP_UNSPECIFIED 0 No step; chalkd refuses it.
ROTATION_STEP_RESTART_ADDONS 1 On a bootstrapped control-plane node: restart the Deployments, DaemonSets and StatefulSets of chalkos's add-ons and of the node's Addon documents, once the kube-root-ca.crt ConfigMaps of their namespaces hold every Kubernetes CA the node trusts, and wait until they rolled out.
ROTATION_STEP_LIST_TOKEN_SECRETS 2 On a bootstrapped control-plane node: list the Secrets of type kubernetes.io/service-account-token, whose tokens nothing signs again.
ROTATION_STEP_REWRITE_ENCRYPTED 3 On a bootstrapped control-plane node: update every object of the resources the API server encrypts without changing it, so the API server encrypts it with its first key, then count the objects etcd holds under each key.
ROTATION_STEP_COUNT_ENCRYPTED 4 On a bootstrapped control-plane node: count the objects etcd holds under each key.
ROTATION_STEP_RENEW_KUBELET_SERVING 5 On a node with Kubernetes: remove the kubelet's serving certificate and restart the kubelet, which requests a new one.

The definition is api/chalkos/router/v1/router.proto, package chalkos.router.v1.

RouterService

RouterService is the API of the node's router side. Each method's comment names the modes it is available in and the least role a client certificate needs, as on NodeService. On an image without the router layer every method fails with UNIMPLEMENTED, before the mode and the role are checked.

Status

Status reports the state of the router's routing daemons, its NAT64 instances, its resolvers and its DHCP servers and relays. Available in normal mode to readers, on images with the router layer. The console may call it.

Request: StatusRequest. Response: StatusResponse.

StatusRequest

The request of Status.

No fields.

StatusResponse

The response of Status: the state of a router's routing daemons, its NAT64 instances, its resolvers and its DHCP servers.

Field Type Description
peers list of chalkos.node.v1.BGPPeerStatus The router's BGP sessions, by VRF, the default first, then by BGPPeer document and by interface or address.
bgp_error string Why FRR's BGP state could not be read, such as vtysh's error; empty when it was. peers is then empty.
nat64 list of NAT64Status The router's NAT64 instances, one per Jool instance, which a NAT64 document names, by name.
nat64_error string Why Jool's state could not be read, such as jool's error; empty when it was. nat64 is then empty.
resolver ResolverStatus The resolver of the router's default VRF; unset on a router without one.
vrf_resolvers list of ResolverStatus The resolvers of the router's VRFs, one per VRF with a Resolver document, by VRF.
dhcp list of DHCPServerStatus The router's DHCP servers, one per VRF whose links DHCPSubnet documents serve, the default VRF's first, then by VRF.
bgp_absent bool Whether the image carries no BGP, as an image that leaves FRR out: peers and bgp_error are then empty.
dhcp_relays list of DHCPRelayStatus The router's DHCP relays, one per VRF whose links DHCPRelay documents relay, the default VRF's first, then by VRF.

Field types: NAT64Status, ResolverStatus, DHCPServerStatus, DHCPRelayStatus.

Routes

Routes lists the routes in the node's kernel, of the main table unless a VRF or another table is asked for, and the paths the BGP instance of that VRF selected, each within an address range when one is given. Available in normal mode to readers, on images with the router layer.

Request: RoutesRequest. Response: RoutesResponse.

RoutesRequest

The request of Routes.

Field Type Description
prefix string An address range, such as 2001:db8::/32: only the routes to it and to ranges within it. Empty for every route.
protocol string Only the kernel's routes of this protocol: kernel, boot, static, ra, dhcp, bgp or another the kernel names, or its number. BGP's paths are listed for bgp and for an empty protocol alone.
table string The kernel's routing table: main, local, default, all, or a table's number. Empty for main, or for the table of vrf.
vrf string The VRF whose routes to list, by the name of its VRF document, or default: the routes of its table, which the node's running VRF document gives, and the paths of its BGP instance. Empty for the default VRF. A request gives vrf or table, not both.

RoutesResponse

The response of Routes.

Field Type Description
kernel list of KernelRoute The kernel's routes, in the order of their tables, families and destinations.
bgp list of BGPRoute The paths BGP selected and installs, in the order of their families and prefixes; none on an image without BGP.
bgp_error string Why BGP's paths could not be read, such as vtysh's error; empty when they were.
vrf string The VRF whose routes these are: the request's vrf, or default for a request without one. A node whose image does not know VRFs leaves it empty and lists the main table and the default instance's paths, whatever the request's vrf.

Field types: KernelRoute, BGPRoute.

Messages of chalkos.router.v1

These messages are held by fields of other messages.

BGPRoute

A path of BGP's for a prefix, which its best path selection took.

Field Type Description
prefix string The prefix, such as ::/0.
as_path string The ASes of the path, separated by spaces; empty for a route the router originates.
next_hops list of string The next hop addresses FRR resolved for the path.
peer string The neighbour the path came from: its interface, for a session of an interface, or its address; empty for a route the router originates.
local_pref uint32 or unset The path's local preference, when it carries one.
med uint32 The path's multi-exit discriminator.
communities list of string The path's standard and large communities.
best bool Whether it is the best path; otherwise one of the equal paths BGP installs beside it.
imported_from string The VRF whose BGP instance the path came from, through the importing instance's spec.import, or the route distinguisher it came from when FRR names no VRF; empty for a path of the instance's own peers or networks.

DHCPRelayStatus

A DHCP relay of a router: dnsmasq's relay of one VRF.

Field Type Description
vrf string The VRF whose links the relay relays: the name of its VRF document, or default.
running bool Whether the relay runs: its unit is active and bound to its VRF's device.
error string Why the relay does not run, such as the state of its unit; empty while it runs.

DHCPServerStatus

A DHCP server of a router: Kea's DHCPv4 or DHCPv6 server of one VRF.

Field Type Description
vrf string The VRF whose links the server serves: the name of its VRF document, or default.
family string The address family the server leases: ipv4 or ipv6.
running bool Whether the server runs: its unit is active, bound to its VRF's device, and it answers on its control socket.
error string Why the server does not run, such as the state of its unit or why it did not answer; empty while it runs.
subnets list of DHCPSubnetStatus The subnets the server serves, in the order of their documents; empty while it does not run.

Field types: DHCPSubnetStatus.

DHCPSubnetStatus

A subnet of a DHCP server, as Kea counts its leases.

Field Type Description
name string Name of the DHCPSubnet document.
subnet string The subnet's range, such as 192.0.2.0/24.
leased uint64 Addresses the server leased that have not expired, reserved ones included.
pool uint64 Addresses of the subnet's pools; the largest 64-bit number for more.
delegated uint64 Prefixes the server delegated that have not expired, of an IPv6 subnet.
delegable uint64 Prefixes the subnet delegates from, of an IPv6 subnet; the largest 64-bit number for more.

KernelRoute

A route in the kernel's routing tables.

Field Type Description
destination string Destination address range, such as ::/0.
type string The route's type: unicast, local, broadcast, anycast, multicast, blackhole, unreachable, prohibit or throw, or its number.
protocol string What installed it: kernel, boot, static, ra, dhcp, bgp and others the kernel names, or its number.
table uint32 The routing table, by number: 254 is main, 255 local and 253 default.
metric uint32 The route's metric.
next_hops list of NextHop Where the route leads; several for a route over equal-cost paths.

Field types: NextHop.

NAT64PoolStatus

A NAT64 instance's pool of one protocol.

Field Type Description
protocol string The protocol: tcp, udp or icmp.
size uint64 IPv4 addresses and ports, or ICMP identifiers, the pool holds for the protocol; 0 when it holds none. An instance whose pool is empty takes the router's own addresses.

NAT64Status

One NAT64 instance of a router, as Jool reports it.

Field Type Description
name string Name of the NAT64 document, which names its instance.
sessions uint64 Connections the instance translates, of all protocols.
bindings uint64 IPv4 addresses and ports of the pool that translated connections hold, of all protocols: one per IPv6 address and port, or ICMP identifier, that the instance translates.
pools list of NAT64PoolStatus The instance's pool for TCP, UDP and ICMP, in this order.

Field types: NAT64PoolStatus.

NextHop

A next hop of a kernel route.

Field Type Description
gateway string The gateway's address, which may be of the other family; empty for a route on the link alone.
interface string The interface the route leaves through.
weight uint32 The next hop's weight among several, from 1; 0 for a route of one next hop.

ResolverStatus

The state of a router's resolver.

Field Type Description
running bool Whether Unbound runs: the default VRF's answers on its control socket, and a VRF's unit is active.
error string Why Unbound does not run, such as unbound-control's error or the state of a VRF's unit; empty while it runs.
vrf string The VRF whose resolver this is; empty for the default VRF's.

Sources: api/chalkos/node/v1/node.proto, api/chalkos/kubernetes/v1/kubernetes.proto and api/chalkos/router/v1/router.proto, rendered by protoc-gen-doc with api/markdown.tmpl. The modes and roles the methods name are those of the permissions in pkg/chalkd/server.go and of each layer's plugin in pkg/chalkd/layers.