Skip to content

[docs] database CA migration and rotation guides#38137

Merged
GavinFrazar merged 1 commit intomasterfrom
gavinfrazar/db-ca-split-migration-docs
Feb 21, 2024
Merged

[docs] database CA migration and rotation guides#38137
GavinFrazar merged 1 commit intomasterfrom
gavinfrazar/db-ca-split-migration-docs

Conversation

@GavinFrazar
Copy link
Copy Markdown
Contributor

@GavinFrazar GavinFrazar commented Feb 13, 2024 •
edited
Loading

This docs-only PR adds guides for Teleport's database CAs (db and db_client).
The guides explain the historical context of why these CAs were added, how they were added via a migration that cloned their predecessor CA (if upgrading from an older version), and how to handle "completing" those migrations by rotating CAs.

Additionally, I added a guide specific to database CA rotation.
The existing CA rotation guide was really too focused on host CA rotation to adequately explain database CA rotation.
I think at some point we might add other CA-type-specific rotation guides, but that is out of scope for this PR.

Relevant related PR:

For reviewers ( @greedy52 @ptgott ) I wasn't too sure about which section to put these guides under.
I put them in the operations guides, because that's where we have other migration guides and the other CA rotation guide.

Let me know if you think these would be better elsewhere, like in the database-access section somewhere.

@GavinFrazar GavinFrazar requested a review from greedy52 February 13, 2024 07:45
@GavinFrazar GavinFrazar changed the title Database CA migration and rotation guides [docs] database CA migration and rotation guides Feb 13, 2024
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 13, 2024

The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with changelog: followed by the changelog entries for the PR.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 13, 2024

The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with changelog: followed by the changelog entries for the PR.

@GavinFrazar GavinFrazar added database-access Database access related issues and PRs no-changelog Indicates that a PR does not require a changelog entry labels Feb 13, 2024
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 13, 2024

🤖 Vercel preview here: https://docs-ez888o013-goteleport.vercel.app/docs/ver/preview

greedy52
greedy52 reviewed Feb 13, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@greedy52 greedy52 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for writing these guides! I think the locations are good but Paul is the better person for this.

Should we link the DB CA rotation guide in tctl auth sign once it's alive?

Comment thread docs/pages/management/operations/db-ca-rotation.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-migrations.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-rotation.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-rotation.mdx Outdated
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 13, 2024

🤖 Vercel preview here: https://docs-ke21ybs9q-goteleport.vercel.app/docs/ver/preview

ptgott
ptgott reviewed Feb 14, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@ptgott ptgott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In terms of location, I think the main consideration is which search terms a user would use to find the page.

If we think users will search for "CA Rotation", and database-specific CA rotation is something they find out about while reading the docs, we could make "CA Rotation" a subsection of "Manage your Cluster" (rather than "Manage your Cluster" > "Operations"), then put all of our CA rotation content in that subsection so this guide is more discoverable.

If users are searching for database-specific CA rotation information, I think the current approach is fine.

In general, one goal this quarter is to document all CA rotation steps, so we can decouple the task of organizing these docs from the one of writing the docs.

@ptgott ptgott mentioned this pull request Feb 14, 2024
Closed
ptgott
ptgott reviewed Feb 14, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@ptgott ptgott left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll leave a review for the "Database CA Migrations" page later this week

Comment thread docs/pages/management/operations/db-ca-rotation.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-rotation.mdx Outdated
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 16, 2024

🤖 Vercel preview here: https://docs-nsjww84mb-goteleport.vercel.app/docs/ver/preview

ptgott
ptgott approved these changes Feb 16, 2024
View reviewed changes
Comment thread docs/pages/management/operations/db-ca-migrations.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-migrations.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-migrations.mdx Outdated
Comment thread docs/pages/management/operations/db-ca-migrations.mdx Outdated
@public-teleport-github-review-bot public-teleport-github-review-bot Bot removed the request for review from xinding33 February 16, 2024 20:08
@GavinFrazar GavinFrazar force-pushed the gavinfrazar/db-ca-split-migration-docs branch from 3fc78de to d161870 Compare February 21, 2024 00:20
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 21, 2024

🤖 Vercel preview here: https://docs-h8xjx5rxe-goteleport.vercel.app/docs/ver/preview

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 21, 2024

🤖 Vercel preview here: https://docs-apxr4s06s-goteleport.vercel.app/docs/ver/preview

@GavinFrazar GavinFrazar force-pushed the gavinfrazar/db-ca-split-migration-docs branch from d161870 to 24e295f Compare February 21, 2024 01:34
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 21, 2024

🤖 Vercel preview here: https://docs-6ynft1n67-goteleport.vercel.app/docs/ver/preview

@GavinFrazar
add DB CA migration and rotation guides
7386539 
* add nav slugs for DB CA migration and rotation guides
* add DB CA guides
* use --phase last in CA rotation guide example commands, so they're less tedious to
  edit
* link to the database CA rotation guide for db and db_client CA rotation
* deprecate spec.ca_cert in db reference
* recommend parallel database ca rotation
* explain reconfig post rotation to fix db vuln
* update cspell to ignore -noout
@GavinFrazar GavinFrazar force-pushed the gavinfrazar/db-ca-split-migration-docs branch from 24e295f to 7386539 Compare February 21, 2024 01:44
@GavinFrazar GavinFrazar added this pull request to the merge queue Feb 21, 2024
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 21, 2024

🤖 Vercel preview here: https://docs-gvusibrd5-goteleport.vercel.app/docs/ver/preview

Merged via the queue into master with commit 7cec562 Feb 21, 2024
@GavinFrazar GavinFrazar deleted the gavinfrazar/db-ca-split-migration-docs branch February 21, 2024 02:01
@public-teleport-github-review-bot
Copy link
Copy Markdown

public-teleport-github-review-bot Bot commented Feb 21, 2024

@GavinFrazar See the table below for backport results.

Branch Result
branch/v13 Failed
branch/v14 Failed
branch/v15 Failed

GavinFrazar added a commit that referenced this pull request Feb 21, 2024
@GavinFrazar
backport #38137 to branch/v15
29266f4
@GavinFrazar GavinFrazar mentioned this pull request Feb 21, 2024
Merged
GavinFrazar added a commit that referenced this pull request Feb 21, 2024
@GavinFrazar
backport #38137 to branch/v14
9632937
@GavinFrazar GavinFrazar mentioned this pull request Feb 21, 2024
Merged
@GavinFrazar GavinFrazar mentioned this pull request Feb 21, 2024
Merged
github-merge-queue Bot pushed a commit that referenced this pull request Feb 22, 2024
@GavinFrazar
backport #38137 to branch/v15 (#38474)
f8441b2
github-merge-queue Bot pushed a commit that referenced this pull request Feb 24, 2024
@GavinFrazar
[v14] [docs] database CA migration and rotation guides (#38476)
b1af40e 
* backport #37606 to branch/v14.

* backport #38137 to branch/v14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ptgott ptgott ptgott approved these changes

@greedy52 greedy52 greedy52 approved these changes

Assignees

No one assigned

Labels

database-access Database access related issues and PRs documentation no-changelog Indicates that a PR does not require a changelog entry

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@GavinFrazar @greedy52 @ptgott