Docs rewrite

docs/03-execution.md

@@ -1,35 +1,53 @@
-# 03 - Execution
+# 03 - Running the Playbooks
 
-Ensure you are operating within the `ansible/` directory inside the DevContainer.
+All commands assume you are inside the DevContainer, working from the `ansible/` directory.
 
-## 1. Performance & Parallelism
-This repository includes an `ansible.cfg` file configured for performance (`pipelining = True`) and high concurrency (`forks = 20`). If you are provisioning 10 independent servers concurrently in `standalone_mode`, Ansible will process them all simultaneously. 
-*(Warning: If your uplink bandwidth is limited, concurrent `apt dist-upgrade` tasks across 20 nodes may saturate the link. Lower the `forks` value if you experience APT timeouts).*
-
-## 2. Test Connectivity
-Verify SSH access to the nodes before triggering the pipeline. 
-
-**Authentication Flag (`-k`):** If you rely on root passwords, you must append `-k` (`--ask-pass`) to force Ansible to prompt you. If you have already deployed your SSH key to the nodes (e.g., via `ssh-copy-id`), omit the `-k` flag for seamless passwordless execution.
+## Step 1 — Verify Connectivity
 
 ```bash
-# With SSH Key deployed:
-ansible all -i inventories/<customer_name>/hosts.yml -m ping -u root
-
-# Without SSH Key (prompts for password):
-ansible all -i inventories/<customer_name>/hosts.yml -m ping -u root -k
+ansible all -i inventories/<customer>/hosts.ini -m ping
 ```
 
-## 3. Execute the Playbook
-Run the converged deployment playbook. 
+All nodes should return `pong`. If any fail with `Permission denied`, run `ssh-copy-id root@<ip>` for that node and retry.
+
+## Step 2 — (Optional) Configure the P2P Private Network
+
+If you have dedicated NICs for Corosync and DRBD replication and have set `priv_nic_1`, `priv_nic_2`, and `priv_ip` in `hosts.ini`, run `network.yml` first to configure the `p2p` bridge on all nodes:
 
 ```bash
-# With SSH Key deployed:
-ansible-playbook -i inventories/<customer_name>/hosts.yml deploy.yml -u root
-
-# Without SSH Key:
-ansible-playbook -i inventories/<customer_name>/hosts.yml deploy.yml -u root -k
+ansible-playbook network.yml -i inventories/<customer>/hosts.ini
 ```
 
-## Expected Behavior
-* **Idempotency:** The playbook is declarative. If execution fails due to a transient network issue, re-running the exact command will bypass successful tasks and resume from the failure point.
-* **State-Driven Reboots:** If APT installs core libraries or a new PVE kernel, it generates `/var/run/reboot-required`. Ansible detects this, initiates a graceful system reboot, drops the SSH connection, and continuously polls port 22 up to 10 minutes, seamlessly resuming execution once the servers are back online.
+This writes the bridge stanza into `/etc/network/interfaces` and applies it live with `ifreload -a` — no reboot required. The task is skipped on any node that does not have `priv_nic_1` and `priv_nic_2` defined.
+
+## Step 3 — Dry Run
+
+Preview all changes before applying anything. Declarative tasks (file writes, package installs, sysctl, templates) are fully simulated and shown with diffs. Shell tasks (Linstor registrations, `pvecm`, disk wipes) are skipped in check mode — they will not be previewed but they also will not run.
+
+```bash
+ansible-playbook deploy.yml -i inventories/<customer>/hosts.ini --check --diff
+```
+
+## Step 4 — Deploy
+
+```bash
+ansible-playbook deploy.yml -i inventories/<customer>/hosts.ini
+```
+
+The playbook runs across all nodes in parallel (20 forks by default). Phases that require serial ordering — cluster join, Linstor node registration — are internally throttled or pinned to Node 1.
+
+## Idempotency
+
+The playbook is safe to re-run. Every task checks current state before acting. If a run fails partway through due to a transient issue (network blip, APT lock), re-running the same command resumes from the failure point — successful tasks are skipped.
+
+## Reboots
+
+If `apt dist-upgrade` installs a new kernel or critical library, `/var/run/reboot-required` is created. Ansible detects this, reboots the node gracefully, and polls SSH for up to 10 minutes before resuming. An explicit sync barrier ensures all nodes are back online before the clustering phase begins.
+
+## Performance Notes
+
+`ansible.cfg` is tuned with `pipelining = True` and `forks = 20`. For large standalone deployments (many independent nodes), all nodes are provisioned simultaneously. If uplink bandwidth is limited, lower `forks` in `ansible.cfg` to stagger `apt dist-upgrade` traffic.
+
+---
+
+[Previous: Configuring the Inventory](02-configuration.md) | [Index](../README.md) | [Next: Architecture & Phase Breakdown](04-architecture.md)