terraform-certificate-automation/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a Terraform module for automated TLS certificate deployment using Vault, vault-agent, Terraform, and Ansible. The module creates Vault AppRole authentication and policies, then deploys vault-agent via Ansible to automatically fetch and deploy certificates from Vault.

Note: This module has been migrated from consul-template to vault-agent for better AppRole support and improved security.

Architecture

Terraform Configuration (terraform/)

• main.tf: Creates Vault policies, AppRole authentication, and Ansible inventory
• variables.tf: Defines environment and short_hostname variables
• outputs.tf: Outputs sensitive AppRole credentials (role_id and secret_id)
• backend.tf, provider.tf, data.tf: Standard Terraform configuration files

Ansible Configuration (ansible/)

• vault_agent-playbook.yml: Main playbook that deploys vault-agent
• roles/vault_agent/: Ansible role for vault-agent installation and configuration
  • Downloads and installs vault binary from HashiCorp releases
  • Creates systemd service for vault-agent
  • Configures AppRole authentication with role_id/secret_id files
  • Deploys certificate templates for automatic renewal
• roles/consul_template-legacy/: Archived legacy consul-template role (for reference)
• collections/: Contains Ansible collections (cloud.terraform, community.crypto, etc.)

Key Components

• Vault Integration: Uses AppRole authentication for secure certificate access
• Certificate Templates: Automatically fetches certificates, private keys, and certificate chains
• System Integration: Configures systemd service and file permissions for certificate deployment

Common Commands

Terraform Operations

cd terraform/
terraform init
terraform plan
terraform apply
terraform destroy

Ansible Operations

cd ansible/
ansible-playbook -i inventory.yml vault_agent-playbook.yml

Certificate Template Files

• certificate.tpl: Certificate template (fullchain)
• private_key.tpl: Private key template
• chain_pem.tpl: Certificate chain template

Note: Template files are dynamically generated by the vault_agent role during deployment.

Security Considerations

• AppRole credentials are marked as sensitive in Terraform outputs
• Certificate files are deployed with restricted permissions (600)
• Vault policies follow principle of least privilege (read-only access to specific secret paths)
• Ansible Vault should be used for encrypting sensitive variables (vault_credentials.yml)

Module Usage Pattern

1. Deploy Vault AppRoles and policies with Terraform
2. Generate Ansible Vault credentials using ansible_vault_output.sh
3. Run Ansible playbook to deploy vault-agent: ansible-playbook vault_agent-playbook.yml
4. vault-agent automatically fetches and renews certificates from Vault using AppRole authentication

Why Vault-Agent?

This module migrated from consul-template to vault-agent for several reasons:

Feature	consul-template	vault-agent
AppRole Authentication	❌ Limited support	✅ Full support with role_id/secret_id files
Token Auto-Renewal	⚠️ Basic	✅ Advanced with auto_auth
Credential Storage	❌ In config file	✅ Separate secure files
Active Development	⚠️ Maintenance mode	✅ Actively developed

vault-agent Configuration

vault-agent uses AppRole auto_auth:

auto_auth {
  method "approle" {
    mount_path = "auth/approle"
    config = {
      role_id_file_path = "/etc/vault-agent/role_id"
      secret_id_file_path = "/etc/vault-agent/secret_id"
    }
  }

  sink "file" {
    config = {
      path = "/opt/vault-agent/vault-token"
    }
  }
}

Certificate templates automatically fetch secrets from Vault:

template {
  source = "/etc/vault-agent/certificate.tpl"
  destination = "/etc/ssl/certs/hostname.crt"
  perms = 0644
  command = "systemctl reload nginx"  # Service-specific reload
}