Skip to content
StratumStratum Docs

Certificates

A cluster has one certificate authority (CA). Every node has its own certificate, signed by it, that it uses to talk to the other nodes.

Material Where Lifetime Renewed by
Cluster CA OpenBao, in the secrets store 10 years You, by rotation
Node certificate /etc/stratum/pki/node.crt on each node 90 days The control plane, by itself
Trust bundle /etc/stratum/pki/cluster-ca.crt on each node Follows the CA Each node

The CA’s private key is only in OpenBao, no copy on any disk. Without a platform backup, losing OpenBao is terminal: no certificate can be issued again.

Check them

Section titled “Check them”

The cluster’s PKI posture, one call:

Terminal window
curl -s "$API/v1/admin/pki/cluster-ca" -H "Authorization: Bearer $TOKEN" | jq '.findings'

It reports whether every node agrees on one CA, and flags peers refused because their node was decommissioned. Console: Admin › Substrate › PKI. stratumctl admin selfcheck runs the same check.

On a node, a certificate’s end date and the CA’s fingerprint:

Terminal window
sudo openssl x509 -in /etc/stratum/pki/node.crt -noout -subject -enddate
sudo openssl x509 -in /etc/stratum/pki/cluster-ca.crt -noout -fingerprint -sha256

The node certificate ends within 90 days. The fingerprint must be the same on every node: a mismatch means a node is on another root.

Node certificates renew when a third of their life remains, with some jitter per node. You need do nothing.

Rotate the cluster CA

Section titled “Rotate the cluster CA”

Readiness warns ClusterCAExpiring when the CA is within 90 days of expiry (the alarm is pki-cluster-ca-expiring), and blocks once it has expired. Rotation is staged, so the cluster trusts the old root while every node’s certificate is re-issued under the new one.

Terminal window
curl -X POST "$API/v1/admin/pki/rotations" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"reason": "CA expires in 80 days"}'
curl -s "$API/v1/admin/pki/rotations" -H "Authorization: Bearer $TOKEN"

The rotation waits for every node, so keep every node up while it runs. One rotation can run at a time.

  • Abort works until the rotation reaches cutting-over: POST /v1/admin/pki/rotations/{id}/abort. After that the only way is forward.
  • A rotation ends every live join code: create a new one afterwards.
  • Take a platform backup after a rotation: an older bundle holds the old CA.