Schedule key maintenance
Open Settings > Certificates & keys > Scheduled key maintenance. Create a schedule for each credential you maintain. All schedules start disabled. The management service checks due work every 30 seconds.
Choose the action
| Key family | Scheduled action | Your next step |
|---|---|---|
| Online instruction signer | Prepare a replacement public key | Get a root key holder's approval, then switch keys and retire the old one. |
| Device instruction encryption key | Replace one enrolled device's key and publish fresh instructions | Confirm that the device accepts the new instructions. |
| Console management credential | Replace the credential and retain the previous value | Verify every Console, then retire the previous credential. |
| Browser, management and device TLS | Create a review reminder | Follow Rotate credentials and certificates. |
| Private swarm issuing CA and root signing keys | Create a review reminder | Plan the trust rollout before replacing any root. |
| Encryption-at-rest identity and recipients | Create a review reminder | Back up, stop writers and follow the recipient procedure. |
| Seeder, metrics and outbound telemetry credentials | Create a review reminder | Follow the credential's rotation procedure. |
Review reminders leave credentials unchanged. Acknowledge review records that you reviewed the procedure, not that a rotation succeeded. For browser TLS, metrics tokens and collector authentication, complete the guided Console workflow separately from the reminder. For deployment trust, seeder credentials and server encryption keys, use deployment maintenance. Its explicit downtime and key-holder approvals are not started by acknowledging a reminder. Device agents already renew their private-swarm leaf certificates six hours before their one-day validity ends. Replacing the issuing CA is a separate task.
Create a schedule
- Select New schedule, then a key family.
- For a device instruction key, enter the enrolled device ID.
- Enter the next window's start in UTC, repeat interval and window length.
- Check Enable schedule, choose Save schedule, and confirm the action.
- Refresh maintenance to check the scheduler and operation state.
Device instruction keys require an interval of 8–21 days. The previous key remains usable for seven days. Other families accept intervals of 1–365 days. Windows can last 5–1,440 minutes. A schedule supports one family and target; the deployment supports up to 32 schedules.
Select an existing schedule to change it or clear Enable schedule. You can disable an active schedule; finish its operation before other edits. Disabling leaves an active transition available for recovery. A saved schedule shows its revision. If settings change while you edit, your draft stays visible. Choose Reload saved schedule, review the UTC window, then save again. For an uncertain save, use Refresh maintenance and check the saved schedule before retrying. Returning to the page does not repeat the request.
Complete the operation
| State | Action |
|---|---|
| Approval required | Under Replace signing key, download the public key and get a root key holder's approval. |
| Verification required | Update and verify every Console, then choose Retire previous credential. |
| Review required | Follow the relevant procedure, then acknowledge the review. |
| Intervention required | Check the credential files and rotation state before using the recovery control. |
| Completed | Confirm device or consumer acceptance separately. |
| Missed | The window elapsed without a credential change. Check the next start time. |
| Cancelled | The pending change was cancelled. Check the next start time. |
Only one scheduled credential transition runs at a time. An unfinished approval or uncertain result pauses further rotations. Review reminders can coexist. Keep manual maintenance separate from scheduled work.
On one Docker host
The server and Console share their management credential files. After a scheduled replacement, open Inventory and verify other Console instances, if present. Retirement requires your confirmation and an API request authenticated with the replacement credential. An old credential cannot authorize its own removal.
On separate Docker hosts
For an installer-owned split deployment with its host worker running, the scheduler publishes the current/previous pair to the recorded remote Console and verifies current-token access. Failed publication keeps overlap active and requires reconciliation. Retirement repeats the consumer check.
For manually provisioned deployments, copy the replacement management credential using the separate-host procedure. Verify each Console before retiring the previous value. The scheduler leaves the overlap active until you confirm.
On Kubernetes
Installer-owned deployments use the writable server credential authority and their external worker to publish the pair to Console Secrets and verify every replica. Keep the worker running; failed synchronization must be reconciled before retirement. The scheduler does not remove overlap automatically.
For manually provisioned deployments, mounted Kubernetes Secrets are read-only: use the management credential procedure instead of enabling that family's automated rotation.
Recover an interrupted operation
The scheduler records its intent before changing a credential. After a restart, an interrupted operation needs explicit review. It does not retry automatically.
For device keys, Retry after key review reuses an already committed key and retries instruction publication. For signer preparation, it reuses the same operation ID. Check the active signer before retrying.
For management credentials, Check credential recovery compares the current and previous files with the recorded public fingerprints. A proven replacement returns to verification. A proven unchanged original cancels the interrupted operation. Conflicting files require repair before recovery can proceed. If credential storage rejected the operation before any change was admitted, the recovery control cancels it without writing to that storage.
Never delete the maintenance journal to clear an uncertain operation.
Include state/key-maintenance/ with the rest of the server state in backups.
The journal retains at most 256 operations and removes the oldest finished
record when admitting new work. Active records are retained.
Check scheduler health
Observed means the management worker checked its journal within 90 seconds. Stale or not observed requires a management-service check. Clock error means the clock moved behind the last recorded observation; restore accurate time before maintenance resumes.
Missed windows advance to the next future interval. They never cause a burst of delayed rotations. Review certificate deadlines even when a schedule exists: key-holder approval and consumer rollout can take longer than the planned window.