# 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

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