infra-automation/docs/variables.md

Ansible Variables Documentation

Overview

This document provides comprehensive documentation of all global, role-specific, and environment-specific variables used in the Ansible infrastructure automation.

Variable Precedence

Ansible variable precedence (highest to lowest):

1. Extra vars (-e in command line)
2. Task vars (only for the task)
3. Block vars (only for tasks in block)
4. Role and include vars
5. Set_facts / registered vars
6. Include params
7. Role params
8. Play vars_files
9. Play vars_prompt
10. Play vars
11. Host facts / cached set_facts
12. Playbook host_vars
13. Playbook group_vars
14. Inventory host_vars
15. Inventory group_vars
16. Inventory vars
17. Role defaults

Global Variables

inventories/*/group_vars/all.yml

These variables apply to all hosts across all environments.

Variable	Default	Description
ansible_user	ansible	SSH user for automation
ansible_become	true	Use privilege escalation
ansible_python_interpreter	/usr/bin/python3	Python interpreter path

Role-Specific Variables

deploy_linux_vm Role

Location: roles/deploy_linux_vm/defaults/main.yml

Required Variables

Variable	Required	Description
deploy_linux_vm_os_distribution	Yes	Distribution identifier (e.g., ubuntu-22.04, almalinux-9)

VM Configuration

Variable	Default	Description
deploy_linux_vm_name	linux-guest	VM name in libvirt
deploy_linux_vm_hostname	linux-vm	Guest hostname
deploy_linux_vm_domain	localdomain	Domain name (FQDN = hostname.domain)
deploy_linux_vm_vcpus	2	Number of virtual CPUs
deploy_linux_vm_memory_mb	2048	RAM allocation in MB
deploy_linux_vm_disk_size_gb	30	Primary disk size in GB

LVM Configuration

Variable	Default	Description
deploy_linux_vm_use_lvm	true	Enable LVM configuration
deploy_linux_vm_lvm_vg_name	vg_system	Volume group name
deploy_linux_vm_lvm_pv_device	/dev/vdb	Physical volume device

Security Configuration

Variable	Default	Description
deploy_linux_vm_enable_firewall	true	Enable UFW/firewalld
deploy_linux_vm_enable_selinux	true	Enable SELinux (RHEL family)
deploy_linux_vm_enable_apparmor	true	Enable AppArmor (Debian family)
deploy_linux_vm_enable_auditd	true	Enable audit daemon
deploy_linux_vm_enable_automatic_updates	true	Enable automatic security updates
deploy_linux_vm_automatic_reboot	false	Auto-reboot after updates

SSH Hardening

Variable	Default	Description
deploy_linux_vm_ssh_permit_root_login	no	Allow root SSH login
deploy_linux_vm_ssh_password_authentication	no	Allow password authentication
deploy_linux_vm_ssh_gssapi_authentication	no	GSSAPI disabled per requirements
deploy_linux_vm_ssh_max_auth_tries	3	Maximum authentication attempts

system_info Role

Location: roles/system_info/defaults/main.yml

Variable	Default	Description
system_info_stats_base_dir	./stats/machines	Base directory for statistics storage
system_info_create_stats_dir	true	Create stats directory if missing
system_info_gather_cpu	true	Gather CPU information
system_info_gather_gpu	true	Gather GPU information
system_info_gather_memory	true	Gather memory information
system_info_gather_disk	true	Gather disk information
system_info_gather_network	true	Gather network information
system_info_detect_hypervisor	true	Detect hypervisor capabilities
system_info_json_indent	2	JSON output indentation

Environment-Specific Variables

Production (inventories/production/group_vars/all.yml)

# Example production variables
environment_name: production
backup_enabled: true
monitoring_enabled: true
automatic_updates_schedule: "0 2 * * 0"  # Weekly Sunday 2 AM

Staging (inventories/staging/group_vars/all.yml)

# Example staging variables
environment_name: staging
backup_enabled: true
monitoring_enabled: true
automatic_updates_schedule: "0 3 * * *"  # Daily 3 AM

Development (inventories/development/group_vars/all.yml)

# Example development variables
environment_name: development
backup_enabled: false
monitoring_enabled: false
automatic_updates_schedule: "0 4 * * *"  # Daily 4 AM

Variable Naming Conventions

Prefix Convention

All role variables should be prefixed with the role name:

# Good
deploy_linux_vm_vcpus: 4
system_info_gather_cpu: true

# Bad (global namespace pollution)
vcpus: 4
gather_cpu: true

Type Indicators

Use clear variable names that indicate type:

# Boolean
enable_firewall: true
is_production: false

# String
hostname: "webserver01"
domain: "example.com"

# Integer
cpu_count: 4
memory_mb: 8192

# List
allowed_ips:
  - "192.168.1.0/24"
  - "10.0.0.0/8"

# Dictionary
lvm_config:
  vg_name: "vg_system"
  volumes:
    - name: "lv_opt"
      size: "3G"

Sensitive Variables

Ansible Vault

Sensitive variables should be encrypted with Ansible Vault:

# inventories/production/group_vars/all/vault.yml (encrypted)
vault_database_password: "SecurePassword123!"
vault_api_token: "eyJhbGc..."
vault_ssh_private_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

Usage in playbooks:

database_password: "{{ vault_database_password }}"

Encryption:

ansible-vault encrypt inventories/production/group_vars/all/vault.yml

Editing:

ansible-vault edit inventories/production/group_vars/all/vault.yml

Variable Validation

Using assert Module

Validate variables before use:

- name: Validate required variables
  assert:
    that:
      - deploy_linux_vm_os_distribution is defined
      - deploy_linux_vm_os_distribution | length > 0
      - deploy_linux_vm_vcpus > 0
      - deploy_linux_vm_memory_mb >= 1024
    fail_msg: "Required variable validation failed"

Best Practices

1. Use Defaults: Define sensible defaults in roles/*/defaults/main.yml
2. Document Variables: Include description and type in README.md
3. Prefix Role Variables: Avoid namespace collisions
4. Validate Input: Use assert to catch misconfigurations early
5. Encrypt Secrets: Always use Ansible Vault for sensitive data
6. Use Clear Names: Make variable purpose obvious
7. Avoid Hardcoding: Use variables instead of hardcoded values

Related Documentation

• Role Index
• CLAUDE.md Guidelines
• Security Model

---

Document Version: 1.0.0 Last Updated: 2025-11-11 Maintained By: Ansible Infrastructure Team