saksh@dev:~/cyclops$cat README.md | head
cyclops
A backstop for cert-manager · Kubernetes controller in Go (kubebuilder)
cert-manager renews your certificates automatically, until it silently doesn't. An ACME challenge starts failing, an issuer loses its CA Secret, a renewal stalls, and nobody finds out until the site is down. cyclops emails you or posts to Slack when a certificate is expired, never issued or overdue for renewal, and includes cert-manager's own failure reason so you can see why. A healthy cluster stays quiet.
github repo quick start back to dev.saksh.fyi
# Status: beta (v0.1.0-beta.8), in development. The API is v1alpha1 and can change between releases.
saksh@dev:~/cyclops$cyclops why
- No Prometheus needed. It reads cert-manager
Certificateresources directly. If you already alert on cert-manager metrics, cyclops is a second line of defence that also tells you why. - It explains the failure. Reports include failed attempts, ACME state and the failure reason word for word. For CA, Vault and self-signed issuers it shows the request's
Readyreason and the issuer's error. - It tells you when it breaks. A failed report run shows up as
ReportSucceeding=Falseon theCertReport, plus a Warning Event. - Least privilege. The controller never reads certificates and the report Pod has read-only access. They use separate ServiceAccounts.
- Email or Slack. SMTP, SES or Slack incoming webhooks (Slack from
v0.1.0-beta.8).
saksh@dev:~/cyclops$cat QUICKSTART.md
kubectl create namespace cyclops-system
helm install cyclops oci://ghcr.io/sakshitposting-irl/charts/cyclops --version 0.1.0-beta.8 \
--namespace cyclops-system \
--set email.smtp.host=smtp.example.com
kubectl apply -f - <<'YAML'
apiVersion: cyclops.sakshitposting-irl.github.io/v1alpha1
kind: CertReport
metadata: {name: cluster-certs}
spec:
schedule: "0 8 * * *" # UTC
notifiers:
- type: Email
email: {from: cyclops@example.com, to: [platform@example.com]}
YAML
Needs a cluster with cert-manager and Helm 3.8+. SMTP logins, SES and Slack are in install below.
# tested: the full path on kind with a fake mail server and a fake Slack, and SMTP against Gmail (STARTTLS on 587, TLS on 465). not yet run: SES against real AWS, and real Slack. Try it on a non-production cluster first.
saksh@dev:~/cyclops$cyclops run --watch
# simulated for the page: made-up certificates, not real cluster data. A healthy run sends nothing.
saksh@dev:~/cyclops$cyclops explain --flow
You create a cluster-scoped CertReport. The controller keeps an owned CronJob in sync with it. On schedule the Job lists the cert-manager Certificates in scope (every namespace by default), picks out the ones that need attention, and sends them to each notifier: by email, to Slack, or both. If there are none, it sends nothing.
"Overdue" means past the renewal time cert-manager set for the certificate. For due certificates the report also shows cert-manager's own diagnostics, word for word, so you can see why renewal isn't happening. For ACME issuers these come from the Order. For a CA, Vault or self-signed issuer the report shows the CertificateRequest's reason and, if the Issuer or ClusterIssuer is not ready, its error (for example a missing CA Secret).
saksh@dev:~/cyclops$cyclops mail --preview --welcome
saksh@dev:~/cyclops$cat architecture.md
| COMPONENT | KIND | ROLE |
|---|---|---|
| CertReport | CRD, cluster-scoped | The configuration: schedule, namespaces, notifiers. |
| controller | Deployment, always on | Reconciles CertReports into CronJobs and sets status conditions. Never reads certificates, never sends a report. |
| report Pod | one-shot, per run | Lists certificates, decides what to report, sends it by email and/or to Slack, then exits. |
| state ConfigMap | owned by the CertReport | Records whether the welcome message was sent. |
The controller and the report Pod run under separate ServiceAccounts. The report Pod is read-only (certificates, CertificateRequests, Orders, Challenges and Issuers, plus Ingresses in annotation mode), so neither holds the other's privileges. Deleting a CertReport removes everything it owns through owner references, so no finalizers are needed.
saksh@dev:~/cyclops$cat ingress-annotation-mode.md
By default cyclops watches whole namespaces. Annotation mode is finer: an Ingress opts in to one CertReport with a single annotation, so ingress-qa and ingress-prod in the same namespace can go to different schedules and recipients, and anything unannotated is left out.
apiVersion: cyclops.sakshitposting-irl.github.io/v1alpha1
kind: CertReport
metadata: {name: prod-certs}
spec:
ingressAnnotationMode: true # cannot be combined with namespaces
notifiers:
- type: Email
email: {from: cyclops@example.com, to: [platform@example.com]}
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: shop
namespace: tenant
annotations:
cyclops.sakshitposting-irl.github.io/cr-name: prod-certs
spec:
tls: [{hosts: [shop.example.com], secretName: shop-tls}] # this Certificate is reported
Each row in the report names the Ingress it came from. The report Pod needs to read Ingresses; the Helm chart grants this unless you set rbac.ingressAccess: false.
# gotcha: an annotation with a typo, or naming a CertReport that does not exist, fails silently. The Ingress is just never reported and nothing is logged.
# security: anyone who can edit an Ingress can send its certificate details to a CertReport's recipients, so restrict who can edit Ingresses.
saksh@dev:~/cyclops$cat slack.md
A Slack notifier posts the report to one or more incoming webhooks. A webhook URL is itself a credential (anyone with it can post), so it never goes in the CertReport: each target names a Secret in cyclops-system that holds the URL under the key url.
kubectl -n cyclops-system create secret generic slack-oncall \
--from-literal=url=https://hooks.slack.com/services/...
---
notifiers:
- type: Slack
slack:
targets:
- name: oncall # lowercase letters, digits and "-"
urlSecretRef: {name: slack-oncall}
- type: Email # Slack and Email can be combined
email: {from: cyclops@example.com, to: [platform@example.com]}
It posts when email would: only when something needs attention, plus a one-time welcome that also checks the URL works. A URL rotated later is not re-checked yet; that comes in a later beta. A long report is split into messages of up to 48 certificates, about a second apart, to stay under Slack's rate limit. Failed posts are retried with backoff, honouring Slack's Retry-After; each target succeeds or fails on its own, and the webhook URL never appears in an error or a log line. An install that only posts to webhooks needs no email settings.
# status: released in v0.1.0-beta.8. Tested with envtest and run on kind against a local fake Slack; not yet run against real Slack.
saksh@dev:~/cyclops$cat INSTALL.md
Needs a cluster with cert-manager installed, kubectl and Helm 3.8 or newer. Beta. The chart and the image (linux/amd64 and linux/arm64) are published to GHCR. Full steps (credentials, templates) are in the README.
# create the namespace, and the credentials Secret only if your SMTP server wants a login kubectl create namespace cyclops-system kubectl -n cyclops-system create secret generic cyclops-mail-credentials \ --from-literal=username=<user> --from-literal=password=<password> # install the chart helm install cyclops oci://ghcr.io/sakshitposting-irl/charts/cyclops --version 0.1.0-beta.8 \ --namespace cyclops-system \ --set email.smtp.host=smtp.example.com \ --set email.smtp.credentialsSecretName=cyclops-mail-credentials # or, Slack only: no email settings, just a Secret per webhook kubectl -n cyclops-system create secret generic slack-oncall \ --from-literal=url=https://hooks.slack.com/services/... helm install cyclops oci://ghcr.io/sakshitposting-irl/charts/cyclops --version 0.1.0-beta.8 \ --namespace cyclops-system
# Helm installs the CRD, RBAC, controller and, if you set them, the mail settings into the namespace you created. SMTP uses STARTTLS on port 587 by default; leave out credentialsSecretName if no login is needed. For SES use --set email.provider=SES --set email.ses.region=<region>. Mail credentials are never set through values: create the Secret yourself and pass its name. With neither email.smtp.host nor email.ses.region set, the chart installs no mail settings; a CertReport with an Email notifier then fails its runs, saying email is not configured.
# use beta.6 or newer: beta.5 crash-loops on startup, and beta.3/beta.4 were never fully published.
# contributing: read CONTRIBUTING.md first. Design decisions are recorded as ADRs, so open an issue before a larger change.
# no Helm? the plain manifests in config/ also work, see "Deploying your own build" in the README.
# then: a CertReport apiVersion: cyclops.sakshitposting-irl.github.io/v1alpha1 kind: CertReport metadata: {name: cluster-certs} spec: schedule: "0 8 * * *" # UTC, the default namespaces: [] # empty means every namespace notifiers: - type: Email email: {from: cyclops@example.com, to: [platform@example.com]} # or, for Slack (or both): - type: Slack slack: targets: [{name: oncall, urlSecretRef: {name: slack-oncall}}]
saksh@dev:~/cyclops$git tag --sort=-creatordate
Newest first. All are pre-releases of v0.1.0; use the latest. From beta.2 on, each tag publishes the image ghcr.io/sakshitposting-irl/cyclops:<tag> and the chart oci://ghcr.io/sakshitposting-irl/charts/cyclops (version without the v).
| RELEASE | DATE | SHIPPED |
|---|---|---|
v0.1.0-beta.8 (latest) | 2026-11-02 | Slack notifier (type: Slack). Email settings optional in the chart, for webhook-only installs. helm install prints a commented CertReport example. The inline logo has a file name, so Gmail no longer shows "noname". Dependencies bumped past govulncheck findings |
v0.1.0-beta.7 | 2026-10-29 | Diagnostics for non-ACME failures: the CertificateRequest's and Issuer's Ready reason |
v0.1.0-beta.6 | 2026-10-28 | Fixes beta.5's crash loop. First working release with the welcome message |
v0.1.0-beta.5 | 2026-10-28 | One-time welcome message and the inline logo in the email. Crash-loops on startup; do not use |
v0.1.0-beta.3, beta.4 | 2026-10-27 | Release runs failed before the chart was attached. Do not use |
v0.1.0-beta.2 | 2026-10-25 | Tag-triggered release workflow (multi-arch image, OCI chart, GitHub pre-release). TemplateValid condition |
v0.1.0-beta.1 | 2026-10-21 | Ingress annotation mode. First Helm chart |
v0.1.0-alpha.2 | 2026-10-14 | ReportSucceeding condition plus a Warning Event for failed runs |
v0.1.0-alpha.1 | 2026-10-11 | First release: CertReport → owned CronJob, report mode, email by SMTP or SES |
saksh@dev:~/cyclops$cyclops status
| PIECE | STATE |
|---|---|
| CertReport → CronJob reconciliation | done, run on kind |
| report mode, email rendering | done, run on kind with a fake SMTP server and with Gmail |
custom email templates (ConfigMap, TemplateValid condition) | done, unit-tested |
| email: SMTP | done, run against Gmail (STARTTLS on port 587 and TLS on port 465, with a login) |
| email: SES | done, tested with a fake client only, not run against real AWS yet |
failed-run signal (ReportSucceeding + Warning Event) | done, run on kind |
| Ingress annotation mode | done, run on kind |
published image v0.1.0-beta.8 | linux/amd64 and linux/arm64 |
| welcome message | done, run on kind (fake server and Gmail): sent once per CertReport; a bad SMTP host shows WelcomeSent=False and one Warning Event, with no retry |
| errors from non-ACME issuers (CA, Vault, self-signed) | done, published in v0.1.0-beta.7 |
| Slack notifier | done, published in v0.1.0-beta.8: tested with envtest and run on kind against a local fake Slack. Not yet run against real Slack |
| Helm chart | published to GHCR as an OCI chart (0.1.0-beta.8) |
| install from the published chart | done, installed and upgraded on kind |
| release pipeline | done: pushing a version tag runs the tests, then publishes the multi-arch image, the chart and a GitHub pre-release |
| design decisions | recorded as numbered ADRs in the repo. Still open: Teams, a generic webhook, who may use which Slack Secret, HA, observability. See what’s next |
# Real SMTP authentication and STARTTLS have run against Gmail; SES has not been run against real AWS. Try it on a non-production cluster first.
saksh@dev:~/cyclops$cat TODO.md
Planned, not built. Each needs its design decision recorded first.
- a new name. "cyclops" collides with two other Kubernetes projects, so the project will likely be renamed before
v0.1.0, with a migration guide. - cyclops check. A one-shot CLI mode: run against your current kubeconfig, print the findings and exit non-zero if there are any. A way to try it with no install, and a CI gate.
- Microsoft Teams. A
type: Teamsnotifier for Workflows webhooks, since the old Office 365 connectors were retired. - served-certificate check. Catch the case where cert-manager renewed but the ingress still serves the old certificate.
- Gateway API. Annotation mode for Gateways, not only Ingresses.
- real Slack. Run the Slack notifier against real Slack and check its message limits.
suggestions welcome at saksh.am [at] outlook [dot] in
← back to dev.saksh.fyi · github.com/sakshitposting-irl/cyclops ↗