Configuring Ansible within a Devbox Environment¶

Assuming you have set up a Devbox environment (as described in our Devbox Setup Guide), this guide focuses on configuring Ansible within that environment, including project structure, using Ansible Vault for secrets management, and writing a simple playbook.

Setting Up Your Project Structure¶

With your Devbox environment ready (including Ansible installed via requirements.txt), let's set up a standard Ansible project structure:

# Ensure you are inside your devbox shell
mkdir -p playbooks roles inventory group_vars host_vars
touch ansible.cfg

Create a basic ansible.cfg file to configure Ansible's behavior:

[defaults]
inventory = ./inventory
roles_path = ./roles
host_key_checking = False
vault_password_file = ./.vault_pass.txt

[privilege_escalation]
become = True
become_method = sudo
become_ask_pass = False

This configuration tells Ansible where to find inventory and roles, disables SSH host key checking (useful for local/dev environments, use with caution), and points to a file containing the Ansible Vault password.

Working with Ansible Vault¶

Ansible Vault is a feature that allows you to keep sensitive data such as passwords or keys encrypted rather than in plaintext. Let's set it up:

Create a vault password file (make sure to add this to your .gitignore):
```
pwgen -ys 14 1 > .vault_pass.txt
chmod 600 .vault_pass.txt
```
To generate a random password, use pwgen. In the command above, "y" generates a secure password, "s" is responsible for symbols in the password, "14" is the length of the password, and "1" at the end helps generate only one password.

Creating encrypted variables:

ansible-vault create group_vars/all/vault.yml

This will open an editor where you can add sensitive variables:

vault_db_password: supersecretpassword
vault_api_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
vault_ssh_private_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn
  ...
  -----END OPENSSH PRIVATE KEY-----

Referencing vault variables in your playbooks: Create group_vars/all/vars.yml for non-sensitive variables that reference vault values:
```
# Public variable that uses vault values
db_password: "{{ vault_db_password }}"
api_token: "{{ vault_api_token }}"
```

Editing encrypted files:

ansible-vault edit group_vars/all/vault.yml

Encrypting strings for use in playbooks:
```
ansible-vault encrypt_string 'secret_value' --name 'encrypted_variable'
```
This outputs an encrypted variable you can paste directly into YAML files.

Security Best Practice

Never commit .vault_pass.txt to your repository. Add it to your .gitignore file and share the password through a secure channel like a password manager.

Advanced: Using Multiple Vault Passwords¶

For complex projects, you might need different vault passwords for different environments:

Create an identity file instead of a single password:

# Create vault ID file for dev
pwgen -ys 14 1 > .vault_pass_dev.txt
chmod 600 .vault_pass_dev.txt

# Create vault ID file for prod
pwgen -ys 14 1 > .vault_pass_prod.txt
chmod 600 .vault_pass_prod.txt

Update ansible.cfg to use multiple vault IDs:

[defaults]
# Other settings...
vault_identity_list = dev@.vault_pass_dev.txt, prod@.vault_pass_prod.txt

Creating environment-specific encrypted files:

# Encrypt with dev identity
ansible-vault create --vault-id dev@.vault_pass_dev.txt group_vars/dev/vault.yml

# Encrypt with prod identity
ansible-vault create --vault-id prod@.vault_pass_prod.txt group_vars/prod/vault.yml

Creating a Simple Playbook¶

Let's create a simple playbook to test our Ansible setup within the Devbox environment:

# Create a playbook file
touch playbooks/test.yml

Edit playbooks/test.yml:

---
- name: Test Playbook
  hosts: localhost
  connection: local
  gather_facts: yes

  vars:
    message: "Hello from Ansible in Devbox!"

  tasks:
    - name: Print message
      debug:
        msg: "{{ message }}"

    - name: Show Python version used by Ansible
      command: python --version
      register: python_version

    - name: Display Python version
      debug:
        msg: "Ansible is using Python: {{ python_version.stdout }}"

Run the playbook from within your devbox shell:

ansible-playbook playbooks/test.yml

You should see output confirming the message and the Python version (matching the one specified in your devbox.json).

Troubleshooting Common Issues¶

SSH Key Issues¶

If Ansible fails to connect to remote hosts via SSH:

Ensure your SSH key is added to the SSH agent

eval $(ssh-agent)
ssh-add ~/.ssh/your_private_key # Replace with your key path

Verify SSH connectivity outside of Ansible
```
ssh user@your_host
```
Check Ansible inventory for correct hostnames/IPs and SSH users/ports
```
cat inventory/your_inventory_file
```

Test Ansible ping module

ansible -i inventory/your_inventory_file -m ping your_host_or_group

Vault Decryption Problems¶

If you're seeing "Decryption failed" errors when running playbooks:

# Verify vault password file permissions are correct (readable only by user)
chmod 600 .vault_pass.txt

# Manually test decryption using the vault password file
ansible-vault view group_vars/all/vault.yml

# If using multiple vault IDs, ensure the correct ID is specified or available
ansible-vault view --vault-id dev@.vault_pass_dev.txt group_vars/dev/vault.yml

Ensure the vault_password_file path in ansible.cfg is correct relative to where you run ansible-playbook.