Common changes¶
This page lists the steps of the changes contributors make most often. Each checklist names every file to touch and the checks that prove the change. Run the commands in the development shell. Code conventions gives the rules each change follows, and Architecture for developers maps other changes to their files.
Add a node API method¶
The node API is NodeService in api/chalkos/node/v1/node.proto. A layer's API is its own
service, such as api/chalkos/router/v1/router.proto; the steps differ where noted.
- Declare the RPC and its request and response messages in the proto file. Its comment says
what it does, and ends with the modes and least role it is available in, such as
Available in normal mode to operators.A layer's RPC adds the layer:Available in normal mode to admins, on images with the Router layer.When the console may call it, addThe console may call it. -
Generate the Go code and the API reference page:
This writes
pkg/api/<api>/v1/anddocs/reference/api.md. -
Implement the handler. A node API method is a method of
*Serverinpkg/chalkd. A layer's method belongs to its chalkd plugin inpkg/chalkd/layers/<layer>. - Give the procedure its permission: the modes, the least role and the console's access. The
node API's are in
permissionsinpkg/chalkd/server.go, and a layer's come from its plugin'sPermissions. chalkd refuses a procedure without an entry. - Run the permission test of the API:
TestNodeAPIPermissionsinpkg/chalkd/server_test.go, or the layer's own, such asTestRouterAPIPermissions. Both calllayertest.CheckAPI, which fails unless each RPC's comment and its permission agree. - Call the method from chalkctl.
client.Connembeds the generatedNodeServiceClient, so a command callsconn.<Method>. A layer's chalkctl plugin creates its service's client on the connection, aspkg/chalkctl/layers/router/routes.godoes. - Add the command that uses it, as the next checklist describes, and the tests of the handler.
- Build the checks
api-generated,docs-generated,go-unitandgo-lint.
Add a chalkctl command¶
- Write the command in
pkg/chalkctl, built witha.command, or for a layer's command inpkg/chalkctl/layers/<layer>. Give itUse,Short,LongandExample. A command that reaches nodes registers its flags throughlayer.NodeFlags:Registerfor the secrets file alone,RegisterClientwhen a client file may run it. - Put its long description and examples in
help.goof the same package, beside the other commands' help.TestCommandsDescribedfails for a visible command without a short or long description or an example. - Add it to the tree: in
newCommandinpkg/chalkctl/chalkctl.go, or in the layer plugin'sCommands, by the group it joins. - A command that takes
--configgoes into the list ofclient new's help inpkg/chalkctl/help.go.TestClientNewNamesClientCommandscompares the two. - Test it in-process with
newTestApp, and with a chalkd that the test app'sstartNodeserves when the command reaches a node, as the tests beside it do. -
Regenerate the command reference and the navigation:
-
Name the command on the hand-written pages it affects, such as the command cheat sheet.
- Build the checks
go-unit,go-lint,docs-generatedanddocs.
A chalklab or chalkbuild command follows the same steps in pkg/chalklab or pkg/chalkbuild.
Add a built-in kind¶
A built-in kind is one every image accepts, such as TimeSync. A layer's kinds live in the
layer's modules instead.
- Declare the kind in a file of
modules/node/kinds/builtin/, asbuiltin groups.<group> // { description = ...; spec = { ... }; }, the waytime.nixdeclaresTimeSync. A new file goes into the imports ofmodules/node/kinds/builtin/default.nix, and a new API group intogroupsinlib/kinds/api.nix. - Use the kind in the module of its area: an output that renders from it, an effect, or a unit
that reads it.
modules/node/time.nixrenders chrony's sources fromTimeSync. - When Go code reads the kind, translate it in
pkg/config. Add its schema totest/fixtures/kinds/builtinand the kind totestBuiltinSchemasMatchFixturesintest/nix/kinds.nix, which holds the image's schema and the fixture equal. - Add evaluation tests to
test/nix/kinds.nixfor its defaults, rules and refusals. - Add image tests. Example files in
modules/node/examples/<area>/become tests throughchalkos.tests = chalkosLib.internal.exampleTests "<area>" ./examples/<area>;. A test ofchalkos.tests.<name>withoutputscompares the rendered files with golden directories. - Regenerate the kinds' reference and the built-ins page with
nix run .#docgen. - Build the checks
eval-kinds,eval,image-tests,rulesanddocs-generated, andgo-unitwhen Go code reads the kind.
Add a router feature¶
A router feature is a part of the router layer that an image can leave out, such as DHCP or
WireGuard. Its directory is in dash case, such as dhcp-relay/, and its name in camel case, such
as dhcpRelay.
- Create
modules/node/router/<feature>/default.nixandkinds.nix.kinds.nixis a function of{ chalkosLib, lib, routerLib }that returns the feature's kinds, anddefault.nixloads it withrouterLib.kinds ./kinds.nix. -
Declare the feature's option in
default.nix, and put everything else under it: -
Add the name to
featuresinmodules/node/router/lib.nix.routerLib.featurerefuses a name that is missing there. A new output also goes intooutputsthere, so the examples' tests compare its files. - Import
./<feature>inmodules/node/router/default.nix. - Pin the IDs of the feature's users and groups, as
dhcp/default.nixpinskea's. An unpinned ID moves the IDs after it whenever an image adds or drops a feature. - Add the feature to
testRouterFeaturesOptionalintest/nix/eval.nix: its kinds, outputs, effects, services, users and the examples that use it. The test checks that leaving the feature out removes exactly these. - Add an example,
modules/node/examples/router/<name>.yaml, which becomes the image testrouter-<name>. Createmodules/node/router/tests/<name>, build theimage-testscheck, read each diff and run the command its log prints withoutrm -r DIR &&. Image tests explains the golden directories. - When the feature runs a unit, add a check in a network namespace as
nix/checks/units/router-<feature>.nix. Each file of that directory is the check of its name. - Put a renderer written in Go in
cmd/chalkos-render, and the derivations it shares with chalkd inpkg/router/derive. - Add a page to
docs/router/, with its card ondocs/router/index.mdand its entry in the navigation ofzensical.toml, and regenerate the reference withnix run .#docgen. - Build the checks
eval,eval-kinds,rules,image-tests,docs-generated,docs, the feature's namespace check ande2e-routerwhen the feature needs a booted router.
Add a layer¶
A layer is a set of NixOS modules and a Go plugin in each program that serves it. Layer plugins describes the hooks of each plugin.
- Name the layer in
pkg/layers/layers.go, besideKubernetesandRouter. - Write its modules in
modules/node/<layer>/, imported bymodules/node/default.nix. Its optionchalkos.<layer>.enableis false by default. Under it, the module setschalkos.layers.<layer> = "";, which writes the marker/etc/chalkos/layers/<layer>. - Export the layer in
lib/layers.nix, which the flake gives asnixosModules.<layer>. Its entry setschalkos.<layer>.enable = true. - Declare its kinds in its modules, with a new API group in
lib/kinds/api.nix. Give each feature its ownchalkos.<layer>.<feature>.enable, as Code conventions says. - Write its API in
api/chalkos/<layer>/v1/<layer>.proto, and follow Add a node API method for each method. - Write chalkd's plugin in
pkg/chalkd/layers/<layer>: alayer.Pluginofpkg/chalkd/layerwith its API's handler, permissions and loops, and the hooks it needs. List it inpluginsincmd/chalkd/plugins.go. - Write chalkctl's plugin in
pkg/chalkctl/layers/<layer>, with its commands' help in its ownhelp.go. List it inpluginsinpkg/chalkctl/layers.go. - Write the layer's section of a node's status in
pkg/statusview/layers/<layer>, which chalkctl's plugin prints. - Write the console's tab in
pkg/console/layers/<layer>, and list it inlayerTabsincmd/chalkos-console/layers.go. - Add a row for each new directory of Go code to Packages and programs.
- Regenerate the code and pages with
buf generateandnix run .#docgen. - Build the checks
api-generated,docs-generated,docs,go-unit,go-lint,eval,eval-kindsandimage-tests. Extend an existing end-to-end test before you add one, as Keep the VM tests few and small asks.
Update a Kubernetes release¶
modules/node/kubernetes/releases.nix pins each Kubernetes minor an image can run to a patch
release and the hash of its source. An image builds its kubelet from that source and uses
nixpkgs's kubernetes package only as the build recipe, so a change of nixpkgs leaves the
kubelet as it is. The newest minor is the default of
chalkos.kubernetes.version, and the
test images, the templates, the examples and the documentation name its control-plane images.
- Change the
versionof the minor inreleases.nix. For a new minor, add its row first in the table, since Renovate takes the first row for the newest minor, remove the oldest, so that the table keeps the three minors Kubernetes supports, and movepublish = trueto the minors whose images a release of chalkos builds. A minor becomes the newest once it has a.1release, because the HA test starts from the patch release before the newest. -
Run
nix run .#update-pinsin the root of the repository. It takes no arguments and needs network access. It sets:- the
hashof every row, from the release's source on GitHub; - the images in
nix/testing/kubernetes-images.jsonthat follow the newest release: the API server, the controller-manager, the scheduler and kube-proxy of the newest release and of the patch release before it, and the etcd, CoreDNS and pause releases that kubeadm of the newest release names, each by the digest of its amd64 manifest with the hash of its OCI layout; - every reference to those images by digest in the templates, the examples, the test
fixtures,
modules/node/kubernetes/kinds.nix, chalkctl's help and the documentation.
A second run changes nothing. Renovate proposes each patch release in a pull request, and its fixup workflow runs
update-pinson it, as Dependency updates describes. 3. Build every kubelet withnix build .#kubelet-releases. Each compiles from source, and its build fails when the kubelet reports a version other than its release's. 4. For a new minor, regenerate the pages withnix run .#docgen, and search the documentation and the tests for the minor that left the table. 5. Build the checkseval,docs-generated,docs,fixtures,image-testsand thetemplate-*checks. Label the pull requeste2e, since the kubelet of every image with Kubernetes changes. - the