Skip to main content

Vault Acme

1. Overview​

ACME (Automatic Certificate Management Environment) is a standardized protocol that automates the issuance, renewal, and revocation of TLS/SSL certificates. Developed by the ISRG (Internet Security Research Group) for Let's Encrypt, ACME allows you to obtain free certificates recognized by all modern web browsers.

The ACME protocol works by domain validation using different methods:

  • HTTP-01: validation by accessible web file
  • DNS-01: validation by DNS TXT record
  • TLS-ALPN-01: validation by temporary certificate

Our implementation uses the DNS-01 method with Cloudflare to generate wildcard certificates (*.domain.com) and automatically store them in Vault for secure distribution within the infrastructure.

2. Advantages​

  • Free and automatically renewed certificates
  • Support for wildcard certificates
  • Validation without service interruption
  • Native integration with Vault
  • Compliance with security standards

3. Vault Integration with ACME​

Vault can be integrated with ACME in several ways depending on architectural needs:

3.1 External Script with Vault Storage​

Our current implementation uses acme.sh externally to generate certificates and then store them in Vault via the KV v2 API. This approach offers:

  • Flexibility in choosing the ACME client
  • Granular control over the generation process
  • Ability to customize business logic
  • Integration with external monitoring systems

3.2 Vault PKI Secrets Engine with ACME​

Vault Enterprise offers a PKI Secrets Engine with native ACME support:

  • Direct configuration of an ACME endpoint in Vault
  • Automatic management of certificate lifecycle
  • Native integration with Vault policies
  • RESTful API for certificate management

3.3 Vault Agent with Templates​

Use Vault Agent to automate retrieval and deployment:

  • Automatic templates for certificate files
  • Transparent certificate rotation
  • Integration with system services (systemd, etc.)
  • Management of file permissions and ownership

3.4 Vault CSI Provider (Kubernetes)​

For containerized environments:

  • Automatic mounting of certificates as volumes
  • Synchronization with Kubernetes Secrets
  • Automatic rotation without pod restart
  • Integration with cert-manager for orchestration

3.5 Webhook and Automation​

Webhook mechanism to trigger actions:

  • Automatic notification upon renewal
  • Triggering application redeployments
  • Integration with CI/CD systems
  • Centralized audit and logging

3. Vault with ACME.sh​

Having tested possibilities with acme and vault, I focused on using acme.sh, a library that generates certificates with certificate servers like Let's Encrypt. For my needs, I developed a Python script to execute acme.sh and register my certificates in Vault, then automate certificate renewal via crontab.

3.1. IAC - Ansible​

Playbook to create a role for generating a certificate and a Vault user​

- name: Configure Vault PKI
  hosts: ['vault-1']
  become: true
  user: supervisor
  roles:
    - role: vault/api
      vars:
        action: create.role
        register: "vault_roles"
        name: "certs_generator"

    - role: vault/api
      vars:
        action: create.user
        register: "vault_users"
        name: "acme"

Playbook to Install the certificate generator and automation script - crontab​

cronplan:
  acme.sh:
    minute: "0"
    hour: "7"
# Playbook
- name: Install ACME
  hosts: ['vault-1']
  user: supervisor
  roles:
    - role: pki/acme
      vars:
        domain: "boxtocloud.app"

Playbook to distribute certificates to other machines​

The certificates in question will be used by other machines that will clone them at each renewal via a cloning script that listens for changes by periodically querying Vault.

# inventories/protobox/group_vars/traffic-plane/crontab.yml
cronplan:
  clonekv:
    minute: "0"
    hour: "8"
- name: Automate boxtocloud.app cloning
  hosts: ['traffic-plane']
  user: supervisor
  roles:
    - role: vault/scripts
      vars:
        svc: "boxtocloud.app"
        script: "clonekv"