Update guide to puppet module #23369

gillespi314 · 2024-10-29T21:00:50Z

Related to #21807

gillespi314 · 2024-10-29T21:21:37Z

articles/puppet-module.md


-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).


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

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

@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)

gillespi314 · 2024-10-29T21:30:55Z

docs/REST API/rest-api.md

@@ -6105,7 +6105,7 @@ The summary can optionally be filtered by team ID.
 }
 ```

-### Turn on end user authentication for macOS setup
+### Configure setup experience


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.

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.

gillespi314 · 2024-10-29T21:31:09Z

articles/puppet-module.md


 ## 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. 


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.

^^ @noahtalerman @marko-lisica

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.

gillespi314 · 2024-10-29T21:51:29Z

articles/puppet-module.md

@@ -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).


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.

@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.

Updated "Turn on end user authentication for macOS setup" in the sub-nav <ul> to "Configure setup experience."

mike-j-thomas

Aside from the technical changes that I can't comment on, the rest looks good. Thanks, @gillespi314

mike-j-thomas · 2024-10-29T23:28:02Z

articles/puppet-module.md

@@ -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).


@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.

mike-j-thomas · 2024-10-29T23:30:46Z

articles/puppet-module.md


-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).


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

mike-j-thomas · 2024-10-29T23:38:42Z

docs/REST API/rest-api.md

@@ -6105,7 +6105,7 @@ The summary can optionally be filtered by team ID.
 }
 ```

-### Turn on end user authentication for macOS setup
+### Configure setup experience


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.

mike-j-thomas · 2024-10-29T23:39:14Z

docs/REST API/rest-api.md

@@ -5736,7 +5736,7 @@ Get aggregate status counts of profiles for to macOS and Windows hosts that are
 - [Delete a bootstrap package](#delete-a-bootstrap-package)
 - [Download a bootstrap package](#download-a-bootstrap-package)
 - [Get a summary of bootstrap package status](#get-a-summary-of-bootstrap-package-status)
- [Turn on end user authentication for macOS setup](#turn-on-end-user-authentication-for-macos-setup)
+- [Configure setup experience](#configure-setup-experience)


I updated the sub-nav to reflect your heading change.

mike-j-thomas · 2024-10-30T23:17:49Z

@gillespi314, we just ran a test on the website for bad links. This puppet module guide was all that came up. Thanks again for flagging.

rachaelshaw

(see https://github.com/fleetdm/fleet/pull/23369/files#r1826241294 - accidentally left as a regular comment and not a review comment.)

Update links in guide to puppet module

7620559

gillespi314 temporarily deployed to Docker Hub October 29, 2024 21:00 — with GitHub Actions Inactive

Update puppet module guide

76e1862

gillespi314 temporarily deployed to Docker Hub October 29, 2024 21:19 — with GitHub Actions Inactive

gillespi314 marked this pull request as ready for review October 29, 2024 21:53

gillespi314 requested a review from rachaelshaw as a code owner October 29, 2024 21:53

gillespi314 commented Oct 29, 2024

View reviewed changes

gillespi314 marked this pull request as draft October 29, 2024 21:54

updated sub-nav for "Setup experience"

20c8bf1

Updated "Turn on end user authentication for macOS setup" in the sub-nav <ul> to "Configure setup experience."

mike-j-thomas temporarily deployed to Docker Hub October 29, 2024 23:37 — with GitHub Actions Inactive

mike-j-thomas reviewed Oct 29, 2024

View reviewed changes

rachaelshaw requested changes Nov 1, 2024

View reviewed changes

Address comments

a89309f

gillespi314 temporarily deployed to Docker Hub November 5, 2024 15:58 — with GitHub Actions Inactive

gillespi314 marked this pull request as ready for review November 5, 2024 15:58

fleet-release requested a review from zayhanlon November 5, 2024 15:58

zayhanlon approved these changes Nov 5, 2024

View reviewed changes

gillespi314 requested a review from rachaelshaw November 5, 2024 16:22

rachaelshaw approved these changes Nov 6, 2024

View reviewed changes

gillespi314 merged commit 3ea68ae into main Nov 6, 2024
5 checks passed

gillespi314 deleted the puppet-module-guide branch November 6, 2024 22:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update guide to puppet module #23369

Update guide to puppet module #23369

gillespi314 commented Oct 29, 2024

gillespi314 Oct 29, 2024

mike-j-thomas Oct 29, 2024

rachaelshaw Nov 1, 2024

gillespi314 Oct 29, 2024

mike-j-thomas Oct 29, 2024

gillespi314 Oct 29, 2024

rachaelshaw Nov 1, 2024

marko-lisica Nov 4, 2024

gillespi314 Oct 29, 2024 •

edited

Loading

mike-j-thomas Oct 29, 2024

mike-j-thomas left a comment

mike-j-thomas Oct 29, 2024

mike-j-thomas Oct 29, 2024

mike-j-thomas Oct 29, 2024

mike-j-thomas Oct 29, 2024

mike-j-thomas commented Oct 30, 2024

rachaelshaw left a comment


		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).

Update guide to puppet module #23369

Update guide to puppet module #23369

Conversation

gillespi314 commented Oct 29, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gillespi314 Oct 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mike-j-thomas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mike-j-thomas commented Oct 30, 2024

rachaelshaw left a comment

Choose a reason for hiding this comment

gillespi314 Oct 29, 2024 •

edited

Loading