Skip to content

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

Closed

Description

@groupsky

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 as install.sh (SHA-256 from SHA256SUMS, gh attestation verify, the binary's version) — best by running the installer built into the binary or the install.sh of that tag with a pinned SHA-256 — the nodkey user and directories with the owners and modes of setup.md section 7, /etc/nodkey/credentials (0700, root) as an empty slot, and contrib/systemd/nodkey.service of the same tag. It never writes credential values and never writes broker.toml (a variable may point to a file the host provides; the role then only checks it with nodkey 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 the nodkey ssh-agent user unit for one account (what many hosts need for SSH through the broker).
  • Idempotent: a second run with the same version changes nothing (--check --diff shows 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 the install.sh of 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 (and agent-host.yml) that read one data file (--extra-vars @host.yml) with a strict, documented schema, and a check-data command 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-lint clean.
  • CI runs the role in a systemd container (Debian stable) for both sides: a first run installs and nodkey version prints 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.sh and 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 X of the installed binary, forward only; tests: an older version is refused, a newer one installs.
  • broker-host.yml / agent-host.yml and 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).

Activity

  1. groupsky commented on Nov 18, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-193-ansible-role (run r-20261118-173018-87f4)

    Done in #213 (squash commit f9e53c7). Evidence for each "Done when" box:

    • The role exists with both sides, defaults documented, ansible-lint clean: contrib/ansible/roles/nodkey (nodkey_side: broker | agent). The settings table is in contrib/ansible/README.md, "Settings", and in roles/nodkey/defaults/main.yml. CI job ansible, step ansible-lint (--strict --profile production).
    • CI runs the role in a systemd container (Debian stable) for both sides: contrib/ansible/test/ci.sh in the CI job ansible (image contrib/ansible/test/Dockerfile, debian:trixie-slim, --connection local). The checks:
      • first run installs and nodkey version prints the pinned version: broker: the first run installs nodkey 0.7.0 and agent: the first run installs nodkey 0.7.0 and the user unit;
      • second run and --check --diff report no change: broker: … and agent: a second run, and a run with --check --diff, change nothing;
      • wrong SHA-256 fails and installs nothing: a wrong SHA-256 of install.sh fails, and installs nothing.
    • The unit is the one of the pinned tag: broker: the unit is contrib/systemd/nodkey.service of the tag v0.7.0. It is compared byte for byte with git show v0.7.0:contrib/systemd/nodkey.service, also after the update.
    • setup.md section 2: "There are three ways to install", with the new subsection "The Ansible role". Section 13 says how to update with the role.
    • THREAT-MODEL.md: new T53. The role runs as root and downloads. It has the same checks as install.sh and no setting to skip the attestation.
    • Updates through nodkey update --version X, forward only:
      • an update from nodkey 0.6.0 to 0.7.0 goes through nodkey update (the update task shows changed, and Run install.sh shows skipping);
      • 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.yml and the data check, with the schema documented: contrib/ansible/playbooks/, contrib/ansible/check-data, and README "The data file". Tests in contrib_ansible_linux_test.go:
      • TestCheckDataBad: an unknown key, a wrong type, an older version, and more;
      • TestCheckDataPrintsNoValue, TestCheckDataUsage, TestCheckDataGood;
      • in ci.sh: broker: a data file with an unknown key fails, and installs nothing.
    • Release assets: .github/workflows/release.yml builds nodkey_VERSION_ansible.tar.gz with contrib/ansible/build.sh before SHA256SUMS. The attestation covers dist/*.tar.gz. DESIGN.md section 18, docs/releasing.md and T53 say how a host gets and checks it. Tested by TestAnsibleBuild and TestAnsibleBuildRefuses. The first release that has the file is the next one.
    • No host names, IPs or private repo names: examples use example-host, example-user and config-repo.

    Choices:

    • It is a plain role, not a collection (DESIGN.md section 18).
    • The role of release X installs only nodkey X, because it holds the install.sh and the unit of that tag.
    • The playbooks take -e nodkey_data_file=PATH, not -e @host.yml. With @, every key would become an Ansible variable and could override a pin.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions