NixOS: agent.yaml can be declared, not registered - #549
Draft
joshdrake wants to merge 1 commit into
Draft
Conversation
The NixOS instructions told readers not to manage agent.yaml with environment.etc, on the grounds that it "produces a read-only symlink into the Nix store, and the service refuses to start". The diagnosis was wrong and the advice ruled out the deployment NixOS users actually want. Neither the symlink nor the file mode was the problem. The unit gated on ConditionPathIsReadWrite=, which per systemd.unit(5) tests whether the underlying filesystem is mounted read-only, not whether the file is writable, and it resolves symlinks. NixOS remounts /nix/store read-only at boot, so the check landed there and skipped the unit. The agent itself reads a mode 0444 agent.yaml happily and never writes to it; everything it writes lives in /var/lib/step-agent. agent#1205 changes that gate to ConditionPathExists=, which is the question the unit meant to ask all along. So point readers at the declarative form instead, wired to the pre-registration flow that already documents where the team slug and CA fingerprint come from. Also refresh the troubleshooting callout for the new directive name, and say that older agents report the same check under the old one, so the message matches whichever version a reader has installed. Merge after agent#1205, which is what updates the step-agent.nix published to files.smallstep.com. Refs OFF-19. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkEcowtxSeqvb2pLWC3u5J
|
|
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
2 participants
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.
Refs OFF-19.
Merge after smallstep/agent#1205 — that PR is what updates the
step-agent.nixpublished tofiles.smallstep.com, which these instructions tell readers to download.Why
The NixOS section told readers not to manage
agent.yamlwithenvironment.etc, because "that produces a read-only symlink into the Nix store, and the service refuses to start." The diagnosis was wrong, and the advice ruled out the deployment NixOS users actually want — a customer raised exactly this while packaging the module for nixpkgs (NixOS/nixpkgs#555971).Neither the symlink nor the file mode was the problem. The unit gated on
ConditionPathIsReadWrite=, which persystemd.unit(5)tests whether the underlying filesystem is mounted read-only — not whether the file is writable — and it resolves symlinks. NixOS remounts/nix/storeread-only at boot, so the check landed there and skipped the unit. The agent itself reads a mode 0444agent.yamlwithout complaint and never writes to it; everything it writes lives in/var/lib/step-agent.agent#1205 changes that gate to
ConditionPathExists=, the question the unit meant to ask all along.Changes
platform/smallstep-agent.mdx— replace the prohibition with the declarative form, wired to the existing Pre-registration via API section, which is already where the team slug and agent CA fingerprint come from. The interactivestep-agent registerpath is unchanged and still documented first.platform/troubleshooting-agent.mdx— update the "unmet condition check" callout to the new directive name, and note that older agents report the same check under the old one, so the message matches whichever version a reader has installed.Checks
valerun against both files before and after (via the markdown parser —mdx2vastisn't installed locally): no new alerts. Anchor#pre-registration-via-apiresolves to the existing### Pre-registration via APIheading in the same file.🤖 Generated with Claude Code
https://claude.ai/code/session_01RkEcowtxSeqvb2pLWC3u5J