Skip to content

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. etherectl acts 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 into ethe.re. A cluster tries it by pinning ethere: {path: ~/ethere-wt/<name>} in its ethere.yaml, then moves its ref once merged: that commit of its configuration is its step into production.
  • With it: its tests, a CHANGELOG.md entry under [Unreleased] for what a user sees, TODO.md for what is left. Releases (vX.Y.Z tags, 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