From 499f20e720d3e4c4cb3176a0e2fa06412455d67e Mon Sep 17 00:00:00 2001 From: Ivan Porta Date: Wed, 9 Jul 2025 21:41:37 +0900 Subject: [PATCH 1/2] add warnings Signed-off-by: Ivan Porta --- ...-rotating-control-plane-tls-credentials.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md b/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md index b69f5519de..01442e6c88 100644 --- a/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md +++ b/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md @@ -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. + +{{< /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 @@ -418,6 +427,14 @@ 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 extremely important as it lets you keep the old trust anchor +valid alongside the new one, preventing any mTLS validation failures during +the rotation of the 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`, From fe8a1869281537ce451c7e54140ac8d4d36fbff6 Mon Sep 17 00:00:00 2001 From: Ivan Porta Date: Wed, 9 Jul 2025 21:48:00 +0900 Subject: [PATCH 2/2] update the second warning Signed-off-by: Ivan Porta --- ...automatically-rotating-control-plane-tls-credentials.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md b/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md index 01442e6c88..d600593b59 100644 --- a/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md +++ b/linkerd.io/content/2-edge/tasks/automatically-rotating-control-plane-tls-credentials.md @@ -429,9 +429,10 @@ anchor in the trust bundle until all the restarts have completed. {{< warning >}} -This task is extremely important as it lets you keep the old trust anchor -valid alongside the new one, preventing any mTLS validation failures during -the rotation of the trust anchor certificate. +This task is criticalas 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 >}}