docs/pbs-deployment: require per-hypervisor namespaces

VMIDs aren't globally unique across PVE hosts (esh-pve and sfsrv-ana
both have VM 100, etc.). Without namespaces, per-hypervisor backups
collide under the same /vm/<vmid>/ path in the shared datastore.

Changes:
  - New Phase 1.4b: create one namespace per hypervisor up front
    (pfi-pve, nh3-pve, esh-pve, esh-pve-nas, sfsrv-ana).
  - Phase 2.1 storage-entry template now lists Namespace as a required
    field, set to the hypervisor's own name.
  - Critical-note explaining the collision risk so future deployers
    don't skip this step.

ACL grants remain at the datastore level; they apply across all child
namespaces so the existing fleet-vzdump token continues to work. Sync
job (Phase 6) preserves namespace tree to PBS-NH3 automatically.
This commit is contained in:
2026-04-22 14:33:54 -07:00
parent 2f76da2108
commit d7e6f32e36
+23
View File
@@ -190,6 +190,23 @@ In the PBS web UI: **Datastore → Add Datastore**:
The first time PBS writes to the datastore it initializes `.chunks/`,
`.lock`, etc. Takes a few seconds.
### 1.4b. Create per-hypervisor namespaces
VMIDs are NOT globally unique across PVE hosts (esh-pve and sfsrv-ana
both have VM 100 for instance). Without namespaces, their backups
collide under the same `/vm/100/` path in the datastore. Create a
namespace per hypervisor up front:
```bash
for h in pfi-pve nh3-pve esh-pve esh-pve-nas sfsrv-ana; do
proxmox-backup-manager datastore namespace create backups $h
done
proxmox-backup-manager datastore namespace list backups
```
Each PVE client later (Phase 2.1, 3.1, 4) sets its Namespace field to
its own hostname when configuring the PBS storage.
### 1.5. Create an API token for hypervisors to use
PBS web UI: **Configuration → Access Control → API Token → Add**:
@@ -239,12 +256,18 @@ Web UI: **Datacenter → Storage → Add → Proxmox Backup Server**:
| Username | `root@pam!fleet-vzdump` |
| Password | the token secret from 1.5 |
| Datastore | `backups` |
| **Namespace** | **`pfi-pve`** (match the hypervisor name — see 1.4b) |
| Fingerprint | from 1.6 |
| Content | VZDump backup file |
| Nodes | `pve` (pfi-pve) |
Click Add. Storage should show as available within seconds.
> **Critical:** every hypervisor gets its own namespace value matching
> its own name — `nh3-pve`, `esh-pve`, `esh-pve-nas`, `sfsrv-ana`.
> Prevents VMID collisions (not-globally-unique VMIDs would otherwise
> land in the same `/vm/<vmid>/` path).
### 2.2. Test backup of one VM
Pick a small VM (e.g. an idle LXC like ana-filebot, VMID 112). Web UI: