branderson
f6316e6c0e
Two findings, both from reading the path rather than the code. THE "RECORD IT PROPERLY" BLOCK WAS CONFINED-SHAPED. It ran install.sh - which does not run on a privileged host, deliberately - and then invoked dejima-ci-upgrade bare, which only works because install.sh had just put it there. A privileged operator following it got exactly the error that started this: the tool reporting it could not find itself. There is now a block per tier. Confined keeps install.sh. Privileged gets the three install commands bootstrap uses, because bootstrap is the only thing that installs the tool on that tier and re-running it on a built machine also redoes runner setup - a real cost for a machine that is already serving. Those three duplicate bootstrap's lines and can drift from them, so a test pins both ends to the same destinations. A tool installed to the wrong path is a tool that is not there, reported three sections later as "not installed here", which is how this whole thread started. THE UPGRADE DOCS WERE NOT LINKED FROM THE README AT ALL. Only docs/README.md mentioned them, so an operator with an existing runner had no path from the front page to the flow. There is now an "Updating an existing runner" section with the command to check a version, the instruction to walk the notes in order, and the two things a runner operator needs before starting: run from a checkout, and recording is itself a guest-side change. The runbook and the docs index point at it, and so does the intro, where someone skimming will be. `bats test/` 136 passing, 1 new.
2.3 KiB
2.3 KiB
Documentation
The README is the map: what this is, which tier you want, and how to operate one once it exists. The build itself is two pages, and this is where the second one lives.
| building-a-runner.md | The build, inside the VM: the Debian install, addressing, one bootstrap command, install.sh's settings, and the runners. The same on any hypervisor and for both tiers. Start at your hypervisor's page and it sends you here |
| reference.md | The two settings named docker.sock, CONFIG_FILE and why an edit can appear to do nothing, the /data volume, compose networks against job networks, whether several runners should share a job network, why the privileged runner is separate, why public egress is not restricted on the node, why the resolver is set per-runner, the cache server |
| threat-model.md | The adversary, where each tier's boundary sits, blast radius by layer, and what was rejected |
| upgrading.md | Moving a runner that already exists to a newer version, why the two halves are counted separately, and the seven steps a guest-side change takes when a rollback is going to rebuild the machine. Start at Updating |
| ../upgrades/ | One note per version: what an operator does in the console and in the guest to reach it |
| ../proxmox/README.md | The node-side half on Proxmox: the VM, the datacenter firewall, the security group and the order its rules go in, and all three snapshot moments including the scheduled rollback |
| ../proxmox/firewall.fw.template | The same node firewall as one annotated file, easier to review in one piece than as a table. Reference, not something to install |
| ../examples/ | The annotated templates dejima-ci-runners renders into ~/runners. Every setting carries the reasoning for its value, which the generated copies do not - read them here rather than reading what lands on the host |
One document lives outside this repository: dejima's docs/ci.md, which
covers why a CI run needs any of this over a sandbox, and why no approval gate
is offered. You do not need it to follow the README.