The node API in code¶
chalkd checks the role of every request explains the API's roles; this page maps the API to the code.
Four proto files define the APIs¶
The API is defined in four files below api/chalkos/:
| File | What it holds |
|---|---|
node/v1/node.proto |
NodeService, which every image serves. |
kubernetes/v1/kubernetes.proto |
The Kubernetes layer's API. |
router/v1/router.proto |
The router layer's API. |
check/v1/check.proto |
What chalkd and an image's checker exchange. No client calls it, and the API reference leaves it out. |
buf generate writes the Go code below pkg/api/. Comments in the proto files become the
Node API page, so they are written for users.
chalkd serves NodeService over Connect on TCP port 50000 with mutual TLS. It mounts each compiled layer plugin's service beside it.
Each method has a permission entry¶
One table per API says which client role may call a method, and in which mode. NodeService's is
permissions in pkg/chalkd/server.go. Each layer plugin has its own Permissions, such as that
of pkg/chalkd/layers/kubernetes.
nodev1connect.NodeServiceInfoProcedure: {Modes: layer.AnyMode, Role: pki.RoleReader},
kubernetesv1connect.KubernetesServiceBootstrapProcedure: {Modes: layer.NormalOnly, Role: pki.RoleAdmin},
A new method needs an entry there, because the authoriser refuses a method without one. For a
method of a layer the image lacks, the authoriser answers UNIMPLEMENTED before it checks the
mode. A handler of a layer's method therefore runs only on a node in normal mode whose image
carries that layer. It does not check for a missing layer itself.
One check sits outside the tables. Upgrade needs the admin role when its header carries config
or a fallback secret, as ApplyConfig does. The table cannot see the header, so Upgrade checks
the role itself.