Update device trust docs by flyinghermit · Pull Request #30821 · gravitational/teleport

flyinghermit · 2023-08-21T23:24:14Z

Updates device trust docs:

Most of the work in this PR includes shuffling existing content to various new pages so that contents align with day 1 and day 2 usage of device trust.

Base device trust page: Now explains basic concepts in detail. Contents are borrowed from outgoing "Set up Device Trust" page.
Getting started guide (previously "Set up Device Trust" page): updated to focus on day 1 usage of device trust.
Device Management: New page. Most of the contents borrowed from outgoing "Set up Device Trust" page. This page is focused on device management i.e. register device, enroll device, remove device, advanced config
Enforcing Device Trust: New page focused on device trust enforcement, including locking device. Most of the contents borrowed from outgoing "Set up Device Trust" page.
Auto enrollment: Page is deleted and the content is added to Device Management. After reading my current edits (and also partly from the feedback that it was not easy to find the auto enrollment doc), I felt like it would be better for readers to know about auto enrollment when they are already on the Device Management page. But lmk if this is a wrong idea and will put it back.
Jamf Integration: Updated to add reference to hosted Jamf plugin.

I also recommend to pull these changes and view them in local docs server to review if the links and docs flow is consumable when surfing Device Trust docs.

- remove auto enrollment page - update config.json

…sage

- content is borrowed and expanded from existing doc

codingllama · 2023-08-22T21:29:17Z

I'll take a closer look soon, but I just wanted to jump in and mention the recently-opened PRs #30865 and #30878, both of which might make things a bit simpler here.

- multiple grammar update - auto enrollment -> auto-enrollment - add signed prereqs in enforcing ddevice trust page

flyinghermit · 2023-08-22T21:42:26Z

PRs #30865 and #30878, both of which might make things a bit simpler here.

Nice! That's a great addition 🚀

Note to reviewer: Updated to reflect ~~I will be updating this PR to address changes added in~~ #30865 and #30878

- udpated getting started guide to use preset require-trusted-device role - minor grammar and code formating

flyinghermit · 2023-08-24T13:45:57Z

Friendly ping for review please!

ptgott · 2023-08-24T14:14:52Z

Hi @sshahcodes, to help me review this, would you mind explaining the problems this PR is solving? The summary in the description is helpful for understanding the changes at a high level, but I'm still not really sure why these changes are being made. Thanks!

flyinghermit · 2023-08-24T21:54:54Z

@ptgott sure, the main reason for the changes in this PR is to adjust existing contents focused on day 1 (for users approaching device trust for the first time) and day 2 (for detailed explanation of available configurations, advance use cases, learn about edge case, best practice etc) docs.

Currently, it's a bit mix of reference manual vs getting started all added to a single page without focus on reader persona. It was written when the feature was released first. Lots of defaults have been changed since then, including the new ones that's addressed in #30865 and #30878. Some of the prerequisite aren't even required anymore. The content was structured for general use case but most of it would not be necessary for a admin to quickly try Device Trust, for example, knowing advance use cases and setting up roles and permissions for secure operations is not necessary at all for day 1.

This was highlighted in this ticket improving Device Trust UX. Some of the issues mentioned there would have been addressed if the docs pointed to right direction, hence the changes in this PR. Most of the content is reused from "Set up device trust" page and added to the following pages.
Day 1: Base device trust page (explain concept), Getting started guide (new content)
Day 2: Device Management, Enforcing Device Trust, Jamf Integration

lsgunn-teleport

Overall, this looks good. I might suggest some languages tweaks in a follow-on PR but I think the re-org makes sense. My only question given the current structure is why you wouldn't just but device trust concepts in with the other Device trust topics?
Device trusts

concepts
get-started (how-to enroll a device - simple demo/eval/test/day 1 task)
manage devices (how-to topics)
enforce-trust (how-to topics)

flyinghermit · 2023-08-29T13:31:52Z

@lsgunn-teleport Thank you for the review.

I might suggest some languages tweaks in a follow-on PR

Sure, you can also create an issue ticket and tag me there, I can collaborate to improve Device Trust docs.

... device trust concepts in with the other Device trust topics?

Nothing concrete in particular but given docs re-org, I wanted to keep the new content minimum as there would be too many things to review. I also feel how-to topics needs proper time to find right balance on content, steps and context and so adding reference style docs, as it is in current PR was helpful in quickly grouping relevant commands together while the concepts are explained in single page. But yes, definitely something to revisit in future to add more how-to guides.

flyinghermit · 2023-08-29T13:32:26Z

Friendly ping for review please @zmb3 and @codingllama

codingllama · 2023-08-29T17:06:39Z

Apologies for the delay, taking a look now.

codingllama · 2023-08-29T16:58:07Z

+Categorically, we define these two requirements as Trusted Device management
+and Device Trust enforcement.


Could we either say "Trusted Device management/enforcement" or "Device Trust management/enforcement", so there's less difference between terms?

I hear you on this one. Between "Trusted Device management/enforcement" and "Device Trust management/enforcement", I prefer the first one as it is close to how device trust works(enrolling trusted devices, enforcing trusted device access).

Though the Device Trust Enforcement also aligns with the configuration semantics as the rule to enforce device is device_trust_mode: required and not trusted_device: required. That said, I am open to suggestions here.

