Workload ID: Restructure docs to be more value-first #47637
Conversation
|
🤖 Vercel preview here: https://docs-jmikoxn0k-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-5gce73z6h-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-c1fsy323m-goteleport.vercel.app/docs/ver/preview |
|
🤖 Vercel preview here: https://docs-hplr0qoj9-goteleport.vercel.app/docs/ver/preview |
github-actions
bot
requested review from
mmcallister,
ptgott,
r0mant,
xinding33 and
zmb3
| There's a whole host of benefits to adopting Teleport Workload Identity, but | ||
| here's some of the key ones: | ||
|
|
||
| - Eliminate the use of long-lived shared secrets within your infrastructure, and | ||
| reduce the risk of exfiltration and time spent by engineers creating and | ||
| rotating these secrets. | ||
| - Establish an out of the box universal form of identity for your workloads, | ||
| enabling your engineers to get on with building new services without needing | ||
| to think about how they'll authenticate. | ||
| - Converge on a first-class form of identity for your workloads, simplifying | ||
| infrastructure by reducing the number of different ways workloads authenticate. |
There was a problem hiding this comment.
I would shorten this introductory section by combining the list of benefits with the list of use cases (and choosing three bullets total). That way, we can move past the generalities more quickly and get to the substantive details about how Workload Identity works and what it means in Teleport.
| SPIFFE sets out: | ||
|
|
||
| - A format for uniquely specifying an identity, the SPIFFE ID. | ||
| - Standards for encoding the SPIFFE ID into verifiable documents, the SVID. |
There was a problem hiding this comment.
What does "the SVID" modify here? Is it a rephrasing of "standards"?
| - Processes that workloads should use to validate a received SVID. | ||
| - A set of APIs that workloads can use to request SVIDS, the Workload API. | ||
|
|
||
| The open nature and popularity of SPIFFE make it a great choice as a foundation |
There was a problem hiding this comment.
Is there a way to use a more objective-sounding word than "great" here?
Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
strideynet
added
the
no-changelog
|
🤖 Vercel preview here: https://docs-1zflfb9ky-goteleport.vercel.app/docs/ver/preview |
Since we don't have a general landing page for Workload ID on the main marketing site, I figured it made some sense to try and make the Workload Identity introduction on the docs focus a little more on the potential use-cases and value - rather than diving straight into the technical deep-end.