Proxmox VE 運用リファレンス (リリース 9.1.2)
ノード、ゲスト、サービスはダウンしたり、到達不能になったり、操作中に消えたりすることがあります。決して稼働していると想定せず、実際の状態を再クエリし、タイムアウト内で再試行し、グレースフルに機能を縮退させてください。自己修復パターンについては、bitranox:coding-resilience を参照してください。
1. クラスタ設定 (自動検出)
| チェック項目 | コマンド |
|---|---|
| 環境 | pveversion --verbose (カーネル、pve-manager、corosync、qemu-server などの全コンポーネントバージョン) |
| ノード | pvecm nodes (数、名前、ID) / pvecm status (IP、クォーラム、トランスポート、リンク状態) |
| クォーラム | pvecm status -- "Quorate" フィールドを確認。しきい値: floor(総ノード数/2) + 1 |
| API アクセス | pvesh (ローカル CLI)、pveproxy (HTTPS :8006)、REST API。スクリプトでは --output-format json を使用 |
| ストレージ | pvesm status (アクティブなストレージ) / cat /etc/pve/storage.cfg (全設定) |
| ネットワーク | pvesh get /nodes/{node}/network --output-format json / cat /etc/network/interfaces |
| サブスクリプション | pvesubscription get (ステータス確認) / pvesubscription set <key> (キー適用) |
2. 安全プロトコル
| ルール | 詳細 |
|---|---|
| 破壊的な一括操作の禁止 | 複数ノードに影響するコマンド（再起動、シャットダウン、一括VM停止）は、ユーザーの明示的な確認が必要です。 |
| クォーラムチェック | ノードの再起動/メンテナンス前: pvecm status。(現在 - 1) < floor(総数/2) + 1 の場合は中断。2ノードクラスタの場合は QDevice を確認。 |
| 事前のバックアップ | VM設定変更やアップグレードの前に、バックアップが存在することを確認: pvesm list {storage} --content backup |
| 強制削除の禁止 | リソースIDを確認せずに --purge や --force を使用しない: qm config {vmid} または pct config {vmid} |
| HA ステータス | HAリソース変更前: ha-manager status -- マイグレーションやフェンシングが進行中でないことを確認。 |
| ネットワーク変更 | 常にドライランを先に実行: ifreload -a -n (ifupdown2 には --test はありません)。ゲストトラフィックを運んでいるブリッジで ifdown を実行しない。リモート適用とDHCP/ボンド/WLANのトラップ: references/host-networking.md を参照。 |
| Corosync 設定 | まずコピーを取り、コピーを編集し、現在の設定をバックアップしてから、移動する。常に config_version をインクリメントする。 |
| ストレージ操作 | ストレージ削除前: pvesm list {storage} で、そのストレージを参照しているVM/CTがないことを確認。 |
| 保護フラグ | qm set {vmid} --protection 1 / pct set {vmid} --protection 1 で誤削除を防止。 |
| ZFS プロパティの一括変更 | PVE はゲストの設定済みディスクサイズをデータセットの refquota として保存します。全データセットにわたって refquota/refreservation をクリアする一括変更は、すべてのゲストのディスク制限を黙って削除します。一方、pct config は依然として古いサイズを報告するため、1つのコンテナでプールを満たしてしまう可能性があります。subvol- または vm- で始まるリーフ名は除外してください。 |
3. アクションレビュープロトコル
必須。 Proxmoxノード、VM、コンテナ上で直接実行されるすべてのアクション（コマンド、設定変更、サービス操作）の前に、このレビューを実行してください。
例外: 読み取り専用操作（ログの読み取り、ステータスの問い合わせ、何も変更せずに情報を収集する）は安全とみなされ、このレビューなしで即座に実行できます。
このゲートは
opusで実行してください。 このスティールマン/レッドチーム判定は、稼働中のインフラストラクチャへの変更をゲートします。弱いモデルは、停止、データ損失、クォーラムリスクを過小評価します。レビューはopusで行います。ピン留めされたopusサブエージェントにmediumの努力レベルで委任するか（レビューディスパッチ、bitranox:process-agents-subagent-driven-developmentの「Review dispatches」を参照）、インラインで保持する場合は、実行前にモデル切り替えまたは続行のオプションを提供してください。未知の下位ティアでこのゲートを実行しないでください。bitranox:process-agents-subagent-driven-development（「The session model is fixed」/「Concrete tiers」）を参照してください。
3.1 スティールマンプロンプト
計画されたアクションまたは設定が、最も理想的な形で Proxmox サーバー上で実行されることを検討してください。このアクションが、最も安全で、最も効率的で、最適に統合されたソリューションであると想像してください。このアクションが、システム管理の目標を完全に達成し、安定性を高め、ユーザーニーズを完全に満たす方法を明確に示してください。
3.2 レッドチームプロンプト
経験豊富な管理者またはセキュリティアナリストのように、計画された Proxmox アクションをレビューし、潜在的なリスクを明らかにしてください。設定の潜在的な弱点を特定し、停止リスク、データ損失、または意図しない副作用を考慮してください。最悪のシナリオの下で計画の堅牢性をテストし、プレッシャーがかかっても安全で信頼できることを確認してください。
3.3 決定
レッドチームレビューの最後に、特定されたリスクまたは弱点が、計画されたアクションを停止するほど深刻かどうかを評価してください。アクションが安全で、論理的で、堅牢であると思われる場合は、すぐに実行できます。重大な不確実性が残る場合は、ユーザーに明示的に確認を求める必要があります。明確な決定で締めくくります：「アクションを実行」 または 「ユーザーに確認を求める」。
4. コードと応答スタイル
- 応答: 短く、正確で、CLI 中心（
pvesh、pvecm、pvesm、qm、pct、ha-manager、vzdump、pvesr、pvenode、pveceph、pveum、pveam）。 - トラブルシューティング: 常に最初にログを照会:
journalctl -u pvedaemon -n 50、pvenode task list --errors 1、/var/log/pveproxy/access.log。 - JSON 優先:
--output-format jsonまたはjson-prettyを使用。スクリプトによる解析には--noborder --noheaderを使用。 - ロールバック計画: すべての変更にはロールバックを含めること。最初に設定ファイルをバックアップする。ストレージ/VMを変更する前にバックアップが存在することを確認する。
5. クラスタサイズ別クイックテーブル
| サイズ | 動作 |
|---|---|
| シングルノード | クラスタ操作なし。HAなし。ローカルストレージと外部バックアップに注力。 |
| 2ノード | QDevice を強く推奨。これがない場合: 1ノード喪失 = クォーラム喪失。緊急時は pvecm expected 1。 |
| 3ノード以上 | フルHA。floor((N-1)/2) の障害に耐性（3ノード: 1、5ノード: 2）。 |
ノード数の検出: pvecm nodes | grep -c '^\s*[0-9]'
6. トラブルシューティングクイックリファレンス
| 問題 | 診断 |
|---|---|
| クラスタにクォーラムがない | pvecm status > "Quorate: No"。接続性を確認、systemctl status corosync。緊急時: pvecm expected 1。 |
| ノードが参加しない | UDP 5405-5412、時刻同期、SSH (TCP 22) を確認。試す: pvecm add {IP} --fingerprint {SHA256}。 |
| VM が起動しない | ロックを確認: qm unlock {vmid}。設定を確認: qm config {vmid}。ログ: journalctl -u pvedaemon -n 100。 |
| CT が起動しない | ロックを確認: pct unlock {vmid}。設定を確認: pct config {vmid}。ログ: journalctl -u pvecontainer -n 100。 |
| ストレージが利用できない | pvesm status でアクティブか確認。systemctl status pve-storage。重要でない場合は pvesm set {storage} --disable。 |
| HA リソースの障害 | ha-manager status、ha-manager resource list、journalctl -u pve-ha-manager -n 100。 |
| バックアップ/復元の失敗 | tail -100 /var/log/vzdump.log。ストレージの空き容量を確認: df -h。 |
| Ceph の問題 | ceph -s、ceph osd tree、ceph health detail。OSD: systemctl restart ceph-osd@{id}。 |
| ファイアウォールの問題 | pvefw status、pvefw rules、pvefw log。ログ: /var/log/pve-firewall.log。 |
| ユーザー/パーミッションの問題 | pveum user list、pveum acl list、pveum user modify {user} --enable。 |
| SDN の問題 | pvesh get /cluster/sdn/zones、pvesh get /cluster/sdn/vnets。ログ: journalctl -u pve-sdn -n 100。 |
| 通知の問題 | pvenotify status、pvenotify test。設定: cat /etc/pve/notifications.cfg。 |
7. Proxmox VE CLI リファレンス
7.1 ノード管理
pvenode {command}:stop、reboot、task list、config set（DNS、NTP、その他ノード設定）pvesh {path} {method}: 任意の API エンドポイント呼び出し（get、post、put、delete）
7.2 仮想マシン (VM) (qm)
qm list: 全VM一覧qm config {vmid}: VM設定表示 (--currentで実行時設定)qm start/stop/shutdown/reboot/reset {vmid}: VM電源管理qm suspend/resume {vmid}: サスペンド/レジュームqm migrate {vmid} {target-node}: ライブマイグレーションqm clone {vmid} {new-vmid}: リンククローンqm template {vmid}: テンプレート変換qm set {vmid} --{option} {value}: 設定変更 (例:--memory 4096、--cores 4)qm unlock {vmid}: ロック解除qm disk resize {vmid} {disk} {size}: ディスクリサイズqm monitor {vmid}: QEMUモニターqm terminal {vmid}: VNCコンソール
7.3 コンテナ (CT) (pct)
pct list: 全CT一覧pct config {vmid}: CT設定表示pct start/stop/shutdown/suspend/resume {vmid}: CT電源管理pct migrate {vmid} {target-node}: マイグレーションpct clone {vmid} {new-vmid}: クローンpct template {vmid}: テンプレート変換pct set {vmid} --{option} {value}: 設定変更 (例:--memory 2048、--swap 1024)pct unlock {vmid}: ロック解除pct resize {vmid} {disk} {size}: ディスクリサイズpct enter {vmid}: CT内に入る (シェル)pct push/pull {vmid}: ファイル転送
7.4 ストレージ (pvesm)
pvesm status: ストレージステータスpvesm list {storage}: ストレージ上のコンテンツpvesm add/remove/set {storage}: ストレージ管理pvesm alloc/free {storage} {vmid}: イメージの割り当て/解放pvesm import/export: インポート/エクスポート
7.5 HA 管理 (ha-manager)
ha-manager status: 全体ステータスha-manager resource list: 管理対象リソース一覧ha-manager resource add {vmid}: リソース追加ha-manager resource remove {vmid}: リソース削除ha-manager resource migrate {vmid} {target-node}: マイグレーションha-manager group list/set: HAグループ管理ha-manager crm-command: 手動CRMコマンド送信
7.6 バックアップ (vzdump)
vzdump {vmid}: 単一VM/CTバックアップvzdump --all: 全VM/CTバックアップvzdump --mode snapshot/stop/suspend: バックアップモードvzdump --compress --storage {storage}: 圧縮と保存先指定vzdump --mailto {email}: 通知
7.7 Ceph (pveceph)
pveceph status: Cephクラスタステータスpveceph osd list/create/remove: OSD管理pveceph pool create/ls/delete: プール管理pveceph mon create: MON追加pveceph mgr create: MGR追加pveceph mds create: MDS追加pveceph fs create: CephFS作成pveceph purge: Ceph完全削除
7.8 ユーザー管理 (pveum)
pveum user list/add/modify/remove: ユーザー管理pveum group list/add/modify/remove: グループ管理pveum acl list/add/remove: ACL管理pveum role list/add/modify/delete: ロール管理pveum auth list/modify: 認証ドメイン管理pveum ticket: チケット生成
7.9 ファイアウォール (pvefw)
pvefw status: ファイアウォールステータスpvefw start/stop/restart: ファイアウォール制御pvefw rules: ルール一覧pvefw log: ログ表示pvefw reload: 設定再読み込み
7.10 SDN (Software Defined Network)
pvesh get /cluster/sdn/zones: ゾーン一覧pvesh get /cluster/sdn/vnets: VNet一覧pvesh get /cluster/sdn/subnets: サブネット一覧pvesh get /cluster/sdn/controllers: コントローラー一覧pvesh post /cluster/sdn/zones/{zone}/status: ゾーンステータス
7.11 その他ツール
pvesr: リモートマイグレーション/レプリケーションpveam: アプライアンス管理 (テンプレートダウンロードなど)pveproxy: プロキシ設定pvenet: ネットワーク設定pvers: バージョン情報
8. Proxmox VE の設定ファイル
| ファイル | 説明 |
|---|---|
/etc/pve/storage.cfg | ストレージ設定 |
/etc/pve/ceph.conf | Ceph設定 |
/etc/pve/datacenter.cfg | データセンター設定 |
/etc/pve/nodes/{node}/config | ノード設定 |
/etc/pve/firewall/cluster.fw | ファイアウォールルール (クラスタレベル) |
/etc/pve/firewall/host.fw | ファイアウォールルール (ホストレベル) |
/etc/pve/firewall/ | VM/CT個別ファイアウォール設定 |
/etc/pve/ha | HA設定 |
/etc/pve/notifications.cfg | 通知設定 |
/etc/pve/corosync.conf | Corosync設定 |
/etc/pve/pve-root-ca.pem | CA証明書 |
/etc/pve/priv/storage.pem | ストレージ認証情報 |
/etc/pve/priv/known_hosts | 既知のホスト |
/etc/pve/priv/authorized_keys | 公開鍵 |
9. Proxmox VE のログファイル
| ログ | 説明 |
|---|---|
/var/log/pvedaemon.log | pvedaemon ログ |
/var/log/pveproxy/access.log | pveproxy アクセスログ |
/var/log/pveproxy/error.log | pveproxy エラーログ |
/var/log/pve-firewall.log | ファイアウォールログ |
/var/log/pve-ha-manager.log | HAマネージャーログ |
/var/log/vzdump.log | バックアップログ |
/var/log/syslog | システムログ |
/var/log/messages | メッセージログ |
/var/log/ceph/ | Ceph ログ |
/var/log/pve-sdn.log | SDN ログ |
10. Proxmox VE のベストプラクティス
- 定期的なバックアップ:
vzdumpで定期的なバックアップをスケジュール。 - 監視:
pvenode task list、pvesm status、ceph -sで定期的に監視。 - アップデート:
apt update && apt dist-upgradeで定期的に更新。 - セキュリティ:
pveumでユーザーアクセスを制限。ファイアウォールを有効化。 - パフォーマンス:
qm set {vmid} --memory {size}、pct set {vmid} --memory {size}でリソースを調整。 - ドキュメント: 設定変更はすべてコメント付きで文書化。
- テスト: 本番環境に適用する前に、ステージング環境でテスト。
- フォールバック: すべての変更にはロールバック計画を用意。
11. Proxmox VE API リファレンス (pvesh)
pvesh は Proxmox VE REST API へのコマンドラインインターフェースです。
基本的な使い方:
pvesh get /nodes/{node}/status --output-format json
pvesh create /nodes/{node}/qemu --vmid 100 --name test-vm --memory 2048 --cores 2
pvesh set /nodes/{node}/qemu/100/config --memory 4096
pvesh delete /nodes/{node}/qemu/100
便利な API エンドポイント:
| エンドポイント | 説明 |
|---|---|
/cluster/status | クラスタステータス |
/cluster/options | クラスタオプション |
/nodes/{node}/status | ノードステータス |
/nodes/{node}/qemu | VM管理 |
/nodes/{node}/lxc | CT管理 |
/nodes/{node}/storage | ストレージ管理 |
/nodes/{node}/network | ネットワーク管理 |
/nodes/{node}/ceph | Ceph管理 |
/access/users | ユーザー管理 |
/access/acl | ACL管理 |
/cluster/sdn | SDN管理 |
/cluster/firewall | ファイアウォール管理 |
/cluster/ha | HA管理 |
/cluster/replication | レプリケーション管理 |
/cluster/notifications | 通知管理 |