Repository navigation
Labels
enhancementNew feature or requestNew feature or request
Description
Why
Installing nodkey today means following docs/setup.md by hand: download and check a release, users and directories, the unit, the credential directory, later nodkey update and a unit compare. Each host does it again, and each step can be missed. Many hosts are already run with Ansible, so a role that does the install the way setup.md says, with the same checks, makes a host a few lines of config.
Proposal
A role in contrib/ansible/roles/nodkey/ (or an Ansible collection code6x.nodkey built from the repo; say which in DESIGN.md), with two sides:
nodkey_side: broker: installs a pinned release (nodkey_version) with the same checks asinstall.sh(SHA-256 fromSHA256SUMS,gh attestation verify, the binary's version) — best by running the installer built into the binary or theinstall.shof that tag with a pinned SHA-256 — thenodkeyuser and directories with the owners and modes of setup.md section 7,/etc/nodkey/credentials(0700, root) as an empty slot, andcontrib/systemd/nodkey.serviceof the same tag. It never writes credential values and never writesbroker.toml(a variable may point to a file the host provides; the role then only checks it withnodkey broker check). A changed binary or unit restarts the broker through a handler that the play can turn off (nodkey_restart: false), since a restart ends all grants.nodkey_side: agent: installs the same pinned release, and optionally thenodkey ssh-agentuser unit for one account (what many hosts need for SSH through the broker).- Idempotent: a second run with the same version changes nothing (
--check --diffshows no change). - Works with
ansible-playbook --connection local(for hosts that apply their own config, for example with pullgate).
Added 2026-11-16 (security review)
- Install path: when nodkey is already installed, the role updates it only through the installed binary (
nodkey update --version X), which uses its own built-in installer and checks. The checks must not come from the role or a repo that a change can edit. The first install uses theinstall.shof the pinned tag with its SHA-256 pinned in the role defaults. Forward only: the role refuses a version older than the installed one. - A fixed playbook for data-only hosts:
contrib/ansible/playbooks/broker-host.yml(andagent-host.yml) that read one data file (--extra-vars @host.yml) with a strict, documented schema, and acheck-datacommand or script that validates such a file (known keys only, types, version format, not older than installed). This lets a host keep only data in its repo, applied by a tool like pullgate, while the code that runs as root is installed and pinned on the host.
Done when
- The role exists with both sides, defaults documented in its README, and
ansible-lintclean. - CI runs the role in a systemd container (Debian stable) for both sides: a first run installs and
nodkey versionprints the pinned version; a second run reports no change; a run with a wrong SHA-256 fails and installs nothing. - CI checks that the unit the role installs is the one of the pinned tag.
- setup.md section 2 names the role as the third way to install, next to
install.shand by hand. - THREAT-MODEL.md: the role runs as root and downloads; the same checks as
install.sh, no setting to skip the attestation. - Updates go through
nodkey update --version Xof the installed binary, forward only; tests: an older version is refused, a newer one installs. -
broker-host.yml/agent-host.ymland the data check exist with their schema documented; tests: an unknown key, a wrong type and an older version fail the check. - The role, the playbooks and the data check are release assets (in
SHA256SUMS, covered by the attestation), so a host installs them pinned and checked; THREAT-MODEL.md says how they are fetched and checked. - No host names, IPs or private repo names anywhere (public repo).
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
groupsky commentedon Nov 18, 2026
hq-jobs
nodkey-193-ansible-role(runr-20261118-173018-87f4)Done in #213 (squash commit f9e53c7). Evidence for each "Done when" box:
ansible-lintclean:contrib/ansible/roles/nodkey(nodkey_side: broker | agent). The settings table is incontrib/ansible/README.md, "Settings", and inroles/nodkey/defaults/main.yml. CI jobansible, stepansible-lint(--strict --profile production).contrib/ansible/test/ci.shin the CI jobansible(imagecontrib/ansible/test/Dockerfile,debian:trixie-slim,--connection local). The checks:nodkey versionprints the pinned version:broker: the first run installs nodkey 0.7.0andagent: the first run installs nodkey 0.7.0 and the user unit;--check --diffreport no change:broker: …andagent: a second run, and a run with --check --diff, change nothing;a wrong SHA-256 of install.sh fails, and installs nothing.broker: the unit is contrib/systemd/nodkey.service of the tag v0.7.0. It is compared byte for byte withgit show v0.7.0:contrib/systemd/nodkey.service, also after the update.install.shand no setting to skip the attestation.nodkey update --version X, forward only:an update from nodkey 0.6.0 to 0.7.0 goes through nodkey update(the update task showschanged, andRun install.shshowsskipping);broker: an older version is refused, and nodkey 0.7.0 stays(check-data refuses it);the role alone refuses an older version too(the role's own check refuses it).broker-host.yml/agent-host.ymland the data check, with the schema documented:contrib/ansible/playbooks/,contrib/ansible/check-data, and README "The data file". Tests incontrib_ansible_linux_test.go:TestCheckDataBad: an unknown key, a wrong type, an older version, and more;TestCheckDataPrintsNoValue,TestCheckDataUsage,TestCheckDataGood;ci.sh:broker: a data file with an unknown key fails, and installs nothing..github/workflows/release.ymlbuildsnodkey_VERSION_ansible.tar.gzwithcontrib/ansible/build.shbeforeSHA256SUMS. The attestation coversdist/*.tar.gz. DESIGN.md section 18, docs/releasing.md and T53 say how a host gets and checks it. Tested byTestAnsibleBuildandTestAnsibleBuildRefuses. The first release that has the file is the next one.example-host,example-userandconfig-repo.Choices:
install.shand the unit of that tag.-e nodkey_data_file=PATH, not-e @host.yml. With@, every key would become an Ansible variable and could override a pin.