Certificate renewal failure alerts
Overview
A failed CertOps renew job raises cert_renewal_failed on the same channels as expiry and endpoint-health alerts: the alert queue, your delivery window, and the contact group on the certificate's token.
Paths that can reach a terminal renew failure: the agent reports failed / blocked / policy rejected; the lease reaper marks orphaned_unknown_effect; forced agent retirement fences a held renew job; an external executor reports failed or rejected.
The transaction that records the failure also records the intent to alert. Contact resolution and queue insert run later. A skip (no token, no channel) is stored with its reason.
Durability
The intent is written in certops_outbox. The outbox-drain sweep of the CertOps maintenance worker delivers it. If the worker is not running, intents stay pending.
When it fires
| Fires | Does not fire |
|---|---|
renew reaches failed, blocked, or agent-side rejected | issue, deploy, reload, revoke, no-op |
renew reaches orphaned_unknown_effect (silent agent or forced retirement after running) | Approver reject or operator cancel |
Forced-retirement cancel of a held renew job | Dry run (dry_run_complete) |
Non-terminal statuses (pending, approved, claimed, running) | |
| No linked cert-category token, no workspace admin, or no email/webhook channel | |
Certificate retired as revoked or decommissioned |
The job timeline and audit log remain the source of truth. WhatsApp is not a channel for this alert type.
Issue vs renew
A failed renew means a live certificate with a real expiry was not replaced. A failed issue means a certificate you asked for was never created: nothing is serving, nothing is expiring. Watch provisioning inventory for issuance problems and this alert for renewal problems.
Idempotency
One alert per job, keyed cert_renewal_failed:<jobId>. A new job that also fails is a new alert.
Routing
Resolved from the failed job's managed certificate, in order: the linked token's contact group; else the workspace default; a deleted group falls back to the default. Email and webhooks follow that group. Assign a group with at least one email contact or webhook, or set a workspace default. Delivery still respects the delivery window.
The payload carries certificate identity and the frozen error code. Open the job timeline for evidence. The queue stores ids and the error code only, never payload or key material. The outbox stores the same ids and error code, never payload or key material.
If a failure produced no alert
- Is the
certopsmaintenance worker running? See Maintenance sweeps. - Was the operation
renew? A failedissuedoes not alert. - Did a human reject or cancel the job? Forced-retirement cancel does alert.
- Is the certificate linked to a token?
- Does the contact group have email or a live webhook?
- Was the certificate retired?