MWI: Add documentation for bound keypair joining by timothyb89 · Pull Request #56604 · gravitational/teleport

timothyb89 · 2025-07-09T04:01:46Z

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.

Closes #55598

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.

github-actions · 2025-07-09T04:02:27Z

Amplify deployment status

Branch	Commit	Job ID	Status	Preview	Updated (UTC)
timothyb89/bound-keypair-docs	`7b32e94`	14	✅SUCCEED	timothyb89-bound-keypair-docs	2025-07-16 16:42:23

timothyb89 · 2025-07-09T04:04:42Z

Curious for thoughts on this guide in general, but also about where it fits in the docs hierarchy. I want to both document the architecture of this join method somewhere, and include admin / lifecycle details, and ended up combining the two and nesting them in the Machine ID Reference section. Not sure if that's the best place for it?

I think pending the wider docs refactor - this is in the perfect place and I think strikes a nice level of detail.

ptgott · 2025-07-10T12:49:12Z

+description: "How to install and configure Machine ID with Bound Keypair joining"
+---
+
+In this guide, you will install Machine ID's agent, `tbot`, on an arbitrary


While the title frames the guide around bound keypairs, the introduction doesn't mention this concept.

I would either:

Add one sentence in the introduction explaining what Bound Keypair joining is

Change the title to "Deploying Machine ID using Persistent Storage" or something similar.

+1 for the first option - we should explain what this join method is and when you should consider using it as early as we can.

I've tried to wordsmith things here to hopefully cover everything: it directly compares against other options and mentions recovery.

ptgott · 2025-07-10T13:05:44Z

+  use cases and deployment scenarios
+- Ensures failed bots can be recovered without client-side intervention in most
+  cases
+


I would be clearer about what readers would expect in this guide. The introduction frames it as a general-purpose docs page on bound keypair joining, but that puts it in conflict with the how-to guide. I would consider:

Splitting the architectural information into a separate guide with a more specific title and putting that in the Architecture section.

Retitling this page to be more specific, e.g., Bound Keypair Joining Reference.

Making sure each Bound Keypair Joining guide links to the other Bound Keypair Joining guides in the introduction.

I like option 2.

I've at least retitled the page and added a guides section to link to the main deployment guide. I'll admit it definitely doesn't fit cleanly into "just" being a reference page and is sort of a cursed hybrid of an architecture page, admin manual, and configuration reference.

I'm not opposed making additional separate pages, but I think (for example) a dedicated architecture page might be a bit light on content given the "Concepts" section as it exists now. Definitely happy to hear your thoughts on the best path forward!

I'd definitely be keen to avoid splitting this into a third page - retitling as a reference seems like a good enough compromise and avoids splitting this information across three different places which makes maintaining it as engineers and finding it as end-users harder.

zmb3 · 2025-07-10T22:10:25Z

+description: "How to install and configure Machine ID with Bound Keypair joining"
+---
+
+In this guide, you will install Machine ID's agent, `tbot`, on an arbitrary


+1 for the first option - we should explain what this join method is and when you should consider using it as early as we can.

zmb3 · 2025-07-10T22:13:05Z

+With Bound Keypair joining, instead of using a static token or relying solely on
+renewable certificates, Machine ID bots generate a unique keypair. Teleport is
+then configured to trust this public key for future joining attempts.


I would intro it a bit differently. Take it or leave it:

Bound keypair joining is a more secure and flexible alternative to static token joining.
Machine ID bots generate a unique keypair, registering the public key with Teleport
and keeping the private key in their own storage.

Later, when the bot attempts to join the cluster, ...

I've tried to iterate on this a bit and rewrote things a bit, the "more secure and flexible alternative" wound up getting promoted up into the intro paragraph

zmb3 · 2025-07-10T22:14:08Z

+  duplicated
+- Certificate generation counter checks to ensure regular bot certificates
+  cannot be usefully shared or duplicated
+- Configurable limits on how often - if at all - bots may be allowed to recover


