Mahahe/proxmox-post-install
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs rewrite

Browse Source
This commit is contained in:
Francesco Zimbolo
2026-04-24 12:58:14 +00:00
parent 9e294aea1a
commit 8477f5b592
7 changed files with 425 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

118
docs/02-configuration.md
View File

@@ -1,42 +1,100 @@
# 02 - Configuring the Cluster (or Nodes)
# 02 - Configuring the Inventory
Configurations are segmented per project/customer using isolated Ansible inventories. **Best Practice:** One customer (or one logical cluster) equals one inventory folder. Do not attempt to define multiple clusters within a single inventory to prevent cross-contamination (the "Blast Radius").
One inventory folder per customer or cluster. Never mix multiple clusters in a single inventory — variables are global within an inventory and will cross-contaminate.
## 1. Create the Environment
Copy the template directory for your specific project:
## 1. Create the Inventory
```bash
cp -r inventories/_template inventories/<customer_name>
mv inventories/<customer_name>/hosts.yml.example inventories/<customer_name>/hosts.yml
mv inventories/<customer_name>/group_vars/all.yml.example inventories/<customer_name>/group_vars/all.yml
cp -r inventories/_template inventories/<customer>
```
## 2. Configure `hosts.yml` (Topology & Licensing)
Define the target PVE nodes. Ansible defaults to the `ansible_host` IP for Corosync/DRBD. If a dedicated backend network is available, define `priv_ip`.
The template contains two files to fill in:
**Licensing:** Proxmox licenses are socket/node-specific. Insert the `pve_enterprise_key` directly under each host. If a node lacks a key, omit the variable entirely; Ansible will fall back to the `pve-no-subscription` repository automatically for that specific node.
```
inventories/<customer>/
├── hosts.ini
└── group_vars/all.yml
```
## 2. Configure hosts.ini
Each line defines one node. The inventory alias (left-hand label) is used by Ansible internally and does not need to match the real system hostname — Proxmox and Linstor operations always use the actual hostname gathered from the node at runtime.
```ini
[proxmox]
pve-node-01 ansible_host=192.168.1.1 priv_ip=10.0.0.1 priv_nic_1=enp2s0 priv_nic_2=enp3s0
pve-node-02 ansible_host=192.168.1.2 priv_ip=10.0.0.2 priv_nic_1=enp2s0 priv_nic_2=enp3s0
pve-node-03 ansible_host=192.168.1.3 priv_ip=10.0.0.3 priv_nic_1=enp1s0 priv_nic_2=enp4s0
```
| Variable | Required | Description |
|---|---|---|
| `ansible_host` | Yes | Management IP — used for SSH and Proxmox GUI |
| `priv_ip` | No | Private IP for Corosync and DRBD replication. Falls back to `ansible_host` if omitted |
| `priv_nic_1` / `priv_nic_2` | No | The two NICs forming the p2p bridge. Required only when running `network.yml`. NIC names can differ per node — check with `ip link show` |
| `pve_enterprise_key` | No | Per-node Proxmox subscription key. If omitted, the node uses the no-subscription repository |
**Single-node example** (no cluster, no Linstor):
```ini
[proxmox]
pve-standalone ansible_host=10.0.0.50
```
## 3. Configure group_vars/all.yml
### Deployment Toggles
| Variable | Default | Description |
|---|---|---|
| `standalone_mode` | `false` | Skip all clustering and Linstor tasks, even with multiple nodes in inventory |
| `deploy_linstor` | `false` | Install and configure Linstor + DRBD. Requires 3+ nodes and `standalone_mode: false` |
| `disable_ipv6` | `false` | Disable IPv6 system-wide via sysctl. Useful when IPv6 is unrouted and causes connection timeouts |
| `wipe_linstor_disks` | `false` | Wipe partition tables and signatures from raw block devices before LVM creation. **Destructive — only set on first deployment** |
### Proxmox Cluster
```yaml
all:
children:
proxmox:
hosts:
pve-node-01:
ansible_host: 192.168.1.11
priv_ip: 10.0.0.11
pve_enterprise_key: "pve1c-111111111111"
pve-node-02:
ansible_host: 192.168.1.12
priv_ip: 10.0.0.12
# Omitted key: This node will use no-subscription
pve_cluster_name: "my-cluster"
# pve_enterprise_key: "" # Optional global key; prefer per-host in hosts.ini
```
## 3. Configure `group_vars/all.yml`
### Linstor HA Controller
* **Deployment Toggles:**
* `deploy_linstor: true` (Provisions HCI/DRBD stack)
* `standalone_mode: false` (Set to `true` if you are provisioning independent, unclustered servers).
* **HA Controller:** Define `ha_pool`, `ha_vip` (Virtual IP), and the CIDR prefix for the Linstor DB promoter.
* **Storage Pools:**
* If mapping a raw disk (`/dev/sda`), the playbook invokes `community.general.lvg` to create the VG/Thin Pool.
* If mapping an existing path (`pve/data`), LVM tasks are skipped, and the target is registered directly in Linstor.
```yaml
ha_pool: "fast_pool_1" # Storage pool used for the linstor_db HA volume
ha_vip: "10.0.0.10" # Floating VIP managed by drbd-reactor
ha_vip_cidr: "24" # Prefix length — also used for the p2p bridge address
```
### Linstor Storage Pools
Each entry defines one Resource Group. All nodes in a pool share the same `pool_name`. Keys under `targets` must match the inventory alias from `hosts.ini`.
```yaml
linstor_storage_pools:
- pool_name: "fast_pool_1"
rg_name: "fast_pool_1"
vg_name: "pve"
thin_name: "data"
targets:
pve-node-01: "pve/data" # Register existing pve/data thin pool (no disk changes)
pve-node-02: "pve/data"
pve-node-03: "pve/data"
- pool_name: "slow_pool_1"
rg_name: "slow_pool_1"
vg_name: "sp1"
thin_name: "data"
targets:
pve-node-01: "/dev/sdb" # Create VG sp1 + thin pool on /dev/sdb
pve-node-02: "/dev/sdb"
pve-node-03: "/dev/sdb"
```
**Target path rules:**
- `/dev/...` — playbook creates the VG and LVM thin pool on that raw device. If `wipe_linstor_disks: true`, the disk is wiped first with `wipefs` and `sgdisk`.
- `vg_name/thin_name` (e.g. `pve/data`) — playbook registers the existing thin pool directly in Linstor without touching the underlying storage.
---
[Previous: Prerequisites](01-prerequisites.md) | [Index](../README.md) | [Next: Running the Playbooks](03-execution.md)