Utility that exposes the expiry of TLS certificates as Prometheus metrics
Building
To build the Docker image, simply run docker build:
docker build . -t muxinc/certificate-expiry-monitor:latest
Running
Run the Docker image using the executable at /app:
→ docker run muxinc/certificate-expiry-monitor:latest /app --help
Usage of ./certificate-expiry-monitor:
-domains string
Comma-separated SNI domains to query
-frequency duration
Frequency at which the certificate expiry times are polled (default 1m0s)
-hostIP
If true, then connect to the host that the pod is running on rather than to the pod itself.
-ignoredDomains string
Comma-separated list of domains to exclude from the discovered set. This can be a regex if the string is wrapped in forward-slashes like /.*\.domain\.com$/ which would exclude all domain.com subdomains.
-ingressNamespaces string
If provided, a comma-separated list of namespaces that will be searched for ingresses with domains to automatically query
-insecure
If true, then the InsecureSkipVerify option will be used with the TLS connection, and the remote certificate and hostname will be trusted without verification (default true)
-kubeconfig string
Path to kubeconfig file if running outside the Kubernetes cluster
-labels string
Label selector that identifies pods to query
-logformat string
Log format (text or json) (default "text")
-loglevel string
Log-level threshold for logging messages (debug, info, warn, error, fatal, or panic) (default "error")
-metricsPort int
TCP port that the Prometheus metrics listener should use (default 8888)
-namespaces string
Comma-separated Kubernetes namespaces to query (default "default")
-port int
TCP port to connect to each pod on (default 443)
Kubernetes Manifest
You're probably going to want to run the certificate-expiry monitor in a Kubernetes cluster. The following manifest shows how you might monitor a set of ingress pods matching the label k8s-app=my-ingresses in the default namespace for the foobar.example.com domain:
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: certificate-expiry-monitor
namespace: default
spec:
minReadySeconds: 5
revisionHistoryLimit: 3
strategy:
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
template:
metadata:
labels:
app: certificate-expiry-monitor
spec:
containers:
- command:
- /app
- -labels
- k8s-app=my-ingresses
- -namespaces
- default
- -frequency
- 1m
- -domains
- foobar.example.com
image: muxinc/certificate-expiry-monitor:latest
imagePullPolicy: Always
livenessProbe:
httpGet:
path: /healthz
port: 8888
initialDelaySeconds: 5
timeoutSeconds: 5
name: certificate-expiry-monitor
resources:
limits:
cpu: 20m
memory: 50Mi
requests:
cpu: 20m
memory: 50MiMonitoring
A Prometheus endpoint is available at /metrics on TCP port :8888 (customizable with metricsPort).
Labels
| Name | Description |
|---|---|
ns |
Namespace of the pod that was queried |
pod |
Pod being queried for TLS certificates |
domain |
Domain being verified against TLS certificates |
status |
Certificate is either valid, expired, soon (not yet valid), or notfound |
Gauges
| Name | Labels | Description |
|---|---|---|
certificate_expiry_monitor_matching_pods |
ns |
Number of pods that match the label filter in a namespace |
certificate_expiry_monitor_certificate |
ns, pod, domain, status |
Number of pods with a certificate in a given status for the domain |
certificate_expiry_monitor_seconds_since_cert_issued |
ns, pod, domain |
Seconds since the certificate was issued |
certificate_expiry_monitor_seconds_until_cert_expires |
ns, pod, domain |
Seconds until the certificate expires |
Counters
| Name | Labels | Description |
|---|---|---|
certificate_expiry_monitor_tls_open_connection_error |
ns, pod, domain |
Number of times an error occurred while opening a TLS connection to a pod |
certificate_expiry_monitor_tls_close_connection_error |
ns, pod, domain |
Number of times an error occurred while closing a TLS connection to a pod |
Healthcheck
A simple healthcheck is available at /healthz on the TCP port :8888 (customizable with metricsPort):
→ curl -v http://localhost:8888/healthz
* Trying ::1...
* TCP_NODELAY set
* Connection failed
* connect to ::1 port 8888 failed: Connection refused
* Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8888 (#0)
> GET /healthz HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Mon, 04 Mar 2019 17:56:45 GMT
< Content-Length: 7
< Content-Type: text/plain; charset=utf-8
<
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
Healthy