Skip to content

Agent Mesh

docs: a node can refresh until the key that signed it is retired

Tomas Tormof914204a3014
diff --git a/site/content/docs/concepts/boundaries.md b/site/content/docs/concepts/boundaries.md
index 677b6ad4..e35e084c 100644
--- a/site/content/docs/concepts/boundaries.md
+++ b/site/content/docs/concepts/boundaries.md
@@ -95,9 +95,12 @@ Both results can be verified offline with the control plane's public key.
A credential lasts 24 hours by default and is renewed in the background.
Short lifetimes make revocation work without a central check on every
request. A stolen credential is useful for at most its remaining lifetime. A
-banned node cannot renew. A node that has been offline for longer than the
-signing key's grace period has to come back through enrollment instead of
-reappearing without notice. The lifetime, the session length, the rotation
+banned node cannot renew. Under automatic rotation, the control plane
+retires each signing key one grace period after the next rotation. A node
+that was offline past the retirement of the key that signed its credential
+has to come back through enrollment. So the node cannot reappear without
+notice. The one exception is a node that an administrator opted in to
+autonomous recovery. The lifetime, the session length, the rotation
interval and the grace period are all control plane flags that the operator
sets.
diff --git a/site/content/docs/concepts/identity.md b/site/content/docs/concepts/identity.md
index a13fb837..d5830af8 100644
--- a/site/content/docs/concepts/identity.md
+++ b/site/content/docs/concepts/identity.md
@@ -232,10 +232,13 @@ already trust. The first key comes from enrollment, and each later key is
vouched for by the key it replaces.
Nobody can verify a credential signed by a retired key, including the
-control plane. A node that was offline for a whole grace period therefore
-cannot refresh. This is intentional. The grace period is the deadline after
-which a machine that went quiet cannot come back unnoticed. How it comes back
-depends on how it enrolled:
+control plane. Under automatic rotation, the control plane retires the key
+that signed a credential one grace period after the next rotation. With the
+defaults, the retirement comes at most 25 hours after the credential was
+issued. A node that was offline past that point therefore cannot refresh.
+This is intentional. The retirement is the deadline after which a machine
+that went quiet cannot come back unnoticed. How it comes back depends on how
+it enrolled:
- An OIDC node with a refresh token re-enrolls on its own.
- A bootstrap node needs an operator to mint a new token and run
diff --git a/site/content/docs/guides/headless-enrollment.md b/site/content/docs/guides/headless-enrollment.md
index be858390..63fe978a 100644
--- a/site/content/docs/guides/headless-enrollment.md
+++ b/site/content/docs/guides/headless-enrollment.md
@@ -196,19 +196,19 @@ A node or router enrolled with a platform token (`--jwt-path`,
`TokenRefreshRequest.jwt` on every `POST /refresh`. As long as the token's
`iss|sub` matches the enrolled record, the control plane re-attests the member
in place, updates its stored claims and extends its session
-(`--workload-session-ttl`, `48h` by default) without re-enrolling. If the
-member was offline longer than the session or key grace period, its renewal
-loop automatically re-enrolls with a fresh platform token under the same peer
-ID.
+(`--workload-session-ttl`, `48h` by default) without re-enrolling. A member
+can stay offline past the retirement of the key that signed its credential.
+Its renewal loop then re-enrolls with a fresh platform token under the same
+peer ID.
A node enrolled with a bootstrap token has no login or platform token source
-to fall back on. Its credential is refreshed automatically while it runs. But if the node is off
-for longer than the control plane's key grace period (`--key-grace-period`,
-one hour by default), it comes back with a credential signed by a retired
-key, and `/refresh` refuses it. An SDK member in the same position enrolls
-again on start when its `enroll` call is given a token, and otherwise
-fails with `CredentialRetiredError` naming the state directory. There are
-three ways out, in order of preference.
+to fall back on. The node refreshes its credential automatically while it
+runs. But the control plane retires the key that signed the credential one
+`--key-grace-period` (one hour by default) after the next key rotation. If
+the node is off past that point, `/refresh` refuses its credential. An SDK
+member in the same position enrolls again on start when its `enroll` call is
+given a token. Otherwise the SDK member fails with `CredentialRetiredError`
+naming the state directory. There are three ways out, in order of preference.
**Enroll again.** Mint a new token and run `agentmesh-node join` with it. The
control plane already knows the peer ID, so it mints a new credential
diff --git a/site/content/docs/guides/kubernetes.md b/site/content/docs/guides/kubernetes.md
index 374934d1..c98b4d8c 100644
--- a/site/content/docs/guides/kubernetes.md
+++ b/site/content/docs/guides/kubernetes.md
@@ -208,9 +208,12 @@ keep, review these settings:
`mesh:system:authenticated` to a role with wide grants: on a public
identity provider it means everyone. The testnets bind it on purpose. A
private mesh should bind groups or service accounts.
-- **Signing keys.** `--key-grace-period` defaults to one hour. A node that is
- down for longer must enroll again. The testnets use 48 hours. Pick a value
- that matches how long your nodes can legitimately be off.
+- **Signing keys.** `--key-grace-period` defaults to one hour. The control
+ plane retires a key one grace period after the next rotation. A node that
+ is down past the retirement of the key that signed its credential must
+ enroll again. With the defaults, that retirement comes between about one
+ and 25 hours after the node goes down. The testnets use 48 hours. Pick a
+ value that matches how long your nodes can legitimately be off.
- **Console origin.** When a proxy terminates TLS in front of the console,
set `console.externalUrl` so that the OIDC redirect URI and the cookie
`Secure` flag do not depend on forwarded headers.