ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/roles/proxmox_vm
History
ilia c3e6caf9e8
All checks were successful
CI / skip-ci-check (push) Successful in 1m18s
Details
CI / lint-and-test (push) Successful in 1m23s
Details
CI / ansible-validation (push) Successful in 3m2s
Details
CI / secret-scanning (push) Successful in 1m19s
Details
CI / dependency-scan (push) Successful in 1m24s
Details
CI / sast-scan (push) Successful in 2m32s
Details
CI / license-check (push) Successful in 1m23s
Details
CI / vault-check (push) Successful in 2m22s
Details
CI / playbook-test (push) Successful in 2m25s
Details
CI / container-scan (push) Successful in 1m51s
Details
CI / sonar-analysis (push) Successful in 2m32s
Details
CI / workflow-summary (push) Successful in 1m17s
Details
refactor-servers-workstations-shell-monitoring (#4) 
### Summary

This PR refactors the playbook layout to reduce duplication and make host intent clearer (servers vs workstations), splits monitoring by host type, and restores full Zsh setup for developers while keeping servers aliases-only.

### Key changes

- **New playbooks**
  - `playbooks/servers.yml`: baseline for server-class hosts (no desktop apps)
  - `playbooks/workstations.yml`: baseline for dev/desktop/local + **desktop apps only on `desktop` group**

- **Monitoring split**
  - `roles/monitoring_server`: server monitoring + intrusion prevention (includes `fail2ban`, sysstat)
  - `roles/monitoring_desktop`: desktop-oriented monitoring tooling
  - Updated playbooks to use the correct monitoring role per host type

- **Shell role: server-safe + developer-friendly**
  - `roles/shell` now supports two modes:
    - `shell_mode: minimal` (default): aliases-only, does not overwrite `.zshrc`
    - `shell_mode: full`: installs Oh My Zsh + Powerlevel10k + plugins and deploys a managed `.zshrc`
  - `playbooks/development.yml` and `playbooks/workstations.yml` use `shell_mode: full`
  - `playbooks/servers.yml` remains **aliases-only**

- **Applications**
  - Applications role runs only on `desktop` group (via `workstations.yml`)
  - Removed Brave installs/repo management
  - Added **CopyQ** to desktop apps (`applications_desktop_packages`)

- **Docs + architecture**
  - Added canonical doc tree under `project-docs/` (overview/architecture/standards/workflow/decisions)
  - Consolidated architecture docs: `docs/reference/architecture.md` is now a pointer to `project-docs/architecture.md`
  - Fixed broken doc links by adding the missing referenced pages under `docs/`

### Behavior changes (important)

- Desktop GUI apps install **only** on the `desktop` inventory group (not on servers, not on dev VMs unless they are in `desktop`).
- Dev/workstation Zsh is now provisioned in **full mode** (managed `.zshrc` + p10k).

### How to test (local CI parity)

```bash
make test
npm test
```

Optional dry runs (interactive sudo may be required):

```bash
make check
make check-local
```

### Rollout guidance

- Apply to a single host first:
  - Workstations: `make workstations HOST=<devhost>`
  - Servers: `make servers HOST=<serverhost>`
- Then expand to group runs.

Reviewed-on: #4
2026-01-01 22:11:24 -05:00
..
defaults
Add POTE app project support and improve IP conflict detection (#3)
2026-01-01 11:19:54 -05:00
tasks
refactor-servers-workstations-shell-monitoring (#4)
2026-01-01 22:11:24 -05:00
README.md
Add POTE app project support and improve IP conflict detection (#3)
2026-01-01 11:19:54 -05:00

README.md

Role: proxmox_vm

Provision Proxmox guests via API. This role supports both:

  • LXC containers (proxmox_guest_type: lxc) via community.proxmox.proxmox
  • KVM VMs (proxmox_guest_type: kvm) via community.general.proxmox_kvm

The entry point is roles/proxmox_vm/tasks/main.yml, which dispatches to tasks/lxc.yml or tasks/kvm.yml.

Requirements

  • Ansible (project tested with modern Ansible; older 2.9-era setups may need adjustments)
  • Proxmox VE API access
  • Collections:
    • community.proxmox
    • community.general (for proxmox_kvm)
  • Python lib on the control machine:
    • proxmoxer (installed by make bootstrap / requirements.txt)

Authentication (vault-backed)

Store secrets in inventories/production/group_vars/all/vault.yml:

  • vault_proxmox_host
  • vault_proxmox_user
  • vault_proxmox_password (or token auth)
  • vault_proxmox_token_id (optional)
  • vault_proxmox_token (optional)
  • vault_ssh_public_key (used for bootstrap access where applicable)

Key variables

Common:

  • proxmox_guest_type: lxc or kvm
  • proxmox_host, proxmox_user, proxmox_node
  • proxmox_api_port (default 8006)
  • proxmox_validate_certs (default false)

LXC (tasks/lxc.yml):

  • lxc_vmid, lxc_hostname
  • lxc_ostemplate (e.g. local:vztmpl/debian-12-standard_*.tar.zst)
  • lxc_storage (default local-lvm)
  • lxc_network_bridge (default vmbr0)
  • lxc_ip (CIDR), lxc_gateway
  • lxc_cores, lxc_memory_mb, lxc_swap_mb, lxc_rootfs_size_gb

KVM (tasks/kvm.yml):

  • vm_id, vm_name
  • vm_cores, vm_memory, vm_disk_size
  • vm_storage, vm_network_bridge
  • cloud-init parameters used by the existing KVM provisioning flow

Safety guardrails

LXC provisioning includes a VMID collision guardrail:

  • If the target VMID already exists but the guest name does not match the expected name, provisioning fails.
  • Override only if you really mean it: -e allow_vmid_collision=true

Example usage

Provisioning is typically orchestrated by playbooks/app/provision_vms.yml, but you can call the role directly:

- name: Provision one LXC
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Create/update container
      ansible.builtin.include_role:
        name: proxmox_vm
      vars:
        proxmox_guest_type: lxc
        lxc_vmid: 9301
        lxc_hostname: projectA-dev
        lxc_ip: "10.0.10.101/24"
        lxc_gateway: "10.0.10.1"