Also tagging @zmb3 for more suggestions.

codingllama · 2023-08-29T18:08:04Z

+</Admonition>
+
+
+## Locking a device


Should this be in the management guide?

I think it belongs in enforcement but tagging @zmb3 for third opinion.

zmb3 · 2023-08-29T18:25:56Z

Lot's of great feedback here already, so I'll wait to review until this batch is addressed.

- adds resolved comments

flyinghermit · 2023-08-31T13:02:54Z

Friendly ping @codingllama @zmb3.
I have addressed most of the previous suggestions but few are waiting for discussion.

codingllama

Thanks for tackling this one.

public-teleport-github-review-bot · 2023-08-31T20:45:58Z

@sshahcodes See the table below for backport results.

Branch	Result
branch/v12	Failed
branch/v13	Create PR
branch/v14	Create PR

flyinghermit added 6 commits August 21, 2023 19:10

add dedicated page for device management and enforcement

c939730

- remove auto enrollment page - update config.json

update guide page to getting started, update copy to focus on day 1 u…

23738a0

…sage

update base device-trust doc with concepts.

dcac8da

- content is borrowed and expanded from existing doc

update copy and links

c1944a1

fix links, run linter write

ebc5f81

add reference to hosted Jamf plugin

b253a4c

flyinghermit requested review from codingllama and zmb3 August 22, 2023 18:27

flyinghermit marked this pull request as ready for review August 22, 2023 18:27

github-actions Bot added documentation size/md labels Aug 22, 2023

github-actions Bot requested review from lsgunn-teleport, ptgott, r0mant and xinding33 August 22, 2023 18:28

zmb3 reviewed Aug 22, 2023

View reviewed changes

resolve review comments:

1efbf53

- multiple grammar update - auto enrollment -> auto-enrollment - add signed prereqs in enforcing ddevice trust page

accomodate new preset roles and default auto-enrollment:

84877a3

- udpated getting started guide to use preset require-trusted-device role - minor grammar and code formating

fix typo udpate -> update

d5ac270

ptgott self-assigned this Aug 24, 2023

lsgunn-teleport approved these changes Aug 25, 2023

View reviewed changes

remove auto-enrollment default enabled admonition

5593d8d

flyinghermit requested a review from zmb3 August 29, 2023 13:32

flyinghermit added backport/branch/v13 labels Aug 29, 2023

codingllama reviewed Aug 29, 2023

View reviewed changes

flyinghermit added 5 commits August 29, 2023 20:08

address review suggestions:

b588320

- adds resolved comments

add clusterDefaults variable for generic code reference

deaa15e

add troubleshooting to guide and enforcment page

5ca85df

reference tctl edit role/access and add tsh relogin

74d0302

fix typo

508f1c3

codingllama approved these changes Aug 31, 2023

View reviewed changes

Comment thread docs/pages/access-controls/device-trust/device-management.mdx

public-teleport-github-review-bot Bot removed request for ptgott, r0mant and xinding33 August 31, 2023 17:17

zmb3 approved these changes Aug 31, 2023

View reviewed changes

Comment thread docs/config.json

Comment thread docs/pages/access-controls/device-trust/enforcing-device-trust.mdx Outdated

flyinghermit added 2 commits August 31, 2023 15:46

mention required role for auto-enrollment and minimum requirements

bffb276

add in command

25ab512

flyinghermit enabled auto-merge August 31, 2023 19:54

fix typo

b6eceed

flyinghermit added this pull request to the merge queue Aug 31, 2023

Merged via the queue into master with commit 699f1c2 Aug 31, 2023

flyinghermit deleted the sshah/update-dt-docs branch August 31, 2023 20:44

ptgott removed their assignment Aug 31, 2023

This was referenced Aug 31, 2023

[v14] Update device trust docs #31327

Merged

[v13] Update device trust docs #31328

Merged

flyinghermit added a commit that referenced this pull request Sep 5, 2023

Backport #30821 to branch/v12

cc4867b

flyinghermit mentioned this pull request Sep 5, 2023

[v12] Update device trust docs #31477

Closed

		Categorically, we define these two requirements as Trusted Device management
		and Device Trust enforcement.

Conversation

flyinghermit commented Aug 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Updates device trust docs:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codingllama commented Aug 22, 2023

Uh oh!

flyinghermit commented Aug 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

flyinghermit commented Aug 24, 2023

Uh oh!

ptgott commented Aug 24, 2023

Uh oh!

flyinghermit commented Aug 24, 2023

Uh oh!

lsgunn-teleport left a comment

Choose a reason for hiding this comment

Uh oh!

flyinghermit commented Aug 29, 2023

Uh oh!

flyinghermit commented Aug 29, 2023

Uh oh!

codingllama commented Aug 29, 2023

Uh oh!

Uh oh!

Uh oh!

codingllama Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

flyinghermit Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codingllama Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

flyinghermit Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

zmb3 commented Aug 29, 2023

Uh oh!

flyinghermit commented Aug 31, 2023

Uh oh!

codingllama left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

public-teleport-github-review-bot Bot commented Aug 31, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

flyinghermit commented Aug 21, 2023 •

edited

Loading

flyinghermit commented Aug 22, 2023 •

edited

Loading