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

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

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

### Complete Example

```hcl
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.

## CI/CD Pipeline

This module includes a comprehensive CI/CD pipeline that runs:
- **TFLint**: Terraform linting and best practices
- **Tfsec**: Security scanning for Terraform code
- **Checkov**: Compliance and security policy checks
- **Terraform Validate**: Configuration validation
- **SonarQube**: Code quality analysis

The pipeline runs automatically on pushes to master/main and on pull requests.

## 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