# PGS

`pve-guests-state` este utilitarul manual pentru suspendarea si restaurarea guest-urilor Proxmox inainte si dupa lucrari de mentenanta.

Modelul suportat este deliberat simplu:
- `pgs suspend` se ruleaza manual inainte de mentenanta
- `pgs resume` se ruleaza manual dupa revenirea stabila a clusterului
- `pgs cleanup` poate fi rulat manual pentru audit sau cleanup al artefactelor stale de suspend

Automatizarea prin systemd pentru shutdown si boot a fost abandonata intentionat. Contextul complet este in [docs/DECISIONS.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/docs/DECISIONS.md).

## Capabilitati

- suspend to disk pentru VM-uri QEMU care ruleaza
- graceful shutdown pentru containere LXC care ruleaza
- resume pentru VM-urile salvate in state
- start pentru containerele salvate in state
- cleanup pentru stale suspend images
- cleanup pentru volume orphan `vm-*-state-suspend-YYYY-MM-DD.raw`
- retry pentru anumite erori legate de quorum
- dry-run pentru verificare fara efecte

## Layout proiect

- [bin/pgs](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/bin/pgs) - comanda principala
- [scripts/install.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/scripts/install.sh) - instalare locala pe host
- [scripts/uninstall.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/scripts/uninstall.sh) - uninstall canonic
- [setup.sh](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/setup.sh) - wrapper local/remote
- [docs/TECHNICAL.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/docs/TECHNICAL.md) - detalii tehnice
- [systemd/README.md](/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/cluster/projects/pve-guests-state/systemd/README.md) - statusul unitatilor legacy

## Locatii instalate pe host

- comanda operatorului: `/usr/local/sbin/pgs`
- uninstall canonic: `/usr/local/lib/xdev/pve-guests-state/uninstall.sh`
- wrapper optional pentru uninstall: `/usr/local/sbin/xdev-pve-guests-state-uninstall`
- documentatie instalata: `/usr/local/share/doc/xdev/pve-guests-state`
- state runtime: `/var/lib/xdev/pve-guests-state/pgs-state.json`

Compatibilitate:
- la primul run, daca exista vechiul state file `/var/lib/pve-manager/pgs-state.json`, acesta este migrat automat in locatia noua
- installerul si uninstallerul curata si artefactele istorice `pve-reboot-manager.sh` si `pve-guest-state.sh`

## Flux rapid

```bash
# instalare locala
sudo ./setup.sh --local

# test
/usr/local/sbin/pgs suspend --dry-run -v
/usr/local/sbin/pgs cleanup --dry-run -v

# suspend inainte de mentenanta
/usr/local/sbin/pgs suspend -v

# resume dupa revenirea clusterului
/usr/local/sbin/pgs resume -v

# cleanup manual al artefactelor stale/orphan
/usr/local/sbin/pgs cleanup -v
```

## Instalare si uninstall

Instalare:

```bash
sudo ./setup.sh --local
sudo ./setup.sh <node>
```

Uninstall:

```bash
sudo ./setup.sh --local --uninstall
sudo ./setup.sh --uninstall <node>
```

Sau direct pe host:

```bash
sudo /usr/local/lib/xdev/pve-guests-state/uninstall.sh
```

## Observatii operationale

- proiectul nu instaleaza configuratie persistenta proprie in `/etc`
- proiectul nu instaleaza unitati systemd active; cele vechi sunt doar artefacte istorice si sunt eliminate la install/uninstall
- dupa un `resume` complet reusit, state file-ul este sters
- daca `resume` are erori, state file-ul este pastrat pentru retry
- `cleanup` si preflight-ul din `suspend` ating doar fisiere `vm-*-state-suspend-YYYY-MM-DD.raw`; fisiere `vm-*-state-cp*.raw` sau alte variante raman neatinse
- un nou `suspend` peste un state file existent face merge, nu reseteaza lista de guest-uri de restaurat
- state file-ul retine si `suspend_volume`/`suspend_file_date` per VM pentru a detecta guest-uri alterate dupa salvarea state-ului

## Debug rapid

```bash
journalctl -t pgs -n 50
cat /var/lib/xdev/pve-guests-state/pgs-state.json
```