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. 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 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 consul_template 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: consul_template
• Variables:
  • vault_approle_role_id
  • vault_approle_secret_id
  • vault_address
  • environment
  • short_hostname

The generated inventory can be used with the included Ansible playbooks in the ansible/ directory to deploy consul-template 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 consul-template
4. consul-template automatically fetches and renews certificates from Vault

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 consul-template to target servers
• Consul-Template: Automatically fetches and renews certificates from Vault
• Vault PKI: Stores certificates that this module provides access to

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