Do we expect readers to know what it means to "recover" at this point in the guide, or do we need to elaborate?

I've added a reference to "automated recovery" in the introductory paragraph, hopefully that clarifies it enough?

zmb3 · 2025-07-10T22:18:26Z

+
+**This step is completed on your local machine.**
+
+In this guide, we'll demonstrate joining a bot using a registration secret: this


I would mention both approaches before we narrow down on one, just so the reader knows there's another option.

Maybe:

The initial joining operation can operate in two modes. The first is by using
a registration secret, which is similar to the first join process with the token
join method. Alternatively, initial joining can be performed with a public key.

In this guide, we will demonstrate joining using a registration secret.

I've added an explicit reference (and a link) in the admonition, hopefully it makes the existence of the alternative clear? Trying to balance clarity with the guide only actually showing how to accomplish a single mode.

(Maybe showing both paths in the guide will be more reasonable with a tctl helper - may update this further if so)

zmb3 · 2025-07-10T22:24:03Z

+---
+
+Bound Keypair is a new join method designed to provide the best features of
+[dynamic join methods][dynamic] join methods - like AWS, GCP, or Azure - but in


Should we call them delegated join methods for consistency with https://goteleport.com/docs/reference/join-methods/#secret-vs-delegated

Hmm, that's fair. It might be good to make sure the Machine ID Architecture page adopts that terminology eventually, but probably out of scope here. I've updated references to point to the join methods reference page which uses "delegated", rather than the Machine ID Architecture page which uses "dynamic".

zmb3 · 2025-07-10T22:24:48Z

+  use cases and deployment scenarios
+- Ensures failed bots can be recovered without client-side intervention in most
+  cases
+


I like option 2.

Various bits of review feedback, and attempt to wordsmith on the introduction paragraphs.

Adds some missing references and addresses review feedback.

Adds missing detail, especially around decoupled keypair from certs.

- Retitle the reference guide - Link to preregistered keys in the guide

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.

timothyb89 · 2025-07-15T22:12:36Z

Per a request from @ptgott, I've split the admin guide out into a separate PR stacked on top of this one: #56824

References and links to this guide were either commented out or replaced with a placeholder (just the root of the Machine ID reference section) and are restored in that PR. I'm happy to tweak the approach there if needed.

strideynet · 2025-07-16T09:27:35Z

  cluster)
 - a Windows desktop by the desktop's name
 - an [Access Request](access-requests/access-requests.mdx) by UUID
+- a bot instance ID (for Machine ID bots)


We should either say "Bot" Or "Machine & Workload Identity Bot" or "MWI Bot" - we're deprecating the use of the "Machine ID" phraseology.

Ah, good catch - I've updated a number of references in addition to this one. The guide itself is still named "Deploying Machine ID on..." but I'm wary of changing that phrasing given every other guide still follows the older naming scheme. I assume we'll update the terminology all at once when we're ready to do so?

backport-bot-workflows · 2025-07-16T19:11:42Z

@timothyb89 See the table below for backport results.

Branch	Result
branch/v18	Create PR

* 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 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

MWI: Add documentation for bound keypair joining

85089b5

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.

timothyb89 temporarily deployed to docs-amplify July 9, 2025 04:01 — with GitHub Actions Inactive

timothyb89 commented Jul 9, 2025

View reviewed changes

TODOs for deployment guide, add deployment guide to method list

5324dad

timothyb89 temporarily deployed to docs-amplify July 9, 2025 04:10 — with GitHub Actions Inactive

Finish deployment guide and make small tweaks to other pages

72667fd

timothyb89 temporarily deployed to docs-amplify July 10, 2025 02:18 — with GitHub Actions Inactive

Update tbot CLI and configuration reference

cf2d999

timothyb89 temporarily deployed to docs-amplify July 10, 2025 02:39 — with GitHub Actions Inactive

Fix docs lints

