Vault Agent: add an explicit API to rotate a selected pkiCert template without restarting
Is your feature request related to a problem? Please describe.
Operators need to explicitly reissue a certificate managed by an individual pkiCert template, render the replacement and run that template's configured exec, without restarting Vault Agent or forcing auto-authentication to acquire a different token.
An external scheduler such as a systemd timer can decide when a certificate is eligible for rotation and when a maintenance window opens. What is missing is an operation that asks the running Agent to perform the rotation. This is a narrower building block for #32101; it does not require implementing a scheduler inside Agent.
Long-lived renewable authentication tokens are intentional in this deployment. Replacing the template runner on frequent reauthentication is not a suitable rotation mechanism, particularly given the outstanding dependency-wait cancellation work in hashicorp/consul-template#2171.
Describe the solution you'd like
An opt-in local Agent API that selects one configured template and requests a forced PKI refresh. For an initial implementation, selecting by the exact configured destination could avoid introducing a new template identifier. The endpoint name and payload are proposals for discussion, not existing configuration:
POST /agent/v1/templates/rotate
Content-Type: application/json
{"destination":"/etc/vault-agent.d/pki_example.rendered"}Expected behavior:
- Interrupt the selected PKI dependency's scheduled wait and request a new certificate using the current auto-auth token.
- Bypass both the in-memory certificate value and the valid certificate in
destinationfor this request; do not require deleting working files. - Deliver the new value through the normal template rendering and
execpath, then resume automatic rotation using the new certificate's lifetime. - Do not recreate the whole template runner, restart Agent, rotate other templates' certificates, or revoke authentication tokens.
- Keep the existing certificate available if issuance fails, and retain the forced-refresh intent across issuance retries.
- Distinguish request acceptance from successful rendering and successful
exec. An initial asynchronous API can return acceptance and use existing logs for completion, provided this limitation is documented. - Disable the endpoint by default and document its local administrative trust boundary, since it can issue certificates and trigger configured commands.
Describe alternatives you've considered
Observed with Vault and Vault Agent 1.21.4, real 2160-hour (90-day) certificates, pkiCert plus a secret lookup for the CA chain, default static-secret interval and renewal threshold 0.9:
| Action | Observation |
|---|---|
Remove destination |
It was recreated after 267 seconds with the original serial; exec ran with the old certificate. No reissue during 330 seconds of observation. |
Remove destination, then send SIGHUP |
Original serial restored after 266 seconds; no reissue during the observation period. |
Restart Agent with destination retained |
Original serial retained. |
Stop Agent, remove destination, start Agent |
New certificate and exec observed after 0.4 seconds. |
Remove destination before AppRole reauthentication |
New certificate and exec after 40 seconds without changing the Agent PID; this test deliberately used a 45-second maximum authentication-token lifetime. |
Remove destination, revoke a one-hour AppRole token |
No new serial during 350 seconds. The CA-chain endpoint remained accessible despite the revoked token, so that fetch did not trigger reauthentication. |
The hook in these experiments recorded the certificate serial rather than reloading a real application. No clock manipulation or shortened certificate lifetime was used. These are 1.21.4 runtime observations; current upstream source was also inspected, but these exact experiments have not been repeated with an upstream-main binary.
/agent/v1/cache-clear addresses the proxy/lease cache rather than explicitly forcing the pkiCert dependency to issue. An independent PKI API call would require a separate implementation of file installation and the template hook, and could race the running Agent's cached value.
Explain any additional use-cases
- Maintenance-window rotation controlled by an external scheduler.
- Explicit replacement after PKI role or certificate parameter changes.
- Targeted operational rotation when one Agent manages several unrelated services.
Additional context
The existing Agent listener and optional Agent API configuration provide the HTTP infrastructure. The dependency wait/cache invalidation also needs a targeted mechanism in Consul Template; merely adding a route or deleting the rendered file would not implement forced issuance.
Relevant code:
- https://github.com/hashicorp/vault/blob/v1.21.4/command/agent.go#L1238-L1274
- https://github.com/hashicorp/vault/blob/v1.21.4/command/agent/template/template.go#L163-L192
- https://github.com/hashicorp/consul-template/blob/v0.41.1/dependency/vault_pki.go
I am preparing a minimal draft implementation of this explicit trigger, with targeted tests for valid 90-day certificates, unchanged token/PID, isolation between destinations, retry behavior, and cancellation.
Source: hashicorp/vault