Repository navigation
feat: an Ansible role that installs nodkey from a checked release - #213
Merged
groupsky merged 1 commit intoNov 18, 2026
Merged
Conversation
contrib/ansible holds a role (broker or agent side), two fixed playbooks for a data file, check-data and build.sh. The first install runs the install.sh of the tag after a check of its pinned SHA-256; an update runs only "nodkey update --version X" of the installed binary, forward only. The release packs the recipe as nodkey_VERSION_ansible.tar.gz, in SHA256SUMS and covered by the attestation. CI runs ansible-lint and the role in a Debian container with systemd. Fixes #193 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
groupsky
deleted the
hq-job/nodkey-193-ansible-role/r-20261118-173018-87f4
branch
November 18, 2026 16:03
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
An Ansible recipe in
contrib/ansible/that installs nodkey on the broker host or on an agent machine, from a checked release (#193).roles/nodkey: the role,nodkey_side: brokeroragent.install.shof the tag, after a check of its pinned SHA-256. It checksSHA256SUMS, the attestation and the version, as always.nodkey update --version Xof the installed binary. Forward only: an older version is refused.nodkey,/etc/nodkey, an empty/etc/nodkey/credentials(0700), andcontrib/systemd/nodkey.serviceof the tag, unchanged. It never writesbroker.tomlor a credential.nodkey_broker_configrunsnodkey broker check. A changed binary or unit runssystemctl try-restart nodkey(off withnodkey_restart: false).nodkey ssh-agentuser unit for one account, in/etc/systemd/userwithConditionUser=, so the role never writes into the home directory.playbooks/broker-host.yml,playbooks/agent-host.yml: run the role from one data file (-e nodkey_data_file=PATH). The file is read withinclude_vars name:aftercheck-datapassed, so no key can override a pin.check-data: checks a data file: known keys only, types, version format, not older than installed.build.sh: makes the recipe of one release, withinstall.shand the unit of the tag, and their SHA-256 invars/main.yml. The release packs it asnodkey_VERSION_ansible.tar.gz(inSHA256SUMS, covered by the attestation).Tests
contrib_ansible_linux_test.go:check-data(good files, unknown key, key of the other side, wrong types, older version, key twice, no value in errors, usage) andbuild.sh.contrib/ansible/test/ci.shin the new CI jobansible: Debian stable container with systemd,--connection local, releases 0.6.0 and 0.7.0: first run installs, second run and--check --diffchange nothing, the unit is the one of the tag, a wrong SHA-256 installs nothing, an older version is refused (bycheck-dataand by the role), 0.6.0 → 0.7.0 goes throughnodkey update, agent side with the user unit.ci.sh:--check --diffon a new host installs nothing, a link in place of/usr/local/bin/nodkeyis refused and not run, a restart left due by a failed run is done by the next run, a badbroker.tomlfailsnodkey broker check, and the agent side without an account stops the agent and removes the unit.ansible-lint --strict --profile productionin CI.Docs
DESIGN.md section 18, THREAT-MODEL.md T53, docs/setup.md sections 2 and 13, docs/releasing.md, AGENTS.md,
contrib/ansible/README.md.Review
The security review and a correctness review ran on the change. Fixed: the role checks
/usr/local/bin/nodkeyand its directories before it runs it as root; the playbooks check and read one private copy of the data file, and no value can be an Ansible template; a restart is kept as a mark until a handler does it; key names in errors are cleaned;--checkon a new agent host works; the agent of an old account is stopped; stricter test checks.Not fixed, on purpose:
--check --diff). The README says to move changes to a drop-in before the first run. Refusing to replace it would block every host set up from setup.md section 8, where the unit is always edited.nodkey_restart: false, the mark is removed after one message. Keeping it would make every later run show a change, so the run would never be idempotent; the owner chose to restart by hand.Changes behavior for existing callers: no
Fixes #193
🤖 Generated with Claude Code