Roles and credentials¶
This page is for operators who hand out client files or read a refusal of the node API. It lists the least role each method of the node API needs, the modes chalkd serves it in, what the console on the machine's screen may call, the credential each chalkctl command needs, and the order in which chalkctl looks for the credentials of a command.
Roles¶
A client's role comes from its certificate. A certificate the OS CA issued directly grants the
role its Organization names. A certificate whose chain passes through the node CA has the role
node, whatever its Organization says.
| Role | Granted by | Allows |
|---|---|---|
| reader | a client certificate with the Organization reader |
the methods that need reader |
| operator | a client certificate with the Organization operator |
the methods that need reader or operator |
| admin | a client certificate with the Organization admin, or the certificate chalkctl issues itself from the secrets file |
every method that needs reader, operator or admin |
node |
a node certificate, which chains through the node CA | RenewNodeCertificate of the Kubernetes layer alone |
No other role allows a method that needs node, and node allows no other method. A node in
maintenance mode whose image was built without an OS CA treats every client as an admin, so a
caller without a certificate may install it and run every diagnostic.
Methods¶
chalkd checks the image's layers first, then the mode, then the certificate, then the role. A
method of a layer the image lacks fails with UNIMPLEMENTED and
the kubernetes layer is not in this image. A method called in a mode it is not served in fails
with the node is in maintenance mode; install it first or the node is installed. A
certificate that does not chain to an OS CA the node trusts at that moment fails with
the client certificate does not verify against the OS CAs the node trusts: .... A call whose
role is too low fails with a message that names the role it needs, such as
/chalkos.node.v1.NodeService/Reboot needs the operator role.
chalkd serves NodeService on every image and the API of each layer beside it:
KubernetesService on images with the kubernetes layer, and RouterService on images with the
router layer.
The Console column says whether the console may call the method: yes, or
action while the image allows the console's actions.
| Service | Method | Least role | Served in | Console |
|---|---|---|---|---|
| NodeService | ActivateImage | operator | normal mode | |
| NodeService | ApplyConfig | admin | normal mode | |
| NodeService | ConfirmConfig | admin | normal mode | |
| NodeService | Contract | reader | maintenance and normal mode | |
| NodeService | Diagnostics | reader | maintenance and normal mode | yes |
| NodeService | Disks | reader | maintenance and normal mode | yes |
| NodeService | EnrollSecureBoot | admin | maintenance mode | |
| NodeService | GetConfig | admin | normal mode | |
| NodeService | Info | reader | maintenance and normal mode | yes |
| NodeService | Install | admin | maintenance mode | |
| NodeService | Logs | reader | maintenance and normal mode | yes |
| NodeService | Reboot | operator | maintenance and normal mode | action |
| NodeService | ResetVolume | admin | normal mode | |
| NodeService | RollbackConfig | admin | normal mode | action |
| NodeService | RollbackImage | operator | normal mode | action |
| NodeService | RunDiagnostic | reader, and the diagnostic's own role | maintenance and normal mode | yes, for the diagnostics of readers and operators |
| NodeService | SecureBootDrivers | reader | maintenance mode | |
| NodeService | Shutdown | operator | maintenance and normal mode | action |
| NodeService | Status | reader | normal mode | yes |
| NodeService | Upgrade | operator; admin when the request carries config or a fallback secret | normal mode | |
| KubernetesService | Bootstrap | admin | normal mode | |
| KubernetesService | DrainNode | operator | normal mode | |
| KubernetesService | EtcdLeave | admin | normal mode | |
| KubernetesService | EtcdMembers | reader | normal mode | |
| KubernetesService | EtcdRemoveMember | admin | normal mode | |
| KubernetesService | RenewNodeCertificate | node |
normal mode, on control planes | |
| KubernetesService | RevokeNode | admin | normal mode | |
| KubernetesService | RotationStep | admin | normal mode | |
| KubernetesService | Status | reader | normal mode | yes |
| KubernetesService | UncordonNode | operator | normal mode | |
| KubernetesService | UnrevokeNode | admin | normal mode | |
| RouterService | Routes | reader | normal mode | |
| RouterService | Status | reader | normal mode | yes |
An Upgrade with config or a fallback secret from an operator fails with
/chalkos.node.v1.NodeService/Upgrade with config or a fallback secret needs the admin role; without them the node gives the image its pending config, else carries its own config over.
RunDiagnostic also needs the role the diagnostic names, which chalkctl node diag lists. A
reader who runs ping fails with the diagnostic ping needs the operator role.
The console¶
The console on the machine's screen reaches chalkd through the socket
/run/chalkd/console.sock, without TLS. The socket's directory has mode 0700 and the socket mode
0600, both owned by root. A call on the socket has no certificate and no role. chalkd checks the
image's layers and the mode as for any call, then the Console column in place of the role:
- A method with an empty Console column fails with
PERMISSION_DENIEDandthe console may not call <method>, such asthe console may not call /chalkos.node.v1.NodeService/Install. - A method marked
actionfails withPERMISSION_DENIEDandthe image turns the console's actions offon an image built withchalkos.console.actions.enableset to false. - RunDiagnostic runs the diagnostics of readers and operators. A diagnostic of admins fails with
the diagnostic <name> needs the admin role.
chalkd serves the socket only on an image built with
chalkos.console.enable set to true, the default.
chalkctl has no command that calls Shutdown.
Commands¶
Some chalkctl commands issue certificates or deliver keys and config, so they need the secrets file. The others take a client file of a high enough role, or the secrets file, which counts as admin:
| Command | Secrets file | Admin client file | Operator client file | Reader client file |
|---|---|---|---|---|
install, config apply, client new |
yes | no | no | no |
recovery-key, node renew, rotate |
yes | no | no | no |
storage reset |
yes | yes | no | no |
upgrade with config, upgrade --diff |
yes | yes | no | no |
upgrade without config, reboot |
yes | yes | yes | no |
status, logs, disks |
yes | yes | yes | yes |
bootstrap, etcd remove-member, etcd leave (Kubernetes) |
yes | yes | no | no |
etcd members (Kubernetes) |
yes | yes | yes | yes |
kubeconfig (Kubernetes) |
yes | no | no | no |
validate and gen secrets need neither. A command that needs the secrets file says so when
--secrets is missing, whatever client file there is:
pass the secrets file with --secrets FILE, or --secrets - to read it from standard input. During
an upgrade, the operator role also lets chalkctl drain and uncordon the nodes.
Where chalkctl finds its credentials¶
Commands that need the secrets file read it only from the file --secrets names, or from
standard input with --secrets -. chalkctl never looks for a secrets file on its own, and no
inventory names one.
Commands that accept a client file take the first of:
- the client file
--confignames, or the secrets file--secretsnames. Passing both fails withpass --secrets or --config, not both; - the client file
$CHALKOSCONFIGnames; ~/.config/chalkos/config, wherechalkctl client newwrites a client file without--out.
With none of them, the command fails with
there is no client file at <path>; pass --config or --secrets.
chalkctl refuses a client file whose certificate expired, with
the certificate of <path> expired on <date>; issue a new one with chalkctl client new. It warns
during the certificate's last 30 days.
Sources: pkg/chalkd/server.go, pkg/chalkd/console.go, pkg/chalkd/diagnostics.go,
pkg/chalkd/layers/kubernetes/plugin.go, pkg/chalkd/layers/router/router.go,
pkg/chalkd/upgrade.go, pkg/pki/roles.go and pkg/chalkctl/credentials.go.