# 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`)

```yaml
# 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`)

```yaml
# 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`)

```yaml
# 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:

```yaml
# 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:

```yaml
# 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:

```yaml
# 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**:
```yaml
database_password: "{{ vault_database_password }}"
```

**Encryption**:
```bash
ansible-vault encrypt inventories/production/group_vars/all/vault.yml
```

**Editing**:
```bash
ansible-vault edit inventories/production/group_vars/all/vault.yml
```

## Variable Validation

### Using assert Module

Validate variables before use:

```yaml
- 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](./roles/role-index.md)
- [CLAUDE.md Guidelines](../CLAUDE.md)
- [Security Model](./architecture/security-model.md)

---

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