Repository navigation
Bunch of docs changes to clarify Fleet enrollment - #555
Merged
Merged
Conversation
…path Hosts that Fleet syncs to Smallstep with the osquery extension already exist in inventory. Running `step-agent register` on them creates a conflicting device entry and fails with `unprocessable entity`. Say so in the Fleet tutorial (Linux and Windows), add the symptom to the troubleshooting guide, and reframe self-registration and API pre-registration in the agent guide and enrollment guide as the paths for devices Smallstep can't sync from an MDM. Also replace the Linux approval pointer in the Fleet tutorial: devices synced from Fleet need admin approval by default, and auto-approval is set through the Device Enrollment Policy API, not by adding the device via API. Fixes EFF-334. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK
The API docs site keys operations by PascalCase operationId (PutDeviceEnrollmentPolicy) and the 2026-05-01 version is current. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK
…al curl - Enrollment guide: add an osquery-based enrollment section for Fleet, and move the device API examples to the 2026-05-01 API version. - Fleet tutorial: describe Linux enrollment as ACME Device Attestation with the TPM, and show the curl flow for adding Fleet to autoApproveSources via the Device Enrollment Policy API, since the console doesn't expose it. - Agent guide and troubleshooting: tighten the wording around pre-registration and the duplicate-registration symptom. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK
tashian
changed the title
tashian
enabled auto-merge
September 8, 2026 18:30
dopey
reviewed
Sep 24, 2026
The Smallstep osquery extension is required for Fleet enrollment on macOS too, not only Linux and Windows. Describe what the extension reports per platform. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
hslatman
previously approved these changes
Oct 7, 2026
|
|
||
| When the agent starts, it attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data you just synced. By default, devices synced from Fleet need admin approval: if the host shows as `pending` in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. | ||
|
|
||
| To approve Fleet-synced devices automatically, add `Fleet` to `autoApproveSources` in your team's device enrollment policy. This setting isn't exposed in the Smallstep console. Use the [Device Enrollment Policy API](https://gateway.smallstep.com/v2026-05-01/operations/PutDeviceEnrollmentPolicy) with an [API token](https://smallstep.com/app/?next=/settings/api/tokens/add) that has the `get-device-enrollment-policy` and `put-device-enrollment-policy` scopes. The `PUT` replaces the whole policy, so fetch the current policy first and resubmit it with `Fleet` added to `autoApproveSources`: |
Member
There was a problem hiding this comment.
May be good to add UI for this in the console.
| systemctl enable --now step-agent | ||
| ``` | ||
|
|
||
| When the agent starts, it attests with the endpoint's TPM. Smallstep matches the attestation to the inventory data you just synced. By default, devices synced from Fleet need admin approval: if the host shows as `pending` in the [Smallstep console](https://smallstep.com/app/?next=/devices), approve it there. |
Member
There was a problem hiding this comment.
It looks like auto-approve being off is the case, but I'm curious if this was changed recently? I don't remember adding the MDM using the API myself.
Member
There was a problem hiding this comment.
It looks like we actually have a fallback with defaults, but that currently doesn't include Fleet atm.
I'll open a PR with that change. After that gets merged, one would not have to call the API anymore, unless they need customization.
Member
There was a problem hiding this comment.
My thought about the fallback seems to be wrong; it's a different knob.
Still don't remember having had to use the API myself to add Fleet to auto-approve, though.
hslatman
approved these changes
Oct 12, 2026
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
3 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.
Describe your changes:
Follow-up to EFF-334.
Fleet tutorial (
tutorials/connect-fleet-dm-to-smallstep.mdx)Enrollment guide (
platform/enrollment-guide.mdx)Agent guide (
platform/smallstep-agent.mdx)Troubleshooting guide (
platform/troubleshooting-agent.mdx)unprocessable entity/ duplicate-registration prompt on a device that already exists in inventory, with the fix and cleanup steps.Related links/other PRs/issues:
🤖 Generated with Claude Code
https://claude.ai/code/session_017MzPzeUonmnLSsg2KvYgAK