[ ~/netbox-openbao/proxmox-secrets ]tty0

emerson@netdevops:~/netbox-openbao$ diagram proxbox-openbao --vms --secrets

Proxmox VM & container secrets

How netbox-proxbox inventory sync and netbox-openbao secret storage work together — without mixing credentials into the sync pipeline.

netbox-proxbox keeps Proxmox QEMU VMs and LXC containers modeled in NetBox — clusters, nodes, interfaces, addresses, and optional ssh service metadata. That sync path is read-only against Proxmox and never carries login passwords or private keys.

netbox-openbao attaches SSH credentials to the same VirtualMachine and virtualization.VM objects after they exist. Secret material lives only in OpenBao KV v2; NetBox holds usernames, fingerprints, assignments, and audit — the same split as devices elsewhere in the estate.

The two plugins do not call each other directly. They meet on shared NetBox objects: proxbox creates the VM row and network context; openbao binds credentials to that row (and to an ipam.Service when services are modeled).

›overview

design principles

  • ├─Inventory sync and secret storage are separate lanes — a proxbox job failure must not rotate or leak credentials, and a reveal must not trigger a Proxmox API call.
  • ├─Proxbox never writes to OpenBao; netbox-openbao never queries the Proxmox API for VM discovery.
  • ├─Quick-add SSH on a VM page is the usual handoff: proxbox supplies the object; the operator (or automation with NetBox RBAC) stores the login material in one atomic transaction.
  • ├─Broker mode keeps AppRole material on netbox-openbao-broker; netbox-rpc catalogs audited host procedures that resolve credentials through the same openbao reveal contract.

›inventory sync

Lane 1 — inventory sync (no secrets) — hover any node for details

Proxmox VEProxmox VE — hypervisor hosting QEMU VMs and LXC containers. Source of inventory; guest credentials on the host are not part of sync.
REST read-only
[proxbox-apiFastAPI]proxbox-apiproxbox-api orchestrates read-only sync jobs through proxmox-sdk. HTTP/SSE/WebSocket transport — never writes secret material.
sync jobs
[netbox-proxboxplugin]netbox-proxboxnetbox-proxbox plugin maps clusters, nodes, VMs, interfaces, and IPs into NetBox DCIM/virtualization models.
netbox-sdk · REST write
NetBox PostgreSQLNetBox PostgreSQL — VirtualMachine, VMInterface, IPAddress, ipam.Service (e.g. ssh tcp/22 as reachability metadata).

no passwords · no keys · no tokens

›credential write

Lane 2 — store SSH credential on the VM — Quick-add or API after the object exists

operator / automationOperator or automation with add_credential — Add SSH access on the Device/VM page.
POST · atomic transaction
[netbox-openbaoservices.py]netbox-openbaonetbox-openbao · services.py — validates RBAC, store_credential(), rollback compensation.
indexed metadataNetBox rows
broker modeoptional
NetBox metadataNetBox — Credential (metadata), CredentialAssignment, ipam.Service ssh:22 when assignable_models includes service.netbox-openbao-brokernetbox-openbao-broker (optional) — holds AppRole; NetBox asks over mTLS with audit outside NetBox blast radius.
write-only materialdirect AppRole or via broker
OpenBao KV v2OpenBao KV v2 — ssh-password or ssh-keypair payload; direct AppRole or via broker mTLS.

›reveal & access

Lane 3 — reveal and SSH access — Material leaves only through audited POST reveal

operator · nbx · netbox-rpcOperator, nbx CLI, or netbox-rpc dispatch — needs SSH login for the VM/container.
POST reveal
[openbao REST revealPOST only]openbao REST revealPOST /api/plugins/openbao/credentials/{id}/reveal/ — reveal_credential permission, JSON-only, no-store.
KV v2 read
OpenBao / brokerOpenBao read via AppRole or netbox-openbao-broker — no vendor policy text in errors.
SSH · outside NetBox
VirtualMachine / LXCVirtualMachine or container — SSH session using IP/interface from proxbox inventory.

›security stack

OpenBao, broker, and RPC stack — Open-source secret storage and audited host access

operator · nbxOperator or nbx — human reveal or procedure dispatch through NetBox RBAC.
NetBox plugins
[netbox-openbaoplugin]netbox-openbaonetbox-openbao — Credential inventory, reveal API, OpenBao writes through services.py.netbox-rpcnetbox-rpc — audited procedure catalog, approvals, execution history in NetBox.
broker modedirect AppRole
approved procedurecatalog
netbox-openbao-brokernetbox-openbao-broker (optional) — mTLS sidecar holding AppRole; vault credentials never on the NetBox host.netbox-rpc-backendnetbox-rpc-backend — fixed-argv SSH executor; resolves material via openbao reveal, never ad-hoc shell.
POST reveal
OpenBao KV v2OpenBao KV v2 — sole store for passwords, keys, and tokens.
SSH session
Device · VirtualMachineDevice or VirtualMachine — SSH session using proxbox inventory for reachability.

›what stays out of proxbox sync

Proxmox guest credentials — cloud-init passwords, QEMU agent secrets, LXC root passwords stored on the hypervisor — are not part of the proxbox discovery contract. Even when proxbox creates or updates an ipam.Service named ssh with tcp/22, that row describes reachability, not the login secret.

Storing the SSH login belongs to netbox-openbao (or another credential workflow) after the VM exists in NetBox. Automation should resolve material through POST /api/plugins/openbao/credentials/{id}/reveal/ with reveal_credential permission, not by scraping Proxmox config or expecting sync payloads to include secrets.

# netbox-openbao docs/architecture/openbao-broker-rpc.md

# netbox-openbao docs/architecture/proxmox-vm-secrets.md

# netbox-proxbox docs/companion-plugins/netbox-openbao.md

# netbox-openbao docs/quick-add-ssh.md

›typical operator sequence

  1. Run proxbox sync (manual, scheduled, or via proxbox-api) so the VM or container appears under the correct cluster and node with interfaces and IPs.
  2. Open the VirtualMachine in NetBox and use Add SSH access (quick-add) to create the ipam.Service (when modeled), Credential, and CredentialAssignment in one transaction.
  3. Optional: confirm the public key or username metadata on the credential row; material remains write-only on GET.
  4. Operators or nbx automation POST reveal when they need the password or private key for SSH — audited, Cache-Control: no-store, separate from inventory export.
see also›netbox-openbao — credential plugin showcasesee also›netbox-proxbox — Proxmox → NetBox syncsee also›netbox-rpc cross-plugin integrations — dispatch and credential lanes