User guideWayseer 0.28.3Contents

Proxmox VE

The proxmox module reads a Proxmox VE cluster through its API, with an API token: the cluster, its nodes, the virtual machines and containers on them, and its storage. It only reads, unless you allow its actions, and needs no license key.

Configuration

modules:
  - kind: proxmox
    name: pve
    options:
      url: https://pve1.example.com:8006
      token_id: wayseer@pve!wayseer
      secret_file: ~/.config/wayseer/pve-token   # or secret_env: PVE_TOKEN

url is any node of the cluster, https:// with its port, usually 8006. Put no credentials in it. token_id is the API token's ID, <user>@<realm>!<name>, and the secret is the token's secret, from a file, an environment variable or, with secret_keyring: <service>/<account>, the system keyring (secrets). The secret is read once, when the module starts, and sent only to url, in the Authorization header. Wayseer follows no redirect, so it never sends the token anywhere else. Neither the token ID nor the secret, nor the cluster's address, shows in the log, in an error or on screen.

A token that can only read

Give Wayseer a token of its own with the PVEAuditor role, which can read everything and change nothing. On any node, as root:

pveum user add wayseer@pve
pveum user token add wayseer@pve wayseer --privsep 1
pveum acl modify / --users wayseer@pve --roles PVEAuditor
pveum acl modify / --tokens 'wayseer@pve!wayseer' --roles PVEAuditor

A token made with --privsep 1 has only the privileges that both it and its user have, so the user and the token each need the role.

The second command prints the token's secret once; save it where secret_file points, readable only by you.

A self-signed cluster

Proxmox VE signs its nodes' certificates with its own CA unless you gave it another. Wayseer always checks the certificate, so point ca_file at that CA, copied from /etc/pve/pve-root-ca.pem on any node:

options:
  ca_file: ~/.config/wayseer/pve-root-ca.pem

Without it, the module's state reads "the certificate is not trusted; set ca_file". If the certificate is not for the name in url, use the name the certificate gives.

The options below go under options.

What it shows

Each node is member_of the cluster, and each guest runs_on its node. Storage local to a node runs_on that node; shared storage, such as NFS or Ceph, is one entity, member_of the cluster. A guest's Proxmox VE tags are its tags in Wayseer, so #prod in the palette finds the guests tagged prod.

A running guest or online node is OK. A stopped guest is unknown, not down, with the reason "stopped", since stopping one is usual; a paused one is a warning. An offline node is down, a storage that is not available is a warning, and a cluster without quorum is critical.

A guest is known by the cluster's name and its ID, so a guest that migrates stays the same entity: only the node it runs on changes. Once a read finds it on another node, its runs_on link moves there and nothing else about it changes, so it stays selected if it was. What changed says web-1 moved from alder to birch, and Stream shows the same as an info event of kind migrated on the guest, with the two nodes in its from and to fields. A guest that moves and back between two reads shows no move. A host that is in no cluster shows its node, guests and storage, without a cluster.

Wayseer shows at most max_guests guests, those with the lowest IDs; past it, the module's state says how many were left out.

Nodes on the map

Proxmox VE does not say where a node is, so Geo cannot place it by itself. To place your nodes, give each one a zone with zones, and name the zone under places:

places:
  names:
    Amsterdam: {lat: 52.37, lon: 4.9}
    Ashburn:   {lat: 39.04, lon: -77.49}
modules:
  - kind: proxmox
    name: pve
    options:
      url: https://pve1.example.com:8006
      token_id: wayseer@pve!wayseer
      secret_file: ~/.config/wayseer/pve-token
      zones: {alder: Amsterdam, birch: Ashburn, cedar: Ashburn}

Each node that zones names gets that zone as its zone attribute, which places reads by default. A node zones leaves out has no zone. Guests and storage are not placed; Geo counts the nodes.

Metrics

Each node and running guest has these series, read from Proxmox VE's own history (its rrddata) only when a lens shows them. Wayseer asks for the history fine enough for the time window: a minute apart for the last hour, half an hour for a day, three hours for a week, half a day for a month and a week for a year. The newest values come from each read of the cluster, every interval. A stopped guest has no series, and storage has none.

Actions

The module offers three actions on virtual machines and containers. None runs unless the instance's actions lists it, and each waits for you to confirm it.

There is no forced stop, migration or delete.

modules:
  - kind: proxmox
    name: pve
    actions: [start, shutdown, reboot]
    options:
      url: https://pve1.example.com:8006
      token_id: wayseer@pve!wayseer
      secret_file: ~/.config/wayseer/pve-token

Proxmox VE runs each action as a task on the guest's node. Wayseer follows the task until it ends, for up to five minutes. The status bar and the action log then say how it went: "rebooted web-1 on alder", or why the task failed, such as "VM 100 not running". If the task is still running after five minutes, Wayseer says so and stops following it. The task may still finish on the cluster.

The read-only token above can run none of them. Each needs the VM.PowerMgmt privilege on the guest, for both the user and its token. Give it in a role of its own, on /vms for every guest or on /vms/<id> for one:

pveum role add WayseerPower --privs VM.PowerMgmt
pveum acl modify /vms --users wayseer@pve --roles WayseerPower
pveum acl modify /vms --tokens 'wayseer@pve!wayseer' --roles WayseerPower

If the cluster refuses an action, the status bar reads "reboot: HTTP 403; the token needs the VM.PowerMgmt privilege on the guest". It never shows the cluster's address or the token. A failed task's reason is shown with both taken out.

Health

The module reads the cluster's status every interval. A cluster that has lost quorum shows "cluster <name> is not quorate" beside the module; it still reads, but cannot start, stop or move guests until quorum returns. Errors say what failed, such as "authentication failed (HTTP 401)" or "connection refused", and never quote the cluster's answer.