# Ansible Infrastructure Management

Ansible automation for development machines, service hosts, and **Proxmox-managed guests** (LXC-first, with a path for KVM VMs).

## Quick start

```bash
# Install Python deps + Ansible collections
make bootstrap

# Edit secrets (Proxmox credentials, SSH public key, etc.)
make edit-group-vault

# Validate the repo
make test-syntax
```

## Proxmox app projects (LXC-first)

This repo can provision and configure **dev/qa/prod guests per application project** using the `app_projects` model.

- **Configure projects**: `inventories/production/group_vars/all/main.yml` (`app_projects`)
- **Configure secrets**: `inventories/production/group_vars/all/vault.yml` (encrypted)
- **Run end-to-end**:

```bash
make app PROJECT=projectA
```

Other useful entry points:

- **Provision only**: `make app-provision PROJECT=projectA`
- **Configure only**: `make app-configure PROJECT=projectA`
- **Info / safety**: `make proxmox-info [PROJECT=projectA] [ALL=true] [TYPE=lxc|qemu|all]`

Safety notes:

- **IP conflict precheck**: provisioning fails if the target IP responds
  (override with `-e allow_ip_conflicts=true` only if you really mean it).
- **VMID/CTID collision guardrail**: provisioning fails if the VMID exists but the guest name doesn't match
  (override with `-e allow_vmid_collision=true` only if you really mean it).
- **No destructive playbooks**: this repo intentionally does **not** ship “destroy/decommission” automation.

Docs:

- `docs/guides/app_stack_proxmox.md`
- `docs/guides/app_stack_execution_flow.md`

## Project structure (relevant paths)

```
ansible/
├── Makefile
├── ansible.cfg
├── collections/requirements.yml
├── inventories/production/
│   ├── hosts
│   ├── group_vars/all/
│   │   ├── main.yml
│   │   ├── vault.yml
│   │   └── vault.example.yml
│   └── host_vars/
├── playbooks/
│   ├── app/
│   │   ├── site.yml
│   │   ├── provision_vms.yml
│   │   ├── configure_app.yml
│   │   └── proxmox_info.yml
│   └── site.yml
└── roles/
    ├── proxmox_vm/
    ├── base_os/
    ├── app_setup/
    └── pote/
```

## Documentation

- **Guides**: `docs/guides/`
- **Reference**: `docs/reference/`
- **Project docs (architecture/standards/workflow)**: `project-docs/index.md`