Skip to content

NixOS: agent.yaml can be declared, not registered #549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joshdrake wants to merge 1 commit into
base: main
Choose a base branch
from
+21 −4
Draft

NixOS: agent.yaml can be declared, not registered #549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions platform/smallstep-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,9 +337,24 @@ so a host with no <code>/dev/tpmrm0</code> cannot enroll yet.
```

Registration writes `agent.yaml` into `/etc/step-agent`,
which systemd creates and keeps writable through `ConfigurationDirectory=`.
Do not manage `agent.yaml` with `environment.etc`:
that produces a read-only symlink into the Nix store, and the service refuses to start.
which systemd creates through `ConfigurationDirectory=`.

You can declare `agent.yaml` instead of registering interactively,
which is what makes a hands-off NixOS deployment possible.
Follow [Pre-registration via API](#pre-registration-via-api) to add and approve your devices
and to find your team slug and agent CA fingerprint, then declare the file and skip this step:

```nix
environment.etc."step-agent/agent.yaml".text = ''
team: "[team name]"
fingerprint: "[agents CA fingerprint]"
'';
```

The agent only ever reads this file.
Everything it writes lives in `/var/lib/step-agent`,
so serving `agent.yaml` from the Nix store is fine.
Every host in a fleet gets the same two values; nothing in it is per-device.

5. Check that it was installed correctly:

Expand Down
4 changes: 3 additions & 1 deletion platform/troubleshooting-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -602,8 +602,10 @@ as shown in [the NixOS install instructions](./smallstep-agent.mdx#nixos).
If the agent won't start, check for this message in the logs:
```
step-agent.service was skipped because of an unmet condition check
(ConditionPathIsReadWrite=/etc/step-agent/agent.yaml)
(ConditionPathExists=/etc/step-agent/agent.yaml)
```
Older agents report the same check as `ConditionPathIsReadWrite=`.

This may indicate the device needs to be registered and approved. See [Registering and Approving Endpoints](./smallstep-agent.mdx#registering-and-approving-endpoints).
</Alert>

Expand Down
Loading