Certificate management
Turning TLS on is day one. This page covers day two: keeping certificates valid over time, swapping the CA, and protecting the CA key for disaster recovery. It assumes you have enabled TLS (TLS encryption) and chosen a trust mode (CA and trust modes).
Certificate lifetimes
Two windows govern the cluster's certificates, both configurable under Lifetimes in the zaris.security.tls block.
| Certificate | Default validity | Renewed by |
|---|---|---|
| Cluster CA | 3650 days (~10 years) | Backup/restore or re-provision |
| Node leaf | 90 days | Automatic cert-based renewal |
Short-lived leaves are intentional: a 90-day leaf limits the blast radius of a key compromise, and renewal is automatic and non-disruptive. A leaf renews once Lifetimes.RenewAtFraction of its life has elapsed (default 0.66, about two-thirds).
Renewal (Clustron-signed modes)
A node renews its own leaf without an enrollment token. It proves possession of its current private key by signing the renewal request with it (against the issuer's /security/tls/renew-csr endpoint); the manager validates that the current leaf is this node's, is unexpired, and chains to the cluster CA, then issues a fresh leaf.
The consequences are worth stating plainly:
- The one-time enrollment token is a first-boot credential only. Restarts and renewals never re-spend it.
- Renewal is not a re-enrollment. A node that has lost its key entirely must re-enroll with a new token; a node that still has its key just renews.
Verify current expiry any time:
Get-ZrStoreTlsStatus -Store orders -ShowCertificates
In Mode 3 (pre-issued leaves) you own renewal. Your external system (mesh, cert-manager, pipeline) issues the new certificate and writes it to the mounted path; Zaris reloads the file. Mount the full chain if the leaf is issued by an intermediate.
Swapping the CA
You can change the CA of an already-secured cluster — for example, migrating from the auto-generated CA to your corporate CA. Import the new CA onto every connected manager, then re-enable TLS on the store so Zaris re-issues node certificates under it:
Import-ZrClusterCa -CaFile C:\pki\corp-ca.pfx -CaPassword (Read-Host -AsSecureString)
Enable-ZrStoreTls -Store orders -Restart
Import-ZrClusterCa adopts the CA cluster-wide — it has no -Store parameter. From the Web Console, importing a CA on the Encryption (TLS) tab does the same and automatically re-encrypts (re-enrolls and restarts) the affected stores, so a CA swap is a single action.
A CA swap re-issues every node's certificate and rolls the nodes. Clients that pinned the old CA thumbprint must be updated to the new one; clients that auto-fetch the CA pick it up on their next connect. Plan a swap like any rolling change.
Backup and restore (disaster recovery)
In the Clustron-signed modes, the cluster CA key is the single most important secret in the cluster — lose it and you cannot issue new certificates. Zaris makes it recoverable.
# Back up: exports the CA (cert + key) as a passphrase-encrypted PKCS#12.
Backup-ZrClusterCaKey -OutFile cluster-ca-key.enc -Passphrase (Read-Host -AsSecureString)
# Restore: installs that encrypted backup onto a replacement issuer.
Restore-ZrClusterCaKey -InFile cluster-ca-key.enc -Passphrase (Read-Host -AsSecureString)
- Backup is the one sanctioned copy of the CA key. Keep it off the issuer host, with the passphrase stored separately. It is useless without the passphrase.
- Restore decrypts the backup, validates it is a usable CA, and persists it encrypted at rest — the cluster can issue certificates again.
Treat the CA backup like a root password: encrypted, off-host, passphrase held separately, access audited. Everything else in the security model can be reconstructed; a lost CA key cannot.
At rest, the CA key is always stored encrypted on the issuer, never in plain text and never copied to a live node — nodes only ever hold their own leaf.
Rotating the CA itself
Rotating the CA (as opposed to renewing leaves) is a deliberate operation: provision or import a new CA, which re-issues all node certificates, then update clients' trust anchors to the new CA. Because it touches every client's trust, schedule it — unlike leaf renewal, it is not silent. Clients that auto-fetch the CA minimize the coordination required. The TrustAnchors list can hold more than one root, so old and new can be trusted during the overlap.
Summary
| Task | How |
|---|---|
| Check expiry / thumbprints | Get-ZrStoreTlsStatus -ShowCertificates |
| Export the public CA for clients | Get-ZrClusterCaCert -OutFile cluster-ca.crt |
| Renew a node leaf | Automatic (cert-based, no token) |
| Import / swap the CA | Import-ZrClusterCa then Enable-ZrStoreTls -Restart, or Console → Encryption (TLS) |
| Back up the CA key | Backup-ZrClusterCaKey (passphrase-encrypted, kept off-host) |
| Restore after issuer loss | Restore-ZrClusterCaKey onto a new issuer |
Next steps
- Connecting a secured client — the client's side of all this.
- CA and trust modes — who signs the certificates.
- TLS encryption — the data-plane TLS configuration reference.