[NEW] Add certificate expiration tracking (in days/hours)

[YiwenZhang12]

The problem/use-case that the feature addresses

Valkey currently doesn’t expose TLS certificate expiration time. Once a certificate expires, clients lose connectivity and outages can occur without early warning.

• Certificate expiration is checked automatically, but there’s no proactive monitoring or notification.

• Administrators have no way to see when client certificates will expire until connections start failing.

• There are no built-in commands to expose certificate expiration information.

Having visibility into expiration in days/hours would allow operators to alert and renew certificates proactively. We’ve already seen a real customer case where this visibility could have prevented an incident.

Description of the feature

Expose certificate expiration information in days and hours. Optionally, emit warnings or metrics when approaching configurable thresholds (e.g., 7 days, 24 hours). This enables monitoring systems to trigger alerts before expiry impacts users.

Alternatives you've considered

• Client-side checks: Not all client libraries expose certificate metadata; inconsistent and hard to scale.

• External scripts/tools: Adds maintenance overhead and lacks integration with Valkey’s internal metrics.

• Manual tracking: Error-prone and not tied to the live deployment state.

Additional information

This feature improves operability and reliability by enabling early detection of expiring certificates. It complements existing metrics for verification failures or expired cert errors, shifting monitoring from reactive to proactive. If this proposal is approved, I’m happy to proceed with the implementation and contribute the initial version.

[zuiderkwast]

Can you suggest an API for this? Suggest names of configs, commands, logging, etc.

[YiwenZhang12]

Can you suggest an API for this? Suggest names of configs, commands, logging, etc.

Sure, here is a possible approach: @zuiderkwast

Config

• tls_server_cert_warning_days (default: 7) days before expiration to start warning.

Scheduler

• Use run_with_period() inside serverCron() for hourly checks, following the pattern of other periodic background tasks.

INFO exposure Expose only monitoring-relevant fields, similar to other INFO sections:

tls_server_cert_expires_at_unix_millis: 1767148799000
tls_server_cert_expires_in_seconds: 2592000
tls_server_cert_warning_status: valid | expiring | expired

Logging Emit logs only on state transitions to reduce noise:

At startup (initListeners() after TLS config): "TLS server certificate expires on [ISO8601 date] "

Transition to “expiring” (<7d(default) and >0): "TLS server certificate expiring in N days"

Transition to “expired”: "TLS server certificate has EXPIRED"

Example INFO TLS output

# TLS
tls_enabled:yes
tls_server_cert_expires_at_unix_millis:1767148799000
tls_server_cert_expires_in_seconds:2592000
tls_server_cert_warning_status:valid

I can start implementing this approach once there’s consensus on the design.

[zuiderkwast]

I like these ideas, but do we really need a config? What's the harm in always enabling these INFO fields and log messages?

Maybe 3 INFO fields is too much. They all show the same information in different ways. How about only including one field tls_server_cert_expires_in_seconds and if it's negative, it means that the cert has already expired?

@madolson Any opinion about this API?

[YiwenZhang12]

@zuiderkwast

Thanks for the feedback! The simplification sounds good to me, I’ll drop the config and consolidate the INFO output into one field. I’ll get a PR out shortly.

[YiwenZhang12]

I’ve opened a PR for this: https://github.com/valkey-io/valkey/pull/2913. Feedback is welcome!