Security: document WEED_TLS_CERT_REFRESH_INTERVAL for tuning refresh window

Added a user-facing env var that overrides the 5h default refresh cadence
for both gRPC mTLS and HTTPS cert reloading, for operators running short-
lived certs (Vault, cert-manager with 24h leaves, etc.).
Chris Lu committed 2026-04-21 19:37:13 -07:00
1 parent b6b9aea26b
commit 99ac64d9e6
1 file changed
+11 -1
+11 -1
@@ -260,7 +260,17 @@ New TLS handshakes pick up the rotated cert. In-flight connections keep the cert
**CA rotation caveat.** Only leaf cert/key pairs hot-reload. CA bundles (`[grpc.ca]`, `[https.*.ca]`, `[https.client.ca]`) are loaded once at startup. In k8s, cert-manager typically rotates leaf certs far more often than CAs — if your CA rolls, you still need a rolling restart.
**How it works.** A `GetCertificate` callback is wired into every server-side `tls.Config`. Under the hood it's backed by gRPC's `pemfile.NewProvider`, which stats the cert/key files on its refresh tick and re-parses them only when `mtime` or contents change. The refresh interval is `security.CredRefreshingInterval` (currently 5 hours). To shorten it, fork and change that constant — a flag for this is a reasonable future addition.
**How it works.** A `GetCertificate` callback is wired into every server-side `tls.Config`. Under the hood it's backed by gRPC's `pemfile.NewProvider`, which stats the cert/key files on its refresh tick and re-parses them only when `mtime` or contents change. The default refresh interval is 5 hours.
**Tuning the refresh window.** Set the environment variable `WEED_TLS_CERT_REFRESH_INTERVAL` (accepts any `time.ParseDuration` value, e.g. `30m`, `5m`, `500ms`) on every `weed` process that should pick up rotations faster. Useful with short-lived certs (Vault, cert-manager with `duration: 24h`, etc.). Example:
```yaml
env:
- name: WEED_TLS_CERT_REFRESH_INTERVAL
value: "1m"
```
The same env var tunes both gRPC mTLS and HTTPS reload.
**Requirements for hot reload to work:**