A Prometheus exporter for X.509 certificates, built for Kubernetes first. It watches your cluster's TLS material as native Kubernetes resources β Secrets, ConfigMaps, kubeconfigs, on-disk PKI on the nodes β and turns expirations into actionable Prometheus series. Designed to run inside the cluster it observes, but equally happy as a standalone binary.
- TLS Secrets of any type β
kubernetes.io/tls, Opaque bundles, full chains β across all namespaces or a curated subset. - ConfigMaps holding cert or CRL data under any key you point at.
- PKCS#12 keystores and truststores, with passphrase pulled from a
sibling key in the same Secret, an external file, a cross-namespace
Secret reference, or none (
tryEmptyPassphrase). - JKS / JCEKS keystores and truststores β magic-byte auto-detection
between JKS and JCEKS; passphrase from a sibling key in the same Secret,
a separate Secret in any namespace, an external file, or none
(
tryEmptyPassphrase). - Certificate Revocation Lists β
X509 CRLPEM blocks (intermixed freely withCERTIFICATEblocks) and raw DER*.crlfiles (format: der) are parsed into the dedicatedx509_crl_*family so a stale CRL pages on-call before its consumers start rejecting the issuer's certs. - Admission and API-discovery caBundles β inline
caBundlePEM fields on cluster-scoped admission resources (MutatingWebhookConfiguration,ValidatingWebhookConfiguration), the API-aggregation layer (APIService), and CRDs with a conversion webhook (CustomResourceDefinition). - PEM chains β every certificate in a multi-cert bundle becomes its own series, so intermediate CAs and trust roots appear alongside leaf certs with no extra configuration.
- Raw DER certificates as well as CRLs (
format: der) β the binary blobs some PKI tooling writes and HTTP CRL Distribution Points serve. - Kubeconfigs with embedded base64 certificates or PEM file references β
every
clusteranduserblock exposed as its own series. - Any number of clusters from a single instance β each Kubernetes source can point at its own kubeconfig, so one exporter fans in the certificates of several clusters.
- Files on disk β glob patterns (
*,**,?), atomic symlink swaps detected on the next poll (certbot renewals, kubelet projected..data/mounts), and dual deployment: inside the exporter pod or as a node-local DaemonSet for cluster PKI (kubelet, etcd, kube-apiserver). - Your workload metadata β chosen labels of the watched Secrets, ConfigMaps and caBundle resources are lifted onto the certificate series, so alerts can route to the team that owns them.
| Where to go | What you'll find |
|---|---|
| π Install on Kubernetes | Helm chart values, secretTypes / PKCS#12 wiring, hostPath PKI DaemonSets |
| π Metrics | Per-cert / per-source / health series, label schema, PromQL examples |
| π‘οΈ Hardening | Supply-chain verification, SBOM queries, immutable-digest pinning |
| β FAQ | Memory sizing, cardinality control, HA, non-Kubernetes use |
| ποΈ Contributing | Dev loop with Tilt + k3d + Dagger, conventions, release flow |
Warning
Upgrading from version 3? Start with the
v3 β v4 migration guide β chart distribution
moved to OCI on quay.io, the Alpine image variant is retired, and a few
values keys changed shape.
-
100% Go. A few thousand lines, no CGO, no plugins β auditable end to end in an afternoon.
-
Declarative and modular. One YAML config file lists the sources β Kubernetes, files, kubeconfigs, caBundles β and the format each one parses. Sources and format parsers are independent modules, so adding one doesn't touch the others.
-
Performance-aware. Parsed certificates are cached so repeat scrapes don't re-decode the same PEM blocks. On Kubernetes, the exporter pages through Secrets and ConfigMaps with a paginated LIST + WATCH loop (50 objects per page by default) instead of polling
kube-apiserver, with watch traffic that scales with churn, not with scrape rate. Memory stays flat on Secret-heavy clusters instead of spiking. -
Observable per source. Each source reports its own health β
x509_source_up,x509_source_bundles,x509_source_errors_total{reason}β so a missing RBAC permission or a vanished file shows up as its own triage signal. -
Helm-first delivery. A first-party Helm chart covers Deployments, DaemonSets, RBAC, ServiceMonitor, PrometheusRule, and a Grafana dashboard. Published as an OCI artifact.
-
Cross-platform binaries. Each release ships statically-linked binaries for Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD, Illumos and Solaris across
amd64,arm64,armv7andriscv64. Drop one on a legacy box, run it under systemd or Windows Services β the exporter has no daemon dependencies and reads files straight from disk. -
Plays with any Prometheus-compatible collector. The
/metricsendpoint speaks the canonical OpenMetrics text format and supports TLS + BasicAuth viaprometheus/exporter-toolkit(--web.config.file), so mTLS scrapes work out of the box. Tested against / known to work with: Prometheus, Grafana Agent / Alloy, VictoriaMetrics (vmagent), Thanos, Cortex / Grafana Mimir, OpenTelemetry Collector, Datadog Agent, Elastic Metricbeat, Splunk OTel Collector, Sysdig, New Relic, Dynatrace, Sumo Logic, Wavefront, Telegraf. -
Open, signed, attested supply chain. Every release is built by a single open-source GitHub Actions pipeline. Container images, Helm chart, and binaries are signed with sigstore/cosign keyless (no maintainer-held private key); binaries carry a SLSA Level 3 in-toto provenance attestation; images carry a CycloneDX SBOM as a cosign attestation. Verification recipes live in the hardening guide.
-
Defensive by intent. The project tracks the OpenSSF Scorecard and converges on its recommendations β pinned dependencies, branch protection, signed commits, dependency review, SBOM, no force-pushes. Finding a defensive practice we don't follow yet? Open an issue.
End-to-end, the exporter is one piece in a four-stage pipeline that you likely already run for every other workload. No new tooling to learn, no parallel control plane β just one more metric family in the observability stack you already have.
-
Deploy. A single
helm installdrops a Deployment (in-cluster Secrets / ConfigMaps) and, optionally, DaemonSets (on-node PKI like kubelet, etcd, kube-apiserver). No CRDs of its own, no operator. Outside Kubernetes, the same binary runs as a systemd unit pointed at files on disk. -
Scrape. The chart creates a
ServiceMonitor(orPodMonitor) so a prometheus-operator-managed Prometheus picks the exporter up automatically. On clusters without the operator, the standardprometheus.io/scrapePod annotations work just as well. -
Alert. A
PrometheusRuleships with six batteries-included alerts: read-errors canary (RBAC / parsing / missing files), per-certificate error, renewal warning (28 days out by default), expiration critical (14 days out), plus the two CRL-freshness rulesCRLNeedsRefresh(7 days beforenextUpdate) andCRLStale(the momentnextUpdateis crossed). Alertmanager routes them like any other rule β Slack, PagerDuty, email, webhooks β and the thresholds plus individual alerts are tunable per install. -
Visualize. A ready-to-import Grafana dashboard lists every certificate the exporter sees, sorted by time remaining, sliced by namespace, source, and issuer. Deploy it via the chart as a sidecar-discovered ConfigMap (
grafana.createDashboard: true) or import the JSON by hand.
The net effect: a certificate renewal is no longer an outage waiting to
happen. The on-call rotation that already triages your service alerts
also catches expiring certs β 28 days ahead for the leaf, 14 for the
critical ones β and the team that owns the workload owns the renewal,
instead of a platform team scrambling the day a cert-manager annotation
turns out to have been misspelled six months ago.