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 Certificate resources 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 Ready reason and the issuer's error.
  • It tells you when it breaks. A failed report run shows up as ReportSucceeding=False on the CertReport, 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

idle CronJob 0 8 * * *

# simulated for the page: made-up certificates, not real cluster data. A healthy run sends nothing.

saksh@dev:~/cyclops$cyclops explain --flow

CertReportschedule, scope, notifiers
controllerkeeps a CronJob in sync
CronJobfires on schedule
report Jobsame binary, report mode
emailSES or SMTP
slackincoming webhooks

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

The cyclops welcome email: the logo on a dark header band, then a short explanation of when cyclops sends mail, the report name, its schedule and the namespaces it covers.
The one-time welcome email, rendered from the built-in template with sample data. cyclops sends it once per CertReport, and it also proves that delivery works. The report email uses the same header and styling. A Slack target gets its own one-time welcome message, which checks that the webhook URL works.

saksh@dev:~/cyclops$cat architecture.md

COMPONENTKINDROLE
CertReportCRD, cluster-scopedThe configuration: schedule, namespaces, notifiers.
controllerDeployment, always onReconciles CertReports into CronJobs and sets status conditions. Never reads certificates, never sends a report.
report Podone-shot, per runLists certificates, decides what to report, sends it by email and/or to Slack, then exits.
state ConfigMapowned by the CertReportRecords 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.

Ingressannotated with cr-name
tls[].secretNamematched in the same namespace
Certificatethe same secretName
CertReportits schedule and recipients
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).

RELEASEDATESHIPPED
v0.1.0-beta.8 (latest)2026-11-02Slack 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.72026-10-29Diagnostics for non-ACME failures: the CertificateRequest's and Issuer's Ready reason
v0.1.0-beta.62026-10-28Fixes beta.5's crash loop. First working release with the welcome message
v0.1.0-beta.52026-10-28One-time welcome message and the inline logo in the email. Crash-loops on startup; do not use
v0.1.0-beta.3, beta.42026-10-27Release runs failed before the chart was attached. Do not use
v0.1.0-beta.22026-10-25Tag-triggered release workflow (multi-arch image, OCI chart, GitHub pre-release). TemplateValid condition
v0.1.0-beta.12026-10-21Ingress annotation mode. First Helm chart
v0.1.0-alpha.22026-10-14ReportSucceeding condition plus a Warning Event for failed runs
v0.1.0-alpha.12026-10-11First release: CertReport → owned CronJob, report mode, email by SMTP or SES

saksh@dev:~/cyclops$cyclops status

PIECESTATE
CertReport → CronJob reconciliationdone, run on kind
report mode, email renderingdone, run on kind with a fake SMTP server and with Gmail
custom email templates (ConfigMap, TemplateValid condition)done, unit-tested
email: SMTPdone, run against Gmail (STARTTLS on port 587 and TLS on port 465, with a login)
email: SESdone, tested with a fake client only, not run against real AWS yet
failed-run signal (ReportSucceeding + Warning Event)done, run on kind
Ingress annotation modedone, run on kind
published image v0.1.0-beta.8linux/amd64 and linux/arm64
welcome messagedone, 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 notifierdone, 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 chartpublished to GHCR as an OCI chart (0.1.0-beta.8)
install from the published chartdone, installed and upgraded on kind
release pipelinedone: pushing a version tag runs the tests, then publishes the multi-arch image, the chart and a GitHub pre-release
design decisionsrecorded 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: Teams notifier 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