enix/x509-certificate-exporter

🔏 X.509 Certificate Exporter

https://gitlab.com/enix.io/x509-certificate-exporter/badges/master/pipeline.svg](https://gitlab.com/enix.io/x509-certificate-exporter/-/pipelines) https://gitlab.com/enix.io/x509-certificate-exporter/badges/master/coverage.svg](https://gitlab.com/enix.io/x509-certificate-exporter/-/pipelines) https://goreportcard.com/badge/github.com/enix/x509-certificate-exporter](https://goreportcard.com/report/github.com/enix/x509-certificate-exporter) https://img.shields.io/badge/License-MIT-blue.svg](https://opensource.org/licenses/Apache-2.0) https://img.shields.io/badge/Brought%20to%20you%20by-ENIX-%23377dff?labelColor=888&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAQAAAC1QeVaAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QA/4ePzL8AAAAHdElNRQfkBAkQIg/iouK/AAABZ0lEQVQY0yXBPU8TYQDA8f/zcu1RSDltKliD0BKNECYZmpjgIAOLiYtubn4EJxI/AImzg3E1+AGcYDIMJA7lxQQQQRAiSSFG2l457+655x4Gfz8B45zwipWJ8rPCQ0g3+p9Pj+AlHxHjnLHAbvPW2+GmLoBN+9/+vNlfGeU2Auokd8Y+VeYk/zk6O2fP9fcO8hGpN/TUbxpiUhJiEorTgy+6hUlU5N1flK+9oIJHiKNCkb5wMyOFw3V9o+zN69o0Exg6ePh4/GKr6s0H72Tc67YsdXbZ5gENNjmigaXbMj0tzEWrZNtqigva5NxjhFP6Wfw1N1pjqpFaZQ7FAY6An6zxTzHs0BGqY/NQSnxSBD6WkDRTf3O0wG2Ztl/7jaQEnGNxZMdy2yET/B2xfGlDagQE1OgRRvL93UOHqhLnesPKqJ4NxLLn2unJgVka/HBpbiIARlHFq1n/cWlMZMne1ZfyD5M/Aa4BiyGSwP4Jl3UAAAAldEVYdGRhdGU6Y3JlYXRlADIwMjAtMDQtMDlUMTQ6MzQ6MTUrMDI6MDDBq8/nAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDIwLTA0LTA5VDE0OjM0OjE1KzAyOjAwsPZ3WwAAAABJRU5ErkJggg==]([***]

一个专注于证书过期监控的Prometheus exporter，采用Go编写，专为云部署场景设计。可监控以下来源的证书以在过期前发出通知：

• PEM编码文件（通过路径或目录扫描）
• 包含嵌入式证书或文件引用的Kubeconfig配置
• Kubernetes集群中的TLS Secrets

!https://raw.githubusercontent.com/enix/x509-certificate-exporter/master/docs/grafana-dashboard.jpg

安装

🏃 快速开始

https://github.com/enix/x509-certificate-exporter/tree/master/deploy/charts/x509-certificate-exporter#-tldr%E6%98%AF%E5%9C%A8%E9%9B%86%E7%BE%A4%E4%B8%8A%E9%83%A8%E7%BD%B2%E5%8A%9F%E8%83%BD%E5%AE%8C%E6%95%B4%E7%9A%84exporter%E7%9A%84%E6%9C%80%E7%9B%B4%E6%8E%A5%E6%96%B9%E5%BC%8F%EF%BC%8C%E4%B8%94%E6%94%AF%E6%8C%81%E9%AB%98%E5%BA%A6%E8%87%AA%E5%AE%9A%E4%B9%89%E3%80%82%E8%AF%A6%E8%A7%81https://github.com/enix/x509-certificate-exporter/tree/master/deploy/charts/x509-certificate-exporter%E3%80%82

此外，可使用https://grafana.com/grafana/dashboards/***%E5%9C%A8Grafana%E5%AE%9E%E4%BE%8B%E4%B8%AD%E5%B1%95%E7%A4%BAexporter%E6%8C%87%E6%A0%87%E3%80%82

使用Docker

Docker镜像可通过以下地址获取：https://hub.docker.com/r/enix/x509-certificate-exporter

使用预编译二进制

每个https://github.com/enix/x509-certificate-exporter/releases%E5%9D%87%E6%8F%90%E4%BE%9B%E9%80%82%E7%94%A8%E4%BA%8E%E5%A4%9A%E7%A7%8D%E5%B9%B3%E5%8F%B0%E7%9A%84%E9%A2%84%E7%BC%96%E8%AF%91%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%E3%80%82

使用源码

项目入口点为./cmd/x509-certificate-exporter，可按标准Go程序构建：

bash
go build ./cmd/x509-certificate-exporter

使用方法

可用指标

• x509_cert_not_before: 证书生效时间戳
• x509_cert_not_after: 证书过期时间戳
• x509_cert_expired: 证书是否已过期（1为已过期，0为未过期）
• x509_read_errors: 无法读取的路径数量

高级用法

通过--help查看完整配置参数：

Usage: x509-certificate-exporter [-hv] [--debug] [-d value] [--exclude-label value] [--exclude-namespace value] [--expose-relative-metrics] [-f value] [--include-label value] [--include-namespace value] [-k value] [-p value] [-s value] [--trim-path-components value] [--watch-kube-secrets] [parameters ...]
     --debug       启用调试模式
 -d, --watch-dir=value
                   监控一个或多个包含x509证书文件的目录（非递归）
     --exclude-label=value
                   从监控列表中移除带有指定标签（或标签值）的Kubernetes Secrets（在--include-label之后应用）
     --exclude-namespace=value
                   从监控列表中移除指定的Kubernetes命名空间（在--include-namespace之后应用）
     --expose-relative-metrics
                   额外暴露相对时长指标而非绝对时间戳
 -f, --watch-file=value
                   监控一个或多个x509证书文件
 -h, --help        显示帮助信息并退出
     --include-label=value
                   将带有指定标签（或标签值）的Kubernetes Secrets添加到监控列表（使用时默认排除所有Secrets）
     --include-namespace=value
                   将指定的Kubernetes命名空间添加到监控列表（使用时默认排除所有命名空间）
 -k, --watch-kubeconf=value
                   监控一个或多个包含嵌入式x509证书或PEM文件引用的Kubernetes客户端配置（Config类型）
 -p, --port=value  Prometheus exporter监听端口 [默认：9793]
 -s, --secret-type=value
                   要监控的Kubernetes Secret类型及密钥（例如："kubernetes.io/tls:tls.crt"）
     --trim-path-components=value
                   从标签路径中移除<n>个前置组件
 -v, --version     显示版本信息并退出
     --watch-kube-secrets
                   抓取并监控kubernetes.io/tls类型的Secrets

Docker部署示例

监控本地证书文件：

bash
docker run -d -p 9793:9793 -v /path/to/certs:/certs docker.xuanyuan.run/enix/x509-certificate-exporter --watch-file /certs/server.crt

监控Kubernetes Secrets（需挂载kubeconfig）：

bash
docker run -d -p 9793:9793 -v ~/.kube/config:/kubeconfig docker.xuanyuan.run/enix/x509-certificate-exporter --watch-kube-secrets --watch-kubeconf /kubeconfig

FAQ

为什么使用not after时间戳而非剩余秒数？

主要有两个原因：

1. Prometheus在指标值保持不变时存储效率更高。
2. 通过Prometheus查询计算剩余时间可避免exporter检查与告警/查询执行之间的 latency（秒级）差异。

示例查询：

x509_cert_not_after - time()

如何确保长期稳定工作？

路径变更或文件删除可能导致无法监控关键证书。exporter通过x509_read_errors指标发布无法读取的路径数量，包括Kubernetes API响应失败，但不统计已删除的Secrets。

建议基础告警规则：

x509_read_errors > 0