fc898f5

timothyb89 temporarily deployed to docs-amplify July 10, 2025 02:45 — with GitHub Actions Inactive

timothyb89 marked this pull request as ready for review July 10, 2025 02:45

github-actions bot added documentation no-changelog Indicates that a PR does not require a changelog entry size/lg labels Jul 10, 2025

github-actions bot requested review from mmcallister, ptgott, r0mant and zmb3 July 10, 2025 02:46

ptgott reviewed Jul 10, 2025

View reviewed changes

zmb3 reviewed Jul 10, 2025

View reviewed changes

timothyb89 added 4 commits July 10, 2025 18:46

Add notes about new lock targets for bots

e7c4237

Bound keypair guide feedback

c8ea87a

Various bits of review feedback, and attempt to wordsmith on the introduction paragraphs.

Fix review feedback and missing references

5e49293

Adds some missing references and addresses review feedback.

Address review feedback, add missing detail

cf57e4c

Adds missing detail, especially around decoupled keypair from certs.

timothyb89 temporarily deployed to docs-amplify July 11, 2025 00:57 — with GitHub Actions Inactive

Further clarify what automatic recovery is

6556cd0

timothyb89 temporarily deployed to docs-amplify July 11, 2025 01:05 — with GitHub Actions Inactive

Consistently refer to "bot hosts" rather than nodes

e723101

Address more review feedback

af9941b

- Retitle the reference guide - Link to preregistered keys in the guide

timothyb89 temporarily deployed to docs-amplify July 11, 2025 01:25 — with GitHub Actions Inactive

Add guides section to reference page

c87b4ad

timothyb89 temporarily deployed to docs-amplify July 11, 2025 01:40 — with GitHub Actions Inactive

timothyb89 requested review from ptgott and zmb3 July 15, 2025 01:47

Remove admin guide from this PR

8b80c8a

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.

timothyb89 temporarily deployed to docs-amplify July 15, 2025 22:00 — with GitHub Actions Inactive

Fix docs lint

1a086d2

timothyb89 temporarily deployed to docs-amplify July 15, 2025 22:04 — with GitHub Actions Inactive

timothyb89 mentioned this pull request Jul 15, 2025

[v18] Bound Keypair Joining Backport #56746

Merged

strideynet approved these changes Jul 16, 2025

View reviewed changes

ptgott approved these changes Jul 16, 2025

View reviewed changes

public-teleport-github-review-bot bot removed request for mmcallister and r0mant July 16, 2025 15:19

timothyb89 added the backport/branch/v18 label Jul 16, 2025

Fix Machine ID -> Machine & Workload Identity naming

a9acbbb

timothyb89 temporarily deployed to docs-amplify July 16, 2025 16:25 — with GitHub Actions Inactive

Update more Machine & Workload Identity references

7b32e94

timothyb89 temporarily deployed to docs-amplify July 16, 2025 16:29 — with GitHub Actions Inactive

timothyb89 added this pull request to the merge queue Jul 16, 2025

Merged via the queue into master with commit 3d47efd Jul 16, 2025
41 checks passed

timothyb89 deleted the timothyb89/bound-keypair-docs branch July 16, 2025 19:10

timothyb89 mentioned this pull request Jul 19, 2025

[v18] MWI: Add documentation for bound keypair joining #56966

Merged

timothyb89 mentioned this pull request Sep 12, 2025

[v17] Bound Keypair documentation #59091

Merged


		This step is completed on your local machine.

		In this guide, we'll demonstrate joining a bot using a registration secret: this

Conversation

timothyb89 commented Jul 9, 2025 • edited by zmb3 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timothyb89 Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

timothyb89 commented Jul 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

backport-bot-workflows bot commented Jul 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

timothyb89 commented Jul 9, 2025 •

edited by zmb3

Loading

github-actions bot commented Jul 9, 2025 •

edited

Loading

timothyb89 Jul 11, 2025 •

edited

Loading