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.