Automate certificates with Vault Agent and PKI external CA

Vault Agent can act as an ACME client for public certificate authorities, automating the full certificate lifecycle without manual operator intervention. When Agent issues or renews a certificate, it automatically re-renders any templates that reference it.

Requirements

• Vault Enterprise v2.0.0 or later
• A Vault PKI external CA secrets engine mount configured for ACME workflows. Refer to PKI external CA secrets engine for setup instructions.
• The agent's auth method must grant update access to the PKI mount's acme/* paths and the target roles/<role>/acme/ paths.
• For HTTP-01 challenges: either a writable filesystem path served by an existing web server, or a free TCP port for Agent to bind a temporary listener on.

Configuration

Add one or more pki_external_ca stanzas to your Agent configuration file. Each block must have a unique label that you reference in templates.

Minimal example (HTTP-01 with shared challenge path)

The following example uses an existing web server to serve the ACME HTTP-01 challenge files:

vault {
  address = "https://vault.example.com:8200"
}

auto_auth {
  method "kubernetes" {
    config {
      role = "my-app"
    }
  }
}

pki_external_ca "web-tls" {
  mount_path     = "pki"
  role           = "web-server"
  challenge_type = "http-01"

  identifiers {
    dns = ["app.example.com"]
  }

  http_01 {
    challenge_path = "/var/www/html/.well-known/acme-challenge"
  }

  destination {
    path       = "/etc/certs"
    pem_bundle = false
  }
}

template {
  destination = "/etc/nginx/tls/app.crt"
  contents    = <<-EOT
    {{ with pkiCertExternalCa "web-tls" -}}
    {{ .Certificate }}
    {{- end }}
  EOT
}

Full example (explicit CSR with RSA key)

The following example uses an explicit CSR with a 2048-bit RSA key. Agent binds a temporary HTTP listener on port 8402 to serve the ACME challenge:

pki_external_ca "internal-api" {
  mount_path                  = "pki-internal"
  role                        = "api-server"
  namespace                   = "team-a"
  challenge_type              = "http-01"
  percent_renew_before_expiry = 30

  csr {
    CN  = "api.internal.example.com"
    C   = "US"
    ST  = "California"
    L   = "San Francisco"
    O   = "Example Corp"
    OU  = "Engineering"
    SANs = ["api.internal.example.com", "api-v2.internal.example.com"]

    private_key {
      rsa {
        bits = 2048
      }
    }
  }

  http_01 {
    listener_addr = "0.0.0.0:8402"
  }

  destination {
    path            = "/etc/pki/api"
    pem_bundle      = true
    filename_prefix = "bundle"
    umask           = "077"
  }
}

pki_external_ca stanza reference

¹ Exactly one of identifiers or csr is required.

identifiers block

csr block

csr.private_key block

Exactly one of rsa or ecdsa is required.

rsa sub-block

ecdsa sub-block

http_01 block

Exactly one of challenge_path or listener_addr is required.

destination block

Template function: pkiCertExternalCa

Use the pkiCertExternalCa template function to access certificate data for a named pki_external_ca block. The function accepts exactly one argument: the block label.

{{ pkiCertExternalCa "" }}

The return value is an object whose fields match the Vault PKI issue response, including .Certificate, .PrivateKey, and .IssuingCA. If the certificate has not been issued yet, the function returns nil. Use a {{ with }} block to guard against this during agent startup:

template {
  destination = "/etc/app/tls.crt"
  contents    = <<-EOT
    {{ with pkiCertExternalCa "web-tls" -}}
    {{ .Certificate }}
    {{ .IssuingCA }}
    {{- end }}
  EOT
}

template {
  destination = "/etc/app/tls.key"
  contents    = <<-EOT
    {{ with pkiCertExternalCa "web-tls" -}}
    {{ .PrivateKey }}
    {{- end }}
  EOT
}

Automatic template re-render

When any pki_external_ca block issues or renews a certificate, Agent restarts its template rendering runner. All templates that call pkiCertExternalCa re-render automatically — no polling or manual restart is required.

Considerations

• Block labels must be unique across all pki_external_ca stanzas in a single agent configuration file.
• Destination path values must be unique and must point to existing directories. Agent does not create them.
• The default umask of 077 means only the agent process owner can read the written key files.
• percent_renew_before_expiry is evaluated against the remaining TTL of the certificate. A value of 20 triggers renewal when 20% of the certificate's lifetime remains.