はじめに
Proxmox VE(仮想化基盤)の情報を、外部のダッシュボードツールなどから参照したい場合があります。このとき、Proxmoxの管理者アカウントのIDとパスワードをそのままツールに渡すのは、権限が強すぎて危険です。誤操作や設定ミスがあれば、仮想マシン・コンテナの削除・停止まで行えてしまうからです。こうした場面で使うのがAPIトークンと、権限ロールを組み合わせた最小権限のアクセス設定です。
Proxmox VEの権限モデル
Proxmox VEは、以下の4つの要素からなるロールベースアクセス制御(RBAC)モデルを採用しています。
| 要素 | 内容 |
|---|---|
| ユーザー(User) | ログインするアカウント本体 |
| ロール(Role) | 「何ができるか」をまとめた権限セット(例: 閲覧のみ、フル管理者など) |
| パス(Path) | 「どこに対して」権限を適用するか(例: 特定のVM、ノード全体など) |
| ACL | ユーザー(またはトークン)・ロール・パスを結びつけるルール |
Proxmox VEのCLIツール(qm、pctなど)はいずれもこのAPIのラッパーであり、pveum(Proxmox VE User Manager)コマンドを使うことで、ユーザー管理・ロール割り当て・APIトークンの発行をコマンドラインから操作できます。
APIトークンとは
APIトークンは、特定のユーザーに紐づけて発行する、ログインパスワードとは別の認証情報です。以下のような特徴があります。
- ユーザー本体のパスワードを外部ツールに渡さずに済む
- トークンごとに有効期限を設定できる
- 権限分離(Privilege Separation)を有効にすると、トークン自体に個別のACLを設定でき、紐づくユーザー本体の権限とは別に、トークンの権限をさらに絞り込める
- 重要な原則として、APIトークンの実効権限は常に紐づくユーザー本体の権限の範囲内に収まる。ユーザーができないことは、そのユーザーのトークンでもできない
読み取り専用ロールの例：PVEAuditor
Proxmox VEには、あらかじめ定義済みのロールがいくつか用意されています。その1つPVEAuditorは、VM・コンテナ・ノードの状態を閲覧できるが、変更・作成・削除といった操作は一切できない、読み取り専用のロールです。ダッシュボード用途など「表示するだけ」で十分な場面には、このような閲覧専用ロールを割り当てるのが安全です。
pveumコマンドでの一連の流れ(例)
# 1. 専用ユーザーを作成(realmは pam や pve など環境に応じて指定)
pveum user add api@pam
# 2. ユーザーに読み取り専用ロールを、対象パス(ここではルート全体)に割り当てる
pveum acl modify / --users api@pam --roles PVEAuditor
# 3. そのユーザーに紐づくAPIトークンを発行する
pveum user token add api@pam homepage --privsep 1
--privsep 1は権限分離を有効にするオプションで、トークン自体にも個別にACLを設定する運用にする場合に指定します。発行時に表示されるトークンの値(シークレット)は再表示できないため、この場でのみ控えておく必要があります。
実務での使いどころ
このような「特定用途専用・読み取り専用のAPIトークン」は、自宅サーバーのダッシュボードツールがVM/コンテナの稼働数やノードのリソース使用率を表示する、といった用途に向いています。管理者権限そのものを渡す必要がなく、万一トークンが漏洩しても被害を「閲覧されるだけ」に限定できるのが最小権限の原則(Principle of Least Privilege)の考え方です。
まとめ
| 項目 | 内容 |
|---|---|
| Proxmox VEの権限モデル | ユーザー・ロール・パス・ACLの組み合わせ(RBAC) |
| APIトークン | ユーザー本体のパスワードを渡さずに済む、有効期限付きの認証情報 |
| 権限分離(Privilege Separation) | トークン自体にユーザー本体とは別のACLを設定できる仕組み |
| PVEAuditor | 閲覧のみ可能な、あらかじめ定義済みの読み取り専用ロール |
| 実効権限の原則 | トークンの権限は常に紐づくユーザー本体の権限の範囲内に収まる |
