---
name: proxmox-cluster-notes
description: Read and update Proxmox node and cluster notes via the API. Use when logging kernel upgrades, SDN changes, hardware maintenance, or any on-cluster change. Covers node vs cluster scope, API endpoints, and changelog convention.
---

# Proxmox Cluster Notes

Update notes visible in the Proxmox GUI Summary tab after any infrastructure change.
MUST also log changes in `m.bnna.net` `CHANGELOG.md`.

## Scope: Node vs Cluster

| Change type | Where to log | API endpoint |
|-------------|-------------|--------------|
| Kernel upgrade | Node notes (each node individually) | `PUT /nodes/{node}/config` |
| Hardware maintenance | Node notes | `PUT /nodes/{node}/config` |
| Storage changes (ZFS, PBS) | Node notes | `PUT /nodes/{node}/config` |
| SDN zone/vnet creation | Cluster notes (SDN applies top-down) | `PUT /cluster/options` |
| ACL / permission changes | Cluster notes | `PUT /cluster/options` |
| Account provisioning | Cluster notes | `PUT /cluster/options` |
| Pool migration | Cluster notes | `PUT /cluster/options` |
| Cluster-wide config | Cluster notes | `PUT /cluster/options` |

MUST: After all nodes are updated individually, summarize in cluster notes.

## Read Notes

```sh
# Node notes
curl -sSLk -H "$AUTH" \
  "$BNNA_HOST/api2/json/nodes/{node}/config" | jq -r '.data.description'

# Cluster notes
curl -sSLk -H "$AUTH" \
  "$BNNA_HOST/api2/json/cluster/options" | jq -r '.data.description'
```

## Update Notes

Both endpoints accept `description` as a form field. Markdown is supported
and renders in the Proxmox GUI.

```sh
# Node notes
curl -sSLk -X PUT -H "$AUTH" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "description=# pve1 (bn1) — Dev Cluster
Kernel: 6.17.13-2-pve (updated 2026-03-31)
PVE: 9.1.6

## Recent Changes
- 2026-03-31: Kernel 6.17.2-1 → 6.17.13-2, PVE 9.1.2 → 9.1.6" \
  "$BNNA_HOST/api2/json/nodes/pve1/config"

# Cluster notes
curl -sSLk -X PUT -H "$AUTH" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "description=# pvec-slc1-dev — BNNA Dev Cluster

## SDN Zones & VNets
- zsvc174 / vsvc174 — global services VLAN 174 (172.24.0.0/24)

## Recent Changes
- 2026-03-31: Kernel update (pve1)
- 2026-03-26: zsvc174/vsvc174 added" \
  "$BNNA_HOST/api2/json/cluster/options"
```

## Note Format

```markdown
# {node-or-cluster-name} — {role}
{Key facts: kernel, PVE version, hardware}

## SDN Zones & VNets (cluster only)
- {zone} / {vnet} — {purpose}

## Recent Changes
- {date}: {what changed}
```

MUST: Read existing notes before updating — append to the changelog, don't overwrite it.
NEVER: Remove existing changelog entries when adding new ones.

## Auth

Uses the same PVEAPIToken as other Proxmox API calls. Via bnna pass-through:

```sh
BNNA_HOST="https://tls-10-11-8-205.vms.coolaj86.com"
AUTH="Authorization: Bearer <admin-token>"
```

Or direct to Proxmox:

```sh
BNNA_HOST="https://bn1.pvec-slc1.a.bnna.net"
AUTH="Authorization: PVEAPIToken=root@pam!beamer-agents-ROOT=<secret>"
```

See `LOCAL.md` for real values.

## Workflow

1. Make the infrastructure change
2. Read current notes (`GET`)
3. Append changelog entry to the description
4. Write updated notes (`PUT`)
5. Update `m.bnna.net` `CHANGELOG.md` and push