Developing ethere¶
ethere is a framework: the images, playbooks, operator and documentation every cluster runs, at the version its configuration pins. This tab is for whoever changes it: how it is laid out, how a change is made and tested, and the designs not built yet. How a cluster works today is the Admins tab.
The principles a change is checked against¶
- Easy, fast and cheap: Nova, Neutron, Glance, Cinder and S3 only, a DNS API for the zone holding the name servers; nothing managed beyond.
- Purpose-built images, zero post-boot configuration: everything in the image, nothing run against a server, nobody logs in. The first boot's user-data is a stopgap to shrink.
- Cattle: servers, certificates and CAs are short-lived and replaced, never repaired.
- Self-assembling through anycast: a component knows its own server and anycast addresses, never another server's; whether a server creates a cluster or joins it is decided by whoever creates it, never guessed.
- Everything the operator does, an admin can do the same way: the same playbook, by hand.
etherectlacts on the workstation only. - Exherbo is a deliberate choice, its compile time the accepted cost.
The repository¶
| Path | What |
|---|---|
inventory/ |
the variables, every default (<var>__<group> fragments merged per host) |
playbooks/ |
the entry points, _*.yml their task files |
plugins/ |
Ansible's filters, lookups, modules |
bin/, lib/, libexec/ |
etherectl (Bun) and the scripts the playbooks call |
paludis/repositories/ |
the Exherbo repositories (submodules), local patches |
charts/ |
the charts a cluster's configuration uses (ethere-tenants) |
share/ |
templates and vendored manifests |
docs/, mkdocs.yml |
this site |
tests/ |
the Bun test suite |
project/ |
ethere's own cluster configuration: its builds and tests |
Each area has a CLAUDE.md with its conventions (the root one, inventory/, playbooks/, plugins/, lib/,
tests/, paludis/): they are written for an agent, and are the most precise account of how the code is organised.
Making a change¶
- Where it goes: generic in ethere, specific to a cluster in its configuration (
inventory/group_vars,profile.d/,secrets/). - One worktree per stream of work:
git -C ~/ethere worktree add ~/ethere-wt/<name> -b <branch>, merged intoethe.re. A cluster tries it by pinningethere: {path: ~/ethere-wt/<name>}in itsethere.yaml, then moves itsrefonce merged: that commit of its configuration is its step into production. - With it: its tests, a
CHANGELOG.mdentry under[Unreleased]for what a user sees,TODO.mdfor what is left. Releases (vX.Y.Ztags, SemVer) are made on request. - In English: code, comments, task names, docs.
Testing¶
bun run test # the unit tier: etherectl, playbooks' logic, rendering
etherectl ns bun run test:root # what needs root in the namespace (image builds)
ETHERE_TEST_CLUSTER=1 ETHERE_TEST_CLOUD=ethere-test bun tests/cluster/run.js <suite> # a real cluster
The cluster suites run on the test cloud, a local OpenStack in a VM (etherectl test-cloud up): servers from
the images, the networks, the edge, a DNS zone, an S3. They take from a few minutes to an hour; the images they
need are built first (images.yml, containers.yml).
What's next¶
- The roadmap: what is known to be missing, the open questions.
- Cluster API providers: ethere's own, Ansible run by the operator; how they work, what is left.
- Designs not built yet: continuous delivery of the images, on-demand GPU nodes.