docs: remove SSH references and update install URLs to GitHub Pages
v3.0 requires no SSH — QEMU connects directly via iscsi://. README "How It Works" and troubleshooting sections had v2.x SSH carryover. Compatibility matrix now shows v3.x as stable with PVE 9 confirmed. All install instructions updated from Cloudsmith to the GitHub Pages apt repo (thegrandwazoo.github.io/freenas-proxmox, v3 dist track). Cloudsmith testing channel retained for beta builds only. architecture.md updated to reflect ADR-010 and the live GitHub Pages publish step in CI. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Kevin Adams
parent
dfbb4f6c31
commit
c9dff84c1e
30
README.md
30
README.md
|
|
@ -30,14 +30,12 @@ A Proxmox VE storage plugin that manages ZFS-over-iSCSI volumes on TrueNAS (CORE
|
|||
|
||||
## How It Works
|
||||
|
||||
Proxmox VE's built-in ZFS-over-iSCSI storage type uses SSH to manage LUNs on the storage server. This plugin replaces that SSH-based management layer with direct calls to the **TrueNAS REST API**, giving you:
|
||||
This plugin is a native `PVE::Storage::Custom` type — Proxmox discovers it automatically and treats it like any other storage backend. When you create a VM disk, the plugin calls the **TrueNAS REST API** to provision a ZFS volume (zvol) and a dedicated per-VM iSCSI target, then hands Proxmox an `iscsi://` path. QEMU opens that path directly — no SSH, no `iscsiadm`, no kernel iSCSI sessions on the Proxmox host.
|
||||
|
||||
- API token (Bearer) or username/password authentication
|
||||
- Automatic TrueNAS API version detection (v1 and v2)
|
||||
- Support for both TrueNAS CORE and TrueNAS SCALE
|
||||
- Proper rollback when operations fail (no dangling iSCSI extents)
|
||||
|
||||
> **Note:** Proxmox still uses `iscsiadm` to connect and disconnect the iSCSI session on the Proxmox host itself — that part is handled by the core Proxmox code and does not require SSH. The SSH keys documented in the [Proxmox ZFS-over-iSCSI wiki](https://pve.proxmox.com/wiki/Storage:_ZFS_over_iSCSI) are still required for the ZFS pool listing step.
|
||||
- Bearer Token (API key) authentication — no username/password, no SSH keys
|
||||
- Per-VM iSCSI targets (`proxmox-vm-<vmid>`) — removing one disk never affects other VMs
|
||||
- Automatic rollback when operations fail (no dangling iSCSI extents)
|
||||
- Supports TrueNAS CORE 13.x and TrueNAS SCALE 24.10–25.10
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -47,8 +45,7 @@ Proxmox VE's built-in ZFS-over-iSCSI storage type uses SSH to manage LUNs on the
|
|||
|
||||
| Plugin Version | Proxmox VE | TrueNAS CORE | TrueNAS SCALE | Status |
|
||||
|:--------------:|:----------:|:------------:|:-------------:|:------:|
|
||||
| **3.x** *(beta)* | 8.4.x ✅ | 13.0-U6+ ✅ | Electric Eel (24.10) ✅, Fangtooth (25.04) ✅, Goldeye (25.10) ✅ | Beta — active development |
|
||||
| **3.x** *(planned)* | 9.x ⏳ | 13.0-U6+ | Electric Eel (24.10)+, Goldeye (25.10)+ | v3.1.0 — in progress |
|
||||
| **3.x** *(stable)* | 8.4.x ✅, 9.x ✅ | 13.0-U6+ ✅ | Electric Eel (24.10) ✅, Fangtooth (25.04) ✅, Goldeye (25.10) ✅ | Stable |
|
||||
| **2.x** *(stable)* | 7.x ⚠️, 8.0–8.3 ✅, 8.4.x ✅ | 11.3+ | 22.02+ | Active |
|
||||
| **1.x** *(legacy)* | 5.x, 6.x | 11.x | — | Unsupported |
|
||||
|
||||
|
|
@ -335,27 +332,20 @@ iscsiadm: No active sessions.
|
|||
|
||||
**Layer 3 — Proxmox core storage stack**
|
||||
|
||||
Errors from PVE's own storage subsystem — ZFSPlugin.pm, pvedaemon, pool listing via SSH, or storage.cfg parsing. These exist regardless of which iSCSI plugin you use.
|
||||
Errors from PVE's own storage subsystem — pvedaemon, pvestatd, or storage.cfg parsing.
|
||||
|
||||
Common causes:
|
||||
- SSH keys not configured between Proxmox and TrueNAS (required for ZFS pool listing — see [Prerequisites](#prerequisites))
|
||||
- `storage.cfg` syntax error
|
||||
- `storage.cfg` syntax error or stale config keys (especially after migrating from v2.x — see [migration guide](docs/migrating-from-v2.md))
|
||||
- `pvedaemon` or `pvestatd` service crashed
|
||||
|
||||
Example log line:
|
||||
```
|
||||
unable to run command '/usr/bin/ssh ... zfs list ...': exit code 255
|
||||
```
|
||||
|
||||
**Quick triage:**
|
||||
|
||||
| Symptom | Likely layer | First check |
|
||||
|---------|-------------|-------------|
|
||||
| Disk creation fails, API error in task log | Plugin (Layer 1) | API key, SSL setting, TrueNAS API reachable |
|
||||
| Disk created on TrueNAS but Proxmox reports error | Plugin (Layer 1) | syslog for `freenas-proxmox:` lines |
|
||||
| Disk created on TrueNAS but Proxmox reports error | Plugin (Layer 1) | syslog for `truenas-proxmox:` lines |
|
||||
| VM won't start, iSCSI session error | iSCSI/QEMU (Layer 2) | TrueNAS iSCSI service, initiator group ACL |
|
||||
| Storage shows unavailable, pool listing fails | Proxmox core (Layer 3) | SSH key setup, `pvedaemon` service |
|
||||
| Kernel errors after disk deletion (v2.x) | iSCSI/Proxmox (Layer 2/3) | `iscsiadm -m session -R` to rescan |
|
||||
| Storage shows unavailable | Proxmox core (Layer 3) | `pvedaemon` service, storage.cfg |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -360,16 +360,17 @@ lint → build → security → publish
|
|||
|
||||
**Job 4: Publish**
|
||||
- Skipped for PRs and branches with `channel=none`
|
||||
- Cloudsmith `deb` push to the resolved repo
|
||||
- Cloudsmith `deb` push to the resolved repo (parallel channel, transitional)
|
||||
- GitHub Pages apt repo update: `.deb` added to `pool/v{major}/`, `Packages.gz` and signed `InRelease` regenerated for the relevant dist tracks, committed to `gh-pages` branch
|
||||
- On tagged releases: creates a draft GitHub Release with the `.deb` attached
|
||||
|
||||
### Version String Logic
|
||||
|
||||
| Git ref | Debian version string | Channel | Cloudsmith repo |
|
||||
|---|---|---|---|
|
||||
| `refs/tags/v3.0.0` | `3.0.0-1` | stable | `truenas-proxmox` |
|
||||
| `refs/heads/master` or `refs/heads/release/3.x` | `3.0.0~beta+abc1234` | testing | `truenas-proxmox-testing` |
|
||||
| `refs/heads/release/*` (other) | `3.0.0~alpha+abc1234` | development | `truenas-proxmox-snapshots` |
|
||||
| Git ref | Debian version string | Channel | Cloudsmith repo | GitHub Pages dist |
|
||||
|---|---|---|---|---|
|
||||
| `refs/tags/v3.0.0` | `3.0.0-1` | stable | `truenas-proxmox` | `v3` |
|
||||
| `refs/heads/master` or `refs/heads/release/3.x` | `3.0.0~beta+abc1234` | testing | `truenas-proxmox-testing` | — |
|
||||
| `refs/heads/release/*` (other) | `3.0.0~alpha+abc1234` | development | `truenas-proxmox-snapshots` | — |
|
||||
| feature branches, PRs | `3.0.0~dev+abc1234` | none | not published |
|
||||
|
||||
The tilde (`~`) in the Debian version sorts below the base version in `dpkg`, guaranteeing pre-release builds never auto-upgrade over a stable release.
|
||||
|
|
@ -598,7 +599,8 @@ Major design decisions live in `.claude/cos/adrs/`. Check before making changes
|
|||
|---|---|
|
||||
| ADR-001 | Consolidate build pipeline into this repo; no install-time git clone |
|
||||
| ADR-002 | Full `PVE::Storage::Custom` plugin; no ZFSPlugin.pm or pvemanagerlib.js patches |
|
||||
| ADR-003 | Transition from Cloudsmith to GitHub Pages apt repo (accepted, not yet implemented) |
|
||||
| ADR-003 | Superseded by ADR-010 |
|
||||
| ADR-010 | GitHub Pages apt repo with per-major-version dist tracks (`v3`, `main`/`v2` for backward compat) |
|
||||
| ADR-004 | `eval {}` rollback pattern for all multi-step TrueNAS operations |
|
||||
| ADR-005 | Bearer token (API key) as primary auth; basic auth removed in v3.0 |
|
||||
| ADR-006 | `$VERSION` in `TrueNAS.pm` is the single source of truth for package versioning |
|
||||
|
|
|
|||
|
|
@ -77,18 +77,17 @@ Run all of these commands on **each Proxmox node** in your cluster, or on your s
|
|||
### Step 1 — Import the GPG Signing Key
|
||||
|
||||
```bash
|
||||
curl -fsSL https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/gpg.284C106104A8CE6D.key \
|
||||
curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
|
||||
| gpg --dearmor \
|
||||
| tee /usr/share/keyrings/ksatechnologies-truenas-proxmox-keyring.gpg > /dev/null
|
||||
| tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
|
||||
```
|
||||
|
||||
### Step 2 — Add the Package Repository
|
||||
|
||||
```bash
|
||||
cat > /etc/apt/sources.list.d/ksatechnologies-repo.list << 'EOF'
|
||||
deb [signed-by=/usr/share/keyrings/ksatechnologies-truenas-proxmox-keyring.gpg] \
|
||||
https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/deb/debian any-version main
|
||||
EOF
|
||||
echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
|
||||
https://thegrandwazoo.github.io/freenas-proxmox v3 main" \
|
||||
| tee /etc/apt/sources.list.d/truenas-proxmox.list
|
||||
```
|
||||
|
||||
### Step 3 — Install the Package
|
||||
|
|
|
|||
|
|
@ -76,8 +76,15 @@ Before you do anything else, check if any of your VMs have a TPM state disk. QEM
|
|||
Run this on **every node in the cluster** before adding the new storage:
|
||||
|
||||
```bash
|
||||
# Add the Cloudsmith repo (if not already added)
|
||||
curl -1sLf 'https://dl.cloudsmith.io/public/ksatechnologies/truenas-proxmox/setup.deb.sh' | bash
|
||||
# Import the GPG key
|
||||
curl -fsSL https://thegrandwazoo.github.io/freenas-proxmox/public.gpg.key \
|
||||
| gpg --dearmor \
|
||||
| tee /etc/apt/keyrings/truenas-proxmox.gpg > /dev/null
|
||||
|
||||
# Add the v3 repository track
|
||||
echo "deb [signed-by=/etc/apt/keyrings/truenas-proxmox.gpg] \
|
||||
https://thegrandwazoo.github.io/freenas-proxmox v3 main" \
|
||||
| tee /etc/apt/sources.list.d/truenas-proxmox.list
|
||||
|
||||
# Install
|
||||
apt update && apt install truenas-proxmox
|
||||
|
|
|
|||
Loading…
Reference in New Issue