🔏 X.509 Certificate Exporter

![Build status]([] ![Code coverage]([] ![Go Report]([] ![License MIT]([] ![Brought by Enix]([***]

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

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

!Grafana Dashboard

安装

🏃 快速开始

Helm chart是在集群上部署功能完整的exporter的最直接方式，且支持高度自定义。详见chart文档。

此外，可使用Grafana Dashboard在Grafana实例中展示exporter指标。

使用Docker

Docker镜像可通过以下地址获取：enix/x509-certificate-exporter

使用预编译二进制

每个发布版本均提供适用于多种平台的预编译二进制文件。

使用源码

项目入口点为./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 enix/x509-certificate-exporter --watch-file /certs/server.crt

监控Kubernetes Secrets（需挂载kubeconfig）：

bash
docker run -d -p 9793:9793 -v ~/.kube/config:/kubeconfig 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