Ansible Vault

Overview

Learn how to securely manage sensitive data using Ansible Vault.

Basic Operations

Creating Encrypted Files

# Create new encrypted file
ansible-vault create secrets.yml

# Encrypt existing file
ansible-vault encrypt existing-secrets.yml

# Create encrypted string for variables
ansible-vault encrypt_string 'secret_password' --name 'db_password'

Vault Structure

# secrets.yml
---
database_credentials:
  username: admin
  password: !vault |
    $ANSIBLE_VAULT;1.1;AES256
    31393839363430346263323736626235633062373930663563353435333766376637
    31393839363430346263323736626235633062373930663563353435333766376637
    31393839363430346263323736626235633062373930663563353435333766376637

ssl_certificates:
  private_key: !vault |
    $ANSIBLE_VAULT;1.1;AES256
    62306536383939363833363736653466366362323336313035633339333233353764
    62306536383939363833363736653466366362323336313035633339333233353764

Advanced Usage

Multiple Vault Passwords

# ansible.cfg
[defaults]
vault_identity_list = [email protected],[email protected]

# Using multiple passwords
ansible-playbook site.yml --vault-id [email protected] --vault-id [email protected]

Vault in Playbooks

# playbook.yml
---
- hosts: webservers
  vars_files:
    - vars/common.yml
    - vars/secrets.yml  # encrypted file

  tasks:
    - name: Configure database
      mysql_user:
        name: "{{ database_credentials.username }}"
        password: "{{ database_credentials.password }}"
        state: present

Vault in Roles

# roles/database/vars/main.yml
---
db_credentials: "{{ lookup('file', 'secrets/db_creds.yml') | from_yaml }}"

# roles/database/tasks/main.yml
---
- name: Set up database
  mysql_db:
    name: "{{ db_credentials.name }}"
    login_user: "{{ db_credentials.user }}"
    login_password: "{{ db_credentials.password }}"

Best Practices

Directory Structure

ansible-project/
├── group_vars/
│   ├── all/
│   │   ├── vars.yml           # Unencrypted vars
│   │   └── vault.yml          # Encrypted vars
│   └── production/
│       ├── vars.yml
│       └── vault.yml
├── host_vars/
│   └── server1/
│       ├── vars.yml
│       └── vault.yml
└── vault-password-file.txt    # Not in version control

Variable Organization

# group_vars/all/vars.yml
---
# Public variables
app_name: myapp
environment: production

# group_vars/all/vault.yml (encrypted)
---
# Sensitive variables
database_password: supersecret
api_key: abcd1234

Security Considerations

Password Management

# Using password files
echo "secretpassword" > ~/.vault_pass
chmod 600 ~/.vault_pass

# Using environment variables
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass

CI/CD Integration

# .gitlab-ci.yml example
deploy:
  script:
    - echo "$VAULT_PASSWORD" > .vault_pass
    - ansible-playbook site.yml --vault-password-file .vault_pass
    - rm .vault_pass

Working with Vault

Editing Encrypted Files

# Edit encrypted file
ansible-vault edit secrets.yml

# View encrypted file
ansible-vault view secrets.yml

# Decrypt file
ansible-vault decrypt secrets.yml

Vault in Templates

# config.j2
database:
  user: {{ db_user }}
  password: {{ vault_db_password }}
  host: {{ db_host }}

Rekey Vault Files

# Change vault password
ansible-vault rekey secrets.yml

# Rekey multiple files
ansible-vault rekey --new-vault-password-file=new_pass.txt *.yml

Troubleshooting

Common Issues

# Check vault format
---
# Must use !vault | for encrypted strings
password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  31393839363430346263323736626235633062373930663563353435333766376637

# Incorrect format
password: $ANSIBLE_VAULT;1.1;AES256
  31393839363430346263323736626235633062373930663563353435333766376637

Debugging Tips

# Test vault access
ansible localhost -m debug -a "var=encrypted_variable" --vault-password-file vault_pass.txt

# Verify file encryption
ansible-vault view --vault-password-file vault_pass.txt secrets.yml

Integration Examples

Using with Docker

# docker-compose.yml
services:
  app:
    environment:
      - DB_PASSWORD={{ lookup('file', '.vault_pass') }}

Using with Kubernetes

# k8s-secrets.yml.j2
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  db-password: {{ vault_db_password | b64encode }}
  api-key: {{ vault_api_key | b64encode }}