Context
ADR 0039
ships opt-in TLS / mTLS for the Management HTTP API in v0.1.0,
but the listener does not pick up rotated certificates
without a restart. The cert PFX / PEM path is read once at
`ivicli api start` time.
CHANGELOG.md → Known limitations:
Cert hot-reload deferred (ADR 0039 §Out-of-scope) — long-running
API servers must restart to pick up rotated certs.
Why this matters
Operators who deploy ivi-cli as a long-running daemon (e.g. via
systemd or a Windows Service) and rotate certs via Let's Encrypt
/ ACME / corporate PKI cron jobs have to schedule a restart of
the daemon every rotation cycle, which is intrusive.
Approach sketch
- Wire a
FileSystemWatcher (or polling fallback) on the cert
paths declared in [api.tls].
- On change: validate the new cert, swap the listener's cert
reference under a lock, log a ServerLifecycle audit event
(kind=cert-reloaded).
- Reject the rotation if the new cert fails validation (chain,
expiry, key match); keep the old cert active and emit a
warning.
Acceptance
- E2E test: rotate the cert file mid-flight, verify next
HTTPS request uses the new cert without restarting the
process.
- Update ADR 0039 in place: move "cert hot-reload" out of
§Out-of-scope into §Decision.
Context
ADR 0039
ships opt-in TLS / mTLS for the Management HTTP API in v0.1.0,
but the listener does not pick up rotated certificates
without a restart. The cert PFX / PEM path is read once at
`ivicli api start` time.
CHANGELOG.md → Known limitations:
Why this matters
Operators who deploy ivi-cli as a long-running daemon (e.g. via
systemd or a Windows Service) and rotate certs via Let's Encrypt
/ ACME / corporate PKI cron jobs have to schedule a restart of
the daemon every rotation cycle, which is intrusive.
Approach sketch
FileSystemWatcher(or polling fallback) on the certpaths declared in
[api.tls].reference under a lock, log a
ServerLifecycleaudit event(kind=
cert-reloaded).expiry, key match); keep the old cert active and emit a
warning.
Acceptance
HTTPS request uses the new cert without restarting the
process.
§Out-of-scope into §Decision.