Skip to content

Highlight the importance of the Bundle and the need to restart both CP and DP #1990

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+20 −2
Open

Highlight the importance of the Bundle and the need to restart both CP and DP #1990

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
499f20e
add warnings
GTRekter Jul 9, 2025
fe8a186
update the second warning
GTRekter Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions ...io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,17 @@ primer][mtls-concepts-primer].

{{< /note >}}

While Linkerd automatically rotates the workload certificates, it cannot
automatically rotate the identity issuer certificate or the trust anchor.
{{< warning >}}

Linkerd automatically rotates workload certificates, but it does **not**
rotate the identity issuer certificate or the trust anchor. You can use
third-party tools like cert-manager to automate rotation of those
certificates. However, for critical certificates—such as the
trust anchor, you must manually restart the control-plane components
and all data-plane proxies so they pick up the new trust anchor.
Comment on lines +26 to +31
Copy link
Member

@kflynn kflynn Jul 26, 2025

Choose a reason for hiding this comment

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

Suggested change
Linkerd automatically rotates workload certificates, but it does **not**
rotate the identity issuer certificate or the trust anchor. You can use
third-party tools like cert-manager to automate rotation of those
certificates. However, for critical certificates—such as the
trust anchor, you must manually restart the control-plane components
and all data-plane proxies so they pick up the new trust anchor.
Linkerd automatically rotates workload certificates, but it **cannot**
automatically rotate the identity issuer certificate or the trust anchor.
Third-party tools like cert-manager can automate rotation of those
certificates for you, but **read this documentation carefully** to understand
when you need to restart Linkerd components in order to pick up the new
certificates.


{{< /warning >}}

Linkerd's out-of-the-box installations generate static self-signed
certificates with a validity of one year but require manual rotation by the
user to prevent expiry. While this setup is convenient for quick start
Expand Down Expand Up @@ -418,6 +427,15 @@ the data plane (the proxies) need to be restarted. Since that can't happen
instaneously, we need to have both the old trust anchor and the new trust
anchor in the trust bundle until all the restarts have completed.

{{< warning >}}

This task is criticalas it ensures the old trust anchor remains valid alongside
Copy link
Member

@kflynn kflynn Jul 26, 2025

Choose a reason for hiding this comment

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

Suggested change
This task is criticalas it ensures the old trust anchor remains valid alongside
This task is critical, since it ensures the old trust anchor remains valid alongside

the new one, preventing mTLS validation failures during rotation. After
each rotation, you must also manually update the `linkerd-previous-anchor`
secret with the former trust anchor certificate.

{{< /warning >}}

trust-manager can do this, but it needs a specific source for _each_
certificate in the bundle. So we'll start by copying the trust anchor from the
`linkerd-trust-anchor` Secret into a second Secret, `linkerd-previous-anchor`,
Expand Down