MWI: Add Bound Keypair Joining admin and reference guide#56824
MWI: Add Bound Keypair Joining admin and reference guide#56824timothyb89 merged 5 commits intomasterfrom
Conversation
github-actions
bot
added
documentation
no-changelog
|
Amplify deployment status
|
This adds an admin and reference guide for bound keypair joining, intended to explain the core architecture of the join method, provide a few minimal configuration examples, and cover various long term maintenance tasks expected to be needed for bots using the `bound_keypair` join method, like rotating keypairs, recovering broken bots, and making other config changes.
timothyb89
force-pushed
the
timothyb89/bound-keypair-admin-guide
branch
from
40eb6f8 to
5e5fb91
Compare
ptgott
left a comment
ptgott
left a comment
There was a problem hiding this comment.
I would start by adding a description in the introductory section of what this guide is about. This will help users determine whether this guide is the one they should carry on reading. Otherwise, since there are so many topics in this guide, it'll be difficult for a user to determine this.
I also think adding a scope paragraph will help us determine if we should keep this as one guide. Part of me feels like we should take the following steps to split up the guide while keeping it in the same location of the docs:
- Create an overview page at
docs/pages/reference/machine-id/bound-keypair/bound-keypair.mdxthat includes the use cases and limitations sections of this guide, plus a list of guides in the Bound Keypair section. - Move the existing how-to guide to
docs/pages/reference/machine-id/bound-keypair/getting-started.mdx - Move the Concepts section into
docs/pages/reference/machine-id/bound-keypair/concepts.mdx
I'm not sure about the admin reference—would it make sense to move this to the final section of the how-to guide? That's where we typically include practical steps that don't fit into the main flow of the setup we want users to follow.
| Bound Keypair Joining is available in v18.1.0 and is intended to replace `token` | ||
| joining as the default recommended join method in Teleport v19.0.0. | ||
| </Admonition> | ||
|
|
There was a problem hiding this comment.
I would describe the scope of this guide here. This is especially important since the guide includes multiple purposes in a single document—it might be difficult for readers to determine whether this guide is right for them.
Also, move the Getting Started guide to the bound keypair reference section.
timothyb89
left a comment
timothyb89
left a comment
There was a problem hiding this comment.
I've split the guide into a dedicated Concepts page, moved the Getting Started guide into the reference section, and also split out the admin guide into an individual page.
I'm not sure about the admin reference—would it make sense to move this to the final section of the how-to guide? That's where we typically include practical steps that don't fit into the main flow of the setup we want users to follow.
I've ended up giving it a dedicated page - my feeling was that it felt a bit odd to have long-term reference material as part of the getting started guide? But if that's the established pattern and what users will expect I'm happy to move things around.
| - [Bound Keypair Joining Admin Guide](./admin-guide.mdx): Learn how to deploy | ||
| and maintain bots in production with Bound Keypair Joining | ||
|
|
||
| ## Token resource examples |
There was a problem hiding this comment.
This examples section seems a bit out of place here. Is there a section that would make more sense?
There was a problem hiding this comment.
ptgott
left a comment
ptgott
left a comment
There was a problem hiding this comment.
This seems like a good first iteration to me. Approved, though I think it'd be good to find a solution to the comment here: https://github.com/gravitational/teleport/pull/56824/files#r2224128538
public-teleport-github-review-bot
bot
removed request for
mmcallister and
r0mant
This removes the token examples from the bound keypair overview page and instead moves the key unique information (preregistered keys) into an alternative flow section in the bound keypair guide.
timothyb89
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
There was a problem hiding this comment.
The organization within the guide works for me, though we've been placing how-to guides within docs/pages/machine-workload-identity. Is there a location there that would work for this guide?
There was a problem hiding this comment.
You'd asked to have it moved into the new section here - #56824 (review). Should I leave it where it currently is, or do you still want it moved?
There was a problem hiding this comment.
I forgot about that, thanks—while keeping the Getting Started guide in References diverges from the categorization scheme, I suppose we can keep it there for now since:
- It keeps all of the Bounded Keypair guides together
- Eventually we want to organize the guides in the References section so that they're located alongside the features they describe
If we do want to move the Getting Started guide before we reorganize the References guides in general, we can do so easily.
|
@timothyb89 See the table below for backport results.
|
* MWI: Add Bound Keypair Joining admin and reference guide This adds an admin and reference guide for bound keypair joining, intended to explain the core architecture of the join method, provide a few minimal configuration examples, and cover various long term maintenance tasks expected to be needed for bots using the `bound_keypair` join method, like rotating keypairs, recovering broken bots, and making other config changes. * Split admin guide and concepts into separate pages Also, move the Getting Started guide to the bound keypair reference section. * Remove token examples and add preregistered key flow to guide This removes the token examples from the bound keypair overview page and instead moves the key unique information (preregistered keys) into an alternative flow section in the bound keypair guide. * Add missing redirect * Fix broken header links after reorganization
* MWI: Add documentation for bound keypair joining (#56604) * MWI: Add documentation for bound keypair joining This adds documentation for bound keypair joining, including a user-facing deployment guide, an admin guide (with architecture information), and the usual provision token details. * TODOs for deployment guide, add deployment guide to method list * Finish deployment guide and make small tweaks to other pages * Update tbot CLI and configuration reference * Fix docs lints * Add notes about new lock targets for bots * Bound keypair guide feedback Various bits of review feedback, and attempt to wordsmith on the introduction paragraphs. * Fix review feedback and missing references Adds some missing references and addresses review feedback. * Address review feedback, add missing detail Adds missing detail, especially around decoupled keypair from certs. * Further clarify what automatic recovery is * Consistently refer to "bot hosts" rather than nodes * Address more review feedback - Retitle the reference guide - Link to preregistered keys in the guide * Add guides section to reference page * Remove admin guide from this PR This removes the admin guide from this PR and replaces references to it with placeholders with commented TODOs. The admin guide will be reintroduced in a separate PR stacked onto this one. * Fix docs lint * Fix Machine ID -> Machine & Workload Identity naming * Update more Machine & Workload Identity references * MWI: Add Bound Keypair Joining admin and reference guide (#56824) * MWI: Add Bound Keypair Joining admin and reference guide This adds an admin and reference guide for bound keypair joining, intended to explain the core architecture of the join method, provide a few minimal configuration examples, and cover various long term maintenance tasks expected to be needed for bots using the `bound_keypair` join method, like rotating keypairs, recovering broken bots, and making other config changes. * Split admin guide and concepts into separate pages Also, move the Getting Started guide to the bound keypair reference section. * Remove token examples and add preregistered key flow to guide This removes the token examples from the bound keypair overview page and instead moves the key unique information (preregistered keys) into an alternative flow section in the bound keypair guide. * Add missing redirect * Fix broken header links after reorganization * MWI: Add note about bound keypair joining only supporting bots (#57589) * MWI: Add note about bound keypair only supporting bots Bound keypair joining only supports bots right now, so this adds a note about this limitation in the overview page and join method reference. * Tweak phrasing to better define what an "agent" is * Wording tweaks
3 participants
This adds an admin and reference guide for bound keypair joining, intended to explain the core architecture of the join method, provide a few minimal configuration examples, and cover various long term maintenance tasks expected to be needed for bots using the
bound_keypairjoin method, like rotating keypairs, recovering broken bots, and making other config changes.