Skip to content

feat: an Ansible role that installs nodkey from a checked release - #213

Merged
groupsky merged 1 commit into
mainfrom
hq-job/nodkey-193-ansible-role/r-20261118-173018-87f4
Nov 18, 2026
Merged

groupsky merged 1 commit into
mainfrom
hq-job/nodkey-193-ansible-role/r-20261118-173018-87f4

Conversation

@groupsky

@groupsky groupsky commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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: broker or agent.
    • First install: the install.sh of the tag, after a check of its pinned SHA-256. It checks SHA256SUMS, the attestation and the version, as always.
    • Update: only nodkey update --version X of the installed binary. Forward only: an older version is refused.
    • Broker: the user nodkey, /etc/nodkey, an empty /etc/nodkey/credentials (0700), and contrib/systemd/nodkey.service of the tag, unchanged. It never writes broker.toml or a credential. nodkey_broker_config runs nodkey broker check. A changed binary or unit runs systemctl try-restart nodkey (off with nodkey_restart: false).
    • Agent: optional nodkey ssh-agent user unit for one account, in /etc/systemd/user with ConditionUser=, 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 with include_vars name: after check-data passed, 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, with install.sh and the unit of the tag, and their SHA-256 in vars/main.yml. The release packs it as nodkey_VERSION_ansible.tar.gz (in SHA256SUMS, covered by the attestation).
  • A plain role, not a collection: DESIGN.md section 18 says why.

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) and build.sh.
  • contrib/ansible/test/ci.sh in the new CI job ansible: Debian stable container with systemd, --connection local, releases 0.6.0 and 0.7.0: first run installs, second run and --check --diff change nothing, the unit is the one of the tag, a wrong SHA-256 installs nothing, an older version is refused (by check-data and by the role), 0.6.0 → 0.7.0 goes through nodkey update, agent side with the user unit.
  • Also in ci.sh: --check --diff on a new host installs nothing, a link in place of /usr/local/bin/nodkey is refused and not run, a restart left due by a failed run is done by the next run, a bad broker.toml fails nodkey broker check, and the agent side without an account stops the agent and removes the unit.
  • ansible-lint --strict --profile production in 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/nodkey and 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; --check on a new agent host works; the agent of an old account is stopped; stricter test checks.

Not fixed, on purpose:

  • A unit changed by hand is replaced by the unit of the tag (kept as a backup file, shown by --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.
  • With 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

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
groupsky merged commit f9e53c7 into main Nov 18, 2026
8 of 9 checks passed
@groupsky
groupsky deleted the hq-job/nodkey-193-ansible-role/r-20261118-173018-87f4 branch November 18, 2026 16:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Ansible role that installs nodkey (broker or agent side) from a checked release

1 participant