Skip to content
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

Jump to bottom

Update guide to puppet module #23369

Merged
merged 4 commits into from
Nov 6, 2024
Merged

Update guide to puppet module #23369

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7620559
Update links in guide to puppet module
gillespi314 Oct 29, 2024
76e1862
Update puppet module guide
gillespi314 Oct 29, 2024
20c8bf1
updated sub-nav for "Setup experience"
mike-j-thomas Oct 29, 2024
a89309f
Address comments
gillespi314 Nov 5, 2024
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
10 changes: 5 additions & 5 deletions articles/puppet-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ Install [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm

### Step 2: configure Puppet to talk to Fleet using Heira

1. In Fleet, create an API-only user with the GitOps role. Instructions for creating an API-only user are [here](./fleetctl-CLI.md#create-an-api-only-user).
1. In Fleet, create an API-only user with the GitOps role. Instructions for creating an API-only user are [here](https://fleetdm.com/guides/fleetctl#create-api-only-user).
Copy link
Contributor Author

@gillespi314 gillespi314 Oct 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that a bunch of relative links in the docs were broken at some point. From what I can see, it looks like it was probably when various files were renamed and shuffled from docs/using-fleet into articles (aka guides).

I can see that there was some effort to define redirects on the website, but it doesn't appear to be capturing everything. My suspicion is that it works well enough with simple path changes (a -> b) but starts to break down when there are bigger changes. In this case, the relative link gets transformed to fleetdm.com/articles/fleetctl-cli#create-an-api-only-user but it none of the redirect rules are applied and the user ends up in 404-land.

In this PR, I swapped out all the relative links to markdown files for absolute links to the fleetdm.com site. I'm not sure how product/digital experience wants to resolve cases like this. Should we be using relative markdown links at all? If not, I think we ought to open a follow up ticket to fix relative markdown links and potentially add some kind of linter rule to watch out for them in the future.

If folks agree this should get a closer look, we can start by converting this comment into a new GitHub issue so it gets tracked appropriately.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gillespi314, thanks for jumping on this. We should only be using absolute links. I'll create a ticket for Digital Experience to check for stray relative links.


2. Get the API token for your new API-only user. Learn how [here](./fleetctl-CLI.md#get-the-api-token-of-an-api-only-user).
2. Get the API token for your new API-only user. Learn how [here](https://fleetdm.com/docs/rest-api/rest-api#log-in).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This heading doesn't seem to exist in any guides. The closest I could find for the topic was in the REST API docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it better to link to https://fleetdm.com/docs/rest-api/rest-api#retrieve-your-api-token instead?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gillespi314 As of 4.53.0, the API token is automatically shown in the CLI after creating an API-only user, so I think we can just mention that here instead of linking out anywhere. (See #16961)


3. Set `fleetdm::host` and `fleetdm::token` values to your Fleet server's URL and the API token respectively. Here's an example of the Hiera YAML:

Expand Down Expand Up @@ -99,11 +99,11 @@ Set the `ensure` parameter to `absent` to create teams that exclude specific pro

For more examples check out the `examples/` folder in Fleet's GitHub repository [here](https://github.com/fleetdm/fleet/tree/main/ee/tools/puppet/fleetdm/examples).

> Note that all teams created by Puppet inherit the bootstrap package, macOS Setup Assistant settings, and end user authentication settings from "No team." Learn more about these [here](./mdm-setup.md). In addition all teams automatically enable disk encryption. Learn more about disk encryption [here](./MDM-disk-encryption.md).
> Note that all teams created by Puppet inherit the bootstrap package, macOS Setup Assistant settings, and end user authentication settings from "No team." Learn more about these [here](https://fleetdm.com/guides/macos-setup-experience). In addition all teams automatically enable disk encryption. Learn more about disk encryption [here](https://fleetdm.com/guides/enforce-disk-encryption).

## Release host

If you set `await_device_configured` to `true` in your [macOS Setup Assistant settings](./mdm-setup.md#macos-setup-assistant), you can use the `fleetdm::release_device` function to release the host from the Setup Assistant.
If you set `enable_release_device_manually` to `true` in your [macOS setup experience](https://fleetdm.com/docs/rest-api/rest-api#configure-setup-experience), you can use the `fleetdm::release_device` function to release the host from the Setup Assistant.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The await_device_configured setting in Setup Assistant was effectively overruled by Fleet with the addition of enable_release_device_manually in 4.58, but it seems the docs weren't updated. I took my best shot, but I wasn't closely involved in the development so it would be good for someone from product to weigh in here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^^ @noahtalerman @marko-lisica

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. This is how the new behavior looks like. Fleet adds await_device_configured by default and won't let the user to change that.


Here's what your Puppet code, with error handling, will look like:

Expand Down Expand Up @@ -149,7 +149,7 @@ if $err != '' {
}
```

The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](./MDM-commands.md).
The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](https://fleetdm.com/guides/mdm-commands).

<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="noahtalerman">
Expand Down
5 changes: 3 additions & 2 deletions docs/REST API/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6105,7 +6105,7 @@ The summary can optionally be filtered by team ID.
}
```

### Turn on end user authentication for macOS setup
### Configure setup experience
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scope of this endpoint changed in 4.48 to encompass more than just end user authentication so the old heading is not accurate. I took a stab at updating it here, but it would be good for someone from product to weigh in and also to confirm that changing this here won't break other documentation links elsewhere.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're good. It doesn't look as though #turn-on-end-user-authentication-for-macos-setup is referenced in any other docs.


_Available in Fleet Premium_

Expand All @@ -6128,7 +6128,8 @@ _Available in Fleet Premium_
```json
{
"team_id": 1,
"enabled_end_user_authentication": true
"enable_end_user_authentication": true,
"enable_release_device_manually": true
}
```

Expand Down
Loading