Patrick de Ruiter
9c0d389dd3
- Migrated Ansible integration from consul_template to vault_agent - Copied vault_agent role from terraform-vsphere-infra module - Created vault_agent-playbook.yml for deployment - Archived consul_template role as consul_template-legacy - Updated Terraform configuration: - Changed Ansible inventory group from consul_template to vault_agent - Added vault_secret_path variable for vault-agent - Added ssl_certs_dir and ssl_private_dir variables - Formatted all Terraform files - Implemented CI/CD pipeline: - Created .gitea/workflows/pipeline.yaml - Added TFLint, Tfsec, and Checkov security scans - Added Terraform validate step - Added SonarQube integration - Created sonar-project.properties - Documentation updates: - Updated README.md with vault-agent information - Added migration section comparing consul-template vs vault-agent - Updated CLAUDE.md with vault-agent architecture - Added vault-agent configuration examples Why vault-agent over consul-template: - Full AppRole support with role_id/secret_id files - Advanced token auto-renewal with auto_auth - Better credential security (separate files vs config) - Actively developed by HashiCorp Note: The ansible/ directory changes (vault_agent role and playbook) are not committed as the directory is in .gitignore. These files exist locally and will be deployed during Ansible runs.
114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# 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
|
|
}
|
|
``` |