docs: update CA rotation docs #49468
Conversation
nklaassen
added
no-changelog
github-actions
bot
requested review from
mmcallister,
ptgott,
r0mant,
xinding33 and
zmb3
|
🤖 Vercel preview here: https://docs-f3a9rw882-goteleport.vercel.app/docs |
|
|
||
| CA rotations can be **manual** or **semi-automatic**. In manual mode, admins | ||
| must instruct the Teleport Auth Service to advance from one phase to the next. | ||
| Between phases, admins can prepare their infrastructure to adjust to each | ||
| change. In semi-automatic mode, the Teleport Auth Service cycles through each | ||
| phase automatically, with a grace period between each phase. | ||
|
|
||
| In 17.1.0+ `tctl auth rotate` (with no arguments) starts an interactive |
There was a problem hiding this comment.
note to self: update this with the actual version where #49171 merges
| @@ -267,22 +324,33 @@ $ curl https://example.teleport.sh/.well-known/open-id-configuration | jq '.jwks | |||
| Once you have chosen a CA to rotate and have planned to check or update the | |||
| infrastructure that relies on that CA, you are ready to begin a manual rotation. | |||
|
|
|||
| <Admonition type="tip"> | |||
| In 17.1.0+ `tctl auth rotate` (with no arguments) starts an interactive | |||
There was a problem hiding this comment.
note to self: update this with the actual version where #49171 merges
| [`host` CA](#host). | ||
| 1. `standby`: No rotation in progress. All operations have completed. | ||
| 1. `update_servers`: Any server components in the cluster that accept incoming | ||
| connections from clients should reload their identity and start serving |
There was a problem hiding this comment.
What does "should" mean here? Would the sentence make sense if we removed it, or are there some situation in which cluster components that accept incoming connections do not reload their identity etc.?
There was a problem hiding this comment.
Well, in some cases (OpenSSH servers, self-hosted databases), it's on the admin to issue a new cert and reload the identity, that's why I used "should"
| 1. `update_servers`: Any server components in the cluster that accept incoming | ||
| connections from clients should reload their identity and start serving | ||
| certificates issed by the new CA, but still accept certificates issued by the | ||
| original CA. |
There was a problem hiding this comment.
| original CA. | |
| original CA. | |
Otherwise, the paragraph break won't render.
There was a problem hiding this comment.
I'm not trying to put a paragraph break here, I just like putting each sentence on its own line when writing markdown, I find it makes it easier for editing full sentences and leads to cleaner diffs
|
|
||
| CA rotations can be **manual** or **semi-automatic**. In manual mode, admins | ||
| must instruct the Teleport Auth Service to advance from one phase to the next. | ||
| Between phases, admins can prepare their infrastructure to adjust to each | ||
| change. In semi-automatic mode, the Teleport Auth Service cycles through each | ||
| phase automatically, with a grace period between each phase. | ||
|
|
||
| In 17.1.0+ `tctl auth rotate` (with no arguments) starts an interactive |
There was a problem hiding this comment.
In this change, we mention tctl auth rotate after the manual and semi-automatic options. Would it make sense to structure the guide around the wizard instead, and leave the documentation of the arguments for our reference guides (i.e., this guide would be the fast path)? Otherwise, while the argumentless form of tctl auth rotate is a simplification, the documentation actually becomes a little more complex.
There was a problem hiding this comment.
I can see some benefits to pushing the interactive command, though I worry that relying only on arguments in the reference guides might leave too much as an exercise to the reader.
| <Admonition type="note"> | ||
| Any OpenSSH hosts must be issued new host certificates during the | ||
| `update_servers` phase of the `host` CA rotation. | ||
| </Admonition> | ||
|
|
||
| <Admonition type="note"> | ||
| If you are joining Teleport processes to a cluster via the Teleport Auth | ||
| Service, each Teleport process will need a CA pin to trust the Auth Service. | ||
| The CA pin will change after each `host` CA rotation. Make sure you use the | ||
| *new* CA pin when adding Teleport services after `host` CA rotation. | ||
| Service, each Teleport process needs a CA pin to trust the Auth Service. | ||
| Teleport Agents connecting to a Proxy Service address never need a CA pin, but | ||
| new Proxy Services should always use a CA pin when joining the cluster. | ||
| During the CA rotation, `tctl status` will report that there are 2 CA pins. | ||
| The CA pin configuration can accept a list including both pins. | ||
| After the rotation is complete, only the new CA pin will be reported. |
There was a problem hiding this comment.
I would work these Admonitions into the body text. Successive Admonitions look cluttered and difficult to read.
There was a problem hiding this comment.
made both of these normal paragraphs
|
🤖 Vercel preview here: https://docs-e5day2a2e-goteleport.vercel.app/docs |
This PR updates the CA rotation to mention the new interactive
tctl auth rotate(#49171), and edits a few sections that I found needed to be corrected or reworded for clarity.