Operational discipline: inventory, tagging, change management

Why this matters in production

A Proxmox cluster without discipline becomes unmanageable in months. Tags, inventory, and change management turn infrastructure chaos into operations.

Inventory

Every VM, container, and storage should be in an inventory. The minimum columns:

Maintain in a spreadsheet or CMDB. Update on every change.

An inventory nobody reconciles is fiction

Every estate has an inventory spreadsheet. Most of them were accurate on the day they were written. The difference between a useful inventory and a decorative one is not the tooling — it is whether something compares it against reality on a schedule and produces a list of differences.

set -euo pipefail
INVENTORY=/root/ops/inventory.csv     # VMID in column 1

# What the cluster actually contains, guests and containers alike.
pvesh get /cluster/resources --type vm --output-format json \
| grep -oE '"vmid":[0-9]+' | cut -d: -f2 | sort -n > /tmp/cluster-vmids

# What the inventory claims.
awk -F, 'NR>1 {print $1}' "$INVENTORY" | sort -n > /tmp/inventory-vmids

echo '--- in the cluster, missing from the inventory (undocumented guests)'
comm -23 /tmp/cluster-vmids /tmp/inventory-vmids

echo '--- in the inventory, missing from the cluster (stale rows)'
comm -13 /tmp/cluster-vmids /tmp/inventory-vmids

# Guests with no owner tag at all - the ones nobody will claim in an incident.
for vmid in $(cat /tmp/cluster-vmids); do
tags=$(qm config "$vmid" 2>/dev/null | awk '/^tags:/ {print $2}')
case "$tags" in
  *owner-*) ;;
  *) echo "$vmid has no owner tag" ;;
esac
done

Tagging

Proxmox supports tags on VMs, containers, storage, and nodes.

qm set 100 --tags 'tier-0,database,production'

Tags are searchable and can drive automation. Common conventions:

• By tier: tier-0, tier-1, tier-2, tier-3.
• By environment: prod, staging, dev.
• By owner: team-platform, team-data.
• By technology: postgres, kafka, nginx.

Use key-value tags, not bare words

Proxmox tags are free-form strings with no structure imposed on them, which means the structure has to come from your convention. The convention that survives is a fixed set of keys, each with a controlled value list:

tier-0 and env-prod are parseable. production and important are not, because six months later somebody adds prod, Production and live and nothing can be selected reliably again.

The test for a good taxonomy is whether a script can answer a question with it. “List every Tier-0 production guest that is not in a backup job” is a one-liner against key-value tags and impossible against free prose.

set -euo pipefail

# Every guest carrying a given tag, cluster-wide, in one call.
pvesh get /cluster/resources --type vm --output-format json \
| grep -oE '"(vmid|name|tags)":("[^"]*"|[0-9]+)'

# Tier-0 guests and the node each one is on.
for vmid in $(qm list | awk 'NR>1 {print $1}'); do
tags=$(qm config "$vmid" | awk '/^tags:/ {print $2}')
case "$tags" in
  *tier-0*) printf '%-6s %s\n' "$vmid" "$tags" ;;
esac
done

# Set tags. Note that --tags REPLACES the whole list rather than appending,
# which is the single most common way a tag gets silently dropped.
VMID=100
qm config "$VMID" | grep '^tags:'                 # read the current list first
qm set "$VMID" --tags 'tier-0,env-prod,owner-platform,app-postgres'

Governing tags from datacenter.cfg

Two datacenter.cfg options turn a documented convention into an enforced one, and they are the reason a taxonomy survives contact with a team:

case-sensitive deserves a moment. Left off, Prod and prod are the same tag, which is usually what you want. Turned on, they are two tags and your taxonomy has a hole in it that only shows up when a query returns fewer rows than expected.

Change management

Infrastructure changes should follow a change management process:

1. Request: what, why, when, who.
2. Review: by a peer or senior; risk assessment.
3. Approval: by change authority.
4. Implementation: during change window.
5. Verification: confirm expected outcome.
6. Documentation: update the runbook or inventory.

Naming conventions

Naming should be deliberate. Suggested patterns:

• VMs: app-env-nn, for example webapp-prod-01
• Containers: ct-app-env-nn, or follow the VM convention
• Storage: role-tech-node, for example vmdata-zfs-n1

Which identifiers you can change later, and which you cannot

Not every name in a Proxmox estate is equally revisable, and knowing the difference before you allocate one saves a rebuild.

Production considerations

Common mistakes

• An inventory nobody reconciles, which is accurate on the day it is written and decorative thereafter.
• Ad-hoc tags with no key structure, so nothing can be selected reliably.
• qm set --tags used as if it appends, silently dropping the guest’s classification.
• No registered-tags, so a user can move their own guest into a stronger backup policy or out of one.
• Assigning tiers by asking owners how important their application is.
• Retro-fitting a VMID scheme, discarding backup history in the process.
• Change requests with insufficient detail for anyone to assess risk.

Key takeaways

• An inventory is only as good as the script that reconciles it; run it weekly and treat every difference as a finding.
• Use key-prefixed tags with controlled values so the taxonomy is queryable.
• --tags replaces the list. Read, merge, write.
• registered-tags and user-tag-access in datacenter.cfg are what make a convention an enforced one.
• Tier is the tag that pays for itself, because backup, alerting, HA and cost all consult it.
• The VMID is permanent. Choose a scheme now; do not renumber later.

Knowledge check