terraform-certificate-automation/README.md

Terraform Certificate Automation Module

This Terraform module automates TLS certificate deployment by creating Vault AppRole authentication and policies for automated certificate retrieval and renewal.

Purpose

This module sets up the infrastructure needed to automatically fetch and deploy TLS certificates from HashiCorp Vault to target servers using Vault Agent. It creates:

• Vault policies with read-only access to certificate secrets
• AppRole authentication backend configuration
• AppRole credentials for secure authentication
• Ansible inventory entries for automated vault-agent deployment

What It Does

1. Creates Vault Policy: Generates a read-only policy for accessing certificate secrets at a specific path
2. Configures AppRole: Sets up an AppRole with appropriate token TTLs and secret ID expiration
3. Generates Credentials: Creates AppRole role_id and secret_id for authentication
4. Configures Ansible Host: Registers the target server in Ansible inventory with Vault credentials

Prerequisites

• HashiCorp Vault server with AppRole auth method enabled
• Terraform >= 0.13
• Vault provider configured with appropriate credentials
• Ansible provider (for inventory management)

Usage

Basic Example

module "certificate_automation" {
  source = "./terraform-certificate-automation/terraform"

  environment     = "production"
  short_hostname  = "web01"
  vault_address   = "https://vault.example.com:8200"
}

Complete Example

module "certificate_automation" {
  source = "./terraform-certificate-automation/terraform"

  environment     = "prod"
  short_hostname  = "api-server"
  vault_address   = "https://vault.internal.example.com:8200"
}

# Access the generated credentials (sensitive)
output "approle_creds" {
  value     = module.certificate_automation.approle_credentials
  sensitive = true
}

Inputs

Name	Type	Description	Required	Validation
environment	string	Environment name (e.g., dev, staging, prod)	Yes	Alphanumeric, hyphens, and underscores only
short_hostname	string	Short hostname for the target server	Yes	Alphanumeric and hyphens only
vault_address	string	Vault server address	Yes	Must be valid HTTP/HTTPS URL

Outputs

Name	Description	Sensitive
approle_credentials	Object containing role_id and secret_id	Yes

Generated Resources

This module creates the following Vault resources:

• Policy: {environment}-{short_hostname}-cert-policy

  • Path: secret/data/{environment}/{short_hostname}/certificate
  • Capability: read-only

• AppRole: {environment}-{short_hostname}-approle

  • Token TTL: 1 hour
  • Token Max TTL: 4 hours
  • Secret ID TTL: 24 hours

• Ansible Host: Added to vault_agent group with Vault credentials

Secret Path Convention

Certificates are expected to be stored in Vault at:

secret/data/{environment}/{short_hostname}/certificate

Example: secret/data/production/web01/certificate

Token and Secret TTLs

• Token TTL: 1 hour (tokens automatically renew)
• Token Max TTL: 4 hours (maximum lifetime before re-authentication)
• Secret ID TTL: 24 hours (secret_id expires after 24 hours)

Integration with Ansible

This module automatically creates an Ansible inventory entry with:

• Inventory hostname: {short_hostname}
• Group: vault_agent
• Variables:
  • vault_approle_role_id
  • vault_approle_secret_id
  • vault_address
  • vault_secret_path
  • environment
  • short_hostname
  • ssl_certs_dir
  • ssl_private_dir

The generated inventory can be used with the included Ansible playbooks in the ansible/ directory to deploy vault-agent for automated certificate retrieval.

Deployment Steps

1. Deploy Vault AppRoles and policies with Terraform
2. Generate Ansible Vault credentials (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

Security Considerations

• AppRole credentials are marked as sensitive in outputs
• Policies follow the principle of least privilege (read-only)
• Secret IDs are automatically rotated (24-hour TTL)
• Tokens have limited lifetime (max 4 hours)
• Ensure sensitive files (vault_credentials.yml) are always encrypted and handled securely

Related Components

This module works in conjunction with:

• Ansible Playbooks (in ansible/ directory): Deploy vault-agent to target servers
• Vault Agent: Automatically fetches and renews certificates from Vault using AppRole authentication
• Vault KV Secrets Engine: Stores certificates that this module provides access to

Migration from consul-template

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

Feature	consul-template (legacy)	vault-agent (current)
AppRole Auth	❌ Limited support	✅ Full support with role_id/secret_id files
Token Management	⚠️ Basic	✅ Advanced auto_auth
Security	❌ Credentials in config	✅ Separate credential files
Active Development	⚠️ Maintenance mode	✅ Actively developed

The legacy consul-template role is archived as consul_template-legacy for reference.

Notes

• Ensure the Vault AppRole auth backend is enabled before using this module
• The Ansible directory should be ignored when using this as a Terraform module
• Certificate secrets must be manually populated in Vault at the expected path