# 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
```bash
cd terraform/
terraform init
terraform plan
terraform apply
terraform destroy
```

### Ansible Operations
```bash
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:

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

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