Webhook icon
Schedule icon
Script icon
Process icon
If icon
Pause icon
SlackIncomingWebhook icon
Log icon

Rotate Vault PKI Certificates Without Moving Private Keys

Sign workload CSRs in Vault PKI, verify the CA chain and DNS identity, and publish approved certificates with KV v2 compare-and-set.

Categories
CloudInfrastructure

Workload certificate renewal should not put a private key in an orchestration log or silently overwrite a certificate changed by another operator. This blueprint reads an externally generated CSR, signs it through a restricted Vault PKI role, verifies the resulting certificate against an out-of-band CA fingerprint, and uses KV v2 compare-and-set for publication. The workload keeps its private key and watches the active KV record for the public certificate.

How it works

  1. csr_ready_webhook accepts an event after a workload publishes a CSR; the disabled daily_expiry_sweep is an optional backstop.
  2. validate_request checks all paths, DNS name, TTL, and CA fingerprint before an external request.
  3. inspect_certificate reads the active KV v2 version, checks its expiry and DNS name, and verifies the CSR signature when rotation is due. A healthy certificate produces no write and no Slack message.
  4. approve_rotation (Pause) defaults to rejection. Approval pins the active and CSR KV versions observed before the pause.
  5. sign_verify_publish rechecks both versions after approval, pins Vault's CA against the supplied SHA-256 digest, signs the CSR once, verifies chain, DNS name, public-key match, and remaining validity, then publishes through KV v2 CAS and reads the result back.
  6. notify_rotation reports the new serial only after a successful readback. The consumer must reload the public certificate and verify its live TLS endpoint; this flow does not deploy it.

Error handling

  • Bad inputs, missing or malformed CSR, wrong CA pin, bad chain, wrong DNS name, public-key mismatch, and short-lived signed leaves fail closed.
  • Read-only Vault calls retry transient network and 429/5xx errors with exponential backoff. Signing and KV writes are never blindly retried because a lost response can hide a completed side effect.
  • Both the active version and CSR digest are checked after approval. KV v2 CAS also rejects a concurrent writer between the final read and publish.
  • errors sends an actionable Slack alert with the failed task and cause. The active record remains inspectable; a failed readback requires checking Vault before any retry.

What this blueprint teaches about Kestra

  • A webhook and disabled Schedule can share an expiry decision. If keeps the no-change path quiet, Pause records human approval, and script output carries the pinned KV versions between steps.
  • A single final script can verify and publish with an external compare-and-set primitive, without putting certificate private keys in Kestra's inputs or outputs.

Prerequisites

  • Vault with a PKI mount, a restricted sign role for the DNS name, and a KV v2 mount reachable by the Kestra worker. The token needs read on the CSR and active KV keys, create/update on the active key, read on the PKI CA, and update on the sign role.
  • A workload-generated PEM CSR in secret/data/cert-requests/service under the csr field. Its private key stays outside Kestra. Consumers read secret/data/certificates/service and reload the public certificate after a version change.
  • Python 3 and OpenSSL on the Kestra worker, a Slack incoming webhook, and a trusted root fingerprint obtained out of band.

Secrets

  • VAULT_TOKEN: a narrowly scoped Vault token, supplied as a Kestra secret.
  • SLACK_WEBHOOK_URL: Slack webhook for successful rotations and operational failures.

Inputs

  • vault_url, pki_mount, pki_role, kv_mount, csr_path, and active_path locate the Vault records.
  • dns_name, trusted_root_sha256, renew_before_hours, and certificate_ttl define the security gate and timing. The CA pin is deliberately unset by default.
  • force_rotate allows a planned or incident-driven renewal of an otherwise healthy certificate, still behind approval.

Outputs

  • inspection contains the due reason, current KV version, serial, and CSR version. rotation contains the new serial and KV version only after a verified publication. The KV record contains only public certificate material and metadata, never a private key.

Quick start

  1. Start Vault dev mode on a private Docker network, enable a pki mount, generate a test root, configure a web role restricted to service.example.test, and use the dev secret KV v2 mount.
  2. Generate the workload key and CSR outside Kestra; write only the CSR to secret/data/cert-requests/service. Compute SHA-256 from the trusted root certificate DER out of band.
  3. Set the two Kestra secrets, supply the CA digest in trusted_root_sha256, run the flow, inspect the inspection output, and resume the Pause with approved=true only after review.
  4. Read secret/data/certificates/service and have the workload reload that public certificate. Check the live TLS endpoint separately before retiring its previous certificate.

Plugins used

  • io.kestra.plugin.scripts.python.Script for input checks and Vault PKI/KV calls, using the Process runner and Python standard library.
  • io.kestra.plugin.slack.notifications.SlackIncomingWebhook for one success message and operational error alerts.
  • Kestra core Webhook, Schedule, If, Pause, and Log tasks for event and human-controlled orchestration.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.