🏍️

Proxmox VE APIを使ってみる

に公開
API
Postman
サーバー
VM
Proxmox
tech

Proxmox APIのユーザー作成からPostmanでの動作確認まで徹底解説

背景

Proxmoxを使って、ユーザーが気軽に仮想マシン(VM)を立ち上げたり、削除・クローンしたりできる学習環境を（まずは内部向けサービスとして）手軽に構築したいと考えました。
ProxmoxのAPIについて日本語の情報、特に基本設定に関する記事が少なかったため、備忘録として手順をまとめておきます。

はじめに

この記事では、Proxmox VEでAPI専用のユーザーを作成し、そのユーザーを使ってAPIを操作する基本的な流れを解説します。
動作確認には、広く使われているAPI開発ツール「Postman」を利用します。

目次

  1. ProxmoxでのAPIユーザーと権限設定
    1. API専用ユーザーの作成
    2. API用のロール（権限グループ）を作成
    3. ユーザーとロールの紐付け（パーミッション設定）
    4. APIトークンの発行
  2. PostmanでのAPI動作確認
    1. Postmanの事前設定（SSL証明書検証の無効化）
    2. 認証とチケットの発行 (POST)
    3. Cookieとヘッダーの設定
    4. テストAPIの実行 (GET)
  3. Proxmox APIの主要エンドポイント一覧

1. ProxmoxでのAPIユーザーと権限設定

まず、Proxmoxの管理画面でAPIを安全に利用するための準備を行います。
rootユーザーを直接使わず、専用のユーザーと権限を作成します。

Proxmoxの管理画面 (https://{proxmoxのIPアドレス}:8006) にログインして作業を開始します。

アクセス

※User nameは初回ログイン時はrootです。
※Linux PAM standard authenticationを選択してください。ここが違っているとログインできない可能性があります。

1-1. API専用ユーザーの作成

APIから操作を行うための専用ユーザーを作成します。

  1. 左のツリーから Datacenter を選択します。
  2. Permissions -> Users タブに移動します。
  3. Add ボタンをクリックしてユーザー作成画面を開きます。

Addボタン

  1. 以下のように入力します。
    • User name: 任意の名前（例: api-user）
    • Realm: Proxmox VE authentication server を選択。
    • Password: 任意のパスワードを設定します。
    • その他は任意で設定してください。

user情報入力画面

📝レルム PAM と Proxmox VE の違い

  • Linux PAM: Proxmoxが動作しているLinuxシステムのユーザーアカウントを利用します。
  • Proxmox VE: Proxmoxが独自に管理するユーザーデータベースを利用します。
    APIのようにシステムから独立したユーザーを作成する場合は、Proxmox VE を選択するのが一般的です。

1-2. API用のロール（権限グループ）を作成

次に、APIユーザーに割り当てる権限をまとめた「ロール」を作成します。

  1. Permissions -> Roles タブに移動します。

  2. Create ボタンをクリックします。

  3. Role nameに任意の名前（例: API-Admin）を入力します。

  4. Privilegesを選択します。テスト段階では全ての権限にチェックを入れて構いませんが、本番運用ではVMの操作に必要な最小限の権限（VM.Allocate, VM.Audit, VM.Clone, VM.Config.*, VM.Migrate, VM.Monitor, VM.PowerMgmtなど）に絞ることをお勧めします。

1-3. ユーザーとロールの紐付け（パーミッション設定）

作成したユーザーとロールを紐付け、実際に権限を与えます。

  1. Permissions タブに移動します。

  2. Add -> User Permission を選択します。

  3. 以下の項目を設定します。

    • Path: 権限を適用する範囲です。一番上の / を選択すると全リソースが対象になります。
    • User: 先ほど作成したユーザー（例: api-user@pve）を選択します。
    • Role: 先ほど作成したロール（例: API-Admin）を選択します。

これで、api-userがAPI-Adminの権限を持つようになりました。

1-4. APIトークンの発行

最後に、プログラムから認証するためのAPIトークンを発行します。

  1. Permissions -> API Tokens タブに移動します。

  2. Add ボタンをクリックします。

  3. 以下の項目を設定します。

    • User: 先ほど作成したユーザー（例: api-user@pve）を選択します。
    • Token ID: トークンを識別するための任意の名前（例: api-token）を入力します。
    • Privilege Separation: チェックを外します（Noにする）。

  4. Add をクリックすると、Token ID と Secret が表示されます。

⚠️重要
この Secret はこの画面でしか表示されません。 必ず安全な場所にコピーして保管してください。

2. PostmanでのAPI動作確認

APIの準備ができたので、Postmanを使って実際に通信できるかテストします。
Postman公式サイトからダウンロードして起動してください。

2-1. Postmanの事前設定（SSL証明書検証の無効化）

Proxmoxはデフォルトで自己署名証明書を使用しているため、Postmanがそのままでは安全な接続ではないと判断して通信をブロックします。これを回避するため、SSLの検証を一時的に無効化します。

Settings -> General タブにある SSL certificate verification のトグルを OFF にしてください。

2-2. 認証とチケットの発行 (POST)

Proxmox APIの認証は、まずユーザー名とパスワードを送って一時的なチケットを発行してもらうことから始まります。

  1. メソッドタイプを POST に変更します。
  2. URL入力欄に以下を入力します。
    https://{proxmoxのIPアドレス}:8006/api2/json/access/ticket
  3. Body タブを選択し、x-www-form-urlencoded を選び、以下のキーと値を設定します。
KEY VALUE
username 作成したユーザー名 (api-user@pve)
password ユーザーに設定したパスワード

  1. Send ボタンを押すと、レスポンスが返ってきます。

レスポンスの中から、以下の2つの値をコピーしてメモ帳などに控えておきます。

  • ticket: PVE:api-user@pve:670E... のような文字列
  • CSRFPreventionToken: 670E... のような文字列

2-3. Cookieとヘッダーの設定

取得したチケットを使って、以降のAPIリクエストで自身が認証済みであることを証明します。

Cookieの設定

  1. Send ボタンの隣にある Cookies リンクをクリックします。

  2. 対象ドメイン（{proxmoxのIPアドレス}）が表示されるので、Add Cookie をクリックします。
    ※なければ作成してください

  3. 表示された入力欄に以下のように設定します。
    PVEAuthCookie={先ほどコピーしたticketの値}; Path=/;
    Cookie_1=valueのみの上書きで大丈夫です

  4. Save をクリックします。

ヘッダーの設定

  1. Headers タブに戻ります。
  2. 新しいキーと値を設定します。
KEY VALUE
CSRFPreventionToken 先ほどコピーしたCSRF...トークンの値

2-4. テストAPIの実行 (GET)

認証設定が完了したので、実際にデータを取得する簡単なAPIを叩いてみます。

  1. メソッドタイプを GET に変更します。

  2. Body タブを選択し、none に設定します。

  3. URL入力欄に以下を入力して Send を押します。
    https://{proxmoxのIPアドレス}:8006/api2/json/nodes

成功すれば、Proxmoxクラスターに参加しているノードの情報がJSON形式で返ってくるはずです。これでAPIの疎通確認は完了です！

3. Proxmox APIの主要エンドポイント一覧

Proxmox APIは /api2/json/ 以下に非常に多くのエンドポイントを持っています。ここでは、VM管理でよく使われるものをまとめました。

パスのルール

  • {node}: Proxmoxサーバーのノード名に置き換えます。（例: pve）
  • {vmid}: 操作したいVMやコンテナのIDに置き換えます。（例: 101）
HTTPメソッド エンドポイントパス 説明
GET /nodes 全てのノードの一覧を取得します。
GET /nodes/{node}/qemu 特定ノード上の全VM(QEMU)の一覧を取得します。
GET /nodes/{node}/lxc 特定ノード上の全コンテナ(LXC)の一覧を取得します。
GET /nodes/{node}/qemu/{vmid}/status/current 特定VMの現在のステータス（起動、停止など）を取得します。
POST /nodes/{node}/qemu/{vmid}/status/start 特定VMを起動します。
POST /nodes/{node}/qemu/{vmid}/status/stop 特定VMを安全にシャットダウンします。
POST /nodes/{node}/qemu/{vmid}/status/reboot 特定VMを再起動します。
POST /nodes/{node}/qemu 新しいVMを作成します。（Bodyに詳細な設定が必要）
POST /nodes/{node}/qemu/{vmid}/clone 特定VMのクローンを作成します。（Bodyに設定が必要）
DELETE /nodes/{node}/qemu/{vmid} 特定VMを削除します。

上記全ては試していません。
多少の違いなどがあったら申し訳ないです

この他にも、スナップショット作成やバックアップ、ネットワーク設定など、Proxmoxの管理画面でできるほぼ全ての操作がAPI経由で実行可能です。詳細はProxmox VE API公式ドキュメントをご参照ください。

Discussion