REST API

イントロダクション

LXD とクライアントの間の全ての通信は HTTP 上の RESTful API を使って行います。リモートの操作は SSL で暗号化して通信し、ローカルの操作は Unix ソケットを使って通信します。

全ての REST インターフェースが認証を必要とするわけではありません。

/ への GET は認証なしで誰でも実行可能です (API エンドポイント一覧を返します)
/1.0 への GET は認証なしで誰でも実行可能です (ですが結果は認証ありの場合と異なります)
/1.0/certificates への POST はクライアント証明書があれば誰でも実行可能です
/1.0/images/* への GET は認証なしで誰でも実行可能ですが、その場合認証なしのユーザーに対して公開されているイメージだけを返します。

以下では認証なしで利用できるエンドポイントはそのように明記します。

API のバージョニング

サポートされている API のメジャーバージョンのリストは GET / を使って取得できます。

後方互換性を壊す場合は API のメジャーバージョンが上がります。

後方互換性を壊さずに追加される機能は api_extensions の追加という形になり、特定の機能がサーバでサポートされているかクライアントがチェックすることで利用できます。

戻り値

次の 3 つの標準的な戻り値の型があります。

標準の戻り値
バックグラウンド操作
エラー

標準の戻り値

標準の同期的な操作に対しては以下のような dict が返されます。

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "metadata": {}                          // リソースやアクションに固有な追加のメタデータ
}

HTTP ステータスコードは必ず 200 です。

バックグラウンド操作

リクエストの結果がバックグラウンド操作になる場合、 HTTP ステータスコードは 202 (Accepted) になり、操作の URL を指す HTTP の Location ヘッダが返されます。

レスポンスボディは以下のような構造を持つ dict です。

{
    "type": "async",
    "status": "OK",
    "status_code": 100,
    "operation": "/1.0/instances/<id>",                     // バックグラウンド操作の URL
    "metadata": {}                                          // 操作のメタデータ (下記参照)
}

操作のメタデータの構造は以下のようになります。

{
    "id": "a40f5541-5e98-454f-b3b6-8a51ef5dbd3c",           // 操作の UUID
    "class": "websocket",                                   // 操作の種別 (task, websocket, token のいずれか)
    "created_at": "2015-11-17T22:32:02.226176091-05:00",    // 操作の作成日時
    "updated_at": "2015-11-17T22:32:02.226176091-05:00",    // 操作の最終更新日時
    "status": "Running",                                    // 文字列表記での操作の状態
    "status_code": 103,                                     // 整数表記での操作の状態 (status ではなくこちらを利用してください。訳注: 詳しくは下記のステータスコードの項を参照)
    "resources": {                                          // リソース種別 (container, snapshots, images のいずれか) の dict を影響を受けるリソース
      "containers": [
        "/1.0/instances/test"
      ]
    },
    "metadata": {                                           // 対象となっている (この例では exec) 操作に固有なメタデータ
      "fds": {
        "0": "2a4a97af81529f6608dca31f03a7b7e47acc0b8dc6514496eb25e325f9e4fa6a",
        "control": "5b64c661ef313b423b5317ba9cb6410e40b705806c28255f601c0ef603f079a7"
      }
    },
    "may_cancel": false,                                    // (REST で DELETE を使用して) 操作がキャンセル可能かどうか
    "err": ""                                               // 操作が失敗した場合にエラー文字列が設定されます
}

対象の操作に対して追加のリクエストを送って情報を取り出さなくても、何が起こっているかユーザーにとってわかりやすい形でボディは構成されています。ボディに含まれる全ての情報はバックグラウンド操作の URL から取得することもできます。

エラー

さまざまな状況によっては操作を行う前に直ぐに問題が起きる場合があり、そういう場合には以下のような値が返されます。

{
    "type": "error",
    "error": "Failure",
    "error_code": 400,
    "metadata": {}                      // エラーについてのさらなる詳細
}

HTTP ステータスコードは 400, 401, 403, 404, 409, 412, 500 のいずれかです。

ステータスコード

LXD REST API はステータス情報を返す必要があります。それはエラーの理由だったり、操作の現在の状態だったり、 LXD が提供する様々なリソースの状態だったりします。

デバッグをシンプルにするため、ステータスは常に文字列表記と整数表記で重複して返されます。ステータスの整数表記の値は将来に渡って不変なので API クライアントが個々の値に依存できます。文字列表記のステータスは人間が API を手動で実行したときに何が起きているかをより簡単に判断できるように用意されています。

ほとんどのケースでこれらは status と status_code と呼ばれ、前者はユーザーフレンドリーな文字列表記で後者は固定の数値です。

整数表記のコードは常に 3 桁の数字で以下の範囲の値となっています。

100 to 199: リソースの状態 (started, stopped, ready, ...)
200 to 399: 成功したアクションの結果
400 to 599: 失敗したアクションの結果
600 to 999: 将来使用するために予約されている番号の範囲

現在使用されているステータスコード一覧

コード	意味
100	操作が作成された
101	開始された
102	停止された
103	実行中
104	キャンセル中
105	ペンディング
106	開始中
107	停止中
108	中断中
109	凍結中
110	凍結された
111	解凍された
200	成功
400	失敗
401	キャンセルされた

再帰

巨大な一覧のクエリを最適化するために、コレクションに対して再帰が実装されています。コレクションに対するクエリの GET リクエストに recursion パラメータを指定できます。

デフォルト値は 0 でコレクションのメンバーの URL が返されることを意味します。 1 を指定するとこれらの URL がそれが指すオブジェクト (通常は dict 形式) で置き換えられます。

再帰はジョブへのポインタ (URL) をオブジェクトそのもので単に置き換えるように実装されています。

フィルタ

検索結果をある値でフィルタするために、コレクションにフィルタが実装されています。コレクションに対する GET クエリに filter 引数を渡せます。

フィルタはインスタンスとイメージのエンドポイントに提供されています。

フィルタにはデフォルト値はありません。これは見つかった全ての結果が返されることを意味します。フィルタの引数には以下のような言語を設定します。

?filter=field_name eq desired_field_assignment

この言語は REST API のフィルタロジックを構成するための OData の慣習に従います。フィルタは下記の論理演算子もサポートします。 not(not), equals(eq), not equals(ne), and(and), or(or) フィルタは左結合で評価されます。空白を含む値はクォートで囲むことができます。ネストしたフィルタもサポートされます。例えば config 内のフィールドに対してフィルタするには以下のように指定します。

?filter=config.field_name eq desired_field_assignment

device の属性についてフィルタするには以下のように指定します。

?filter=devices.device_name.field_name eq desired_field_assignment

以下に上記の異なるフィルタの方法を含む GET クエリをいくつか示します。

containers?filter=name eq "my container" and status eq Running

containers?filter=config.image.os eq ubuntu or devices.eth0.nictype eq bridged

images?filter=Properties.os eq Centos and not UpdateSource.Protocol eq simplestreams

非同期操作

完了までに 1 秒以上かかるかもしれない操作はバックグラウンドで実行しなければなりません。そしてクライアントにはバックグラウンド操作 ID を返します。

クライアントは操作のステータス更新をポーリングするか long-poll API を使って通知を待つことが出来ます。

通知

通知のために Websocket ベースの API が利用できます。クライアントへ送られるトラフィックを制限するためにいくつかの異なる通知種別が存在します。

リモート操作の状態をポーリングしなくて済むように、リモート操作を開始する前に操作の通知をクライアントが常に購読しておくのがお勧めです。

PUT と PATCH の使い分け

LXD API は既存のオブジェクトを変更するのに PUT と PATCH の両方をサポートします。

PUT はオブジェクト全体を新しい定義で置き換えます。典型的には GET で現在のオブジェクトの状態を取得した後に PUT が呼ばれます。

レースコンディションを避けるため、 GET のレスポンスから ETag ヘッダを読み取り PUT リクエストの If-Match ヘッダに設定するべきです。こうしておけば GET と PUT の間にオブジェクトが他から変更されていた場合は更新が失敗するようになります。

PATCH は変更したいプロパティだけを指定することでオブジェクト内の単一のフィールドを変更するのに用いられます。キーを削除するには通常は空の値を設定すれば良いようになっていますが、 PATCH ではキーの削除は出来ず、代わりに PUT を使う必要がある場合もあります。

インスタンス、コンテナーと仮想マシン

このドキュメントでは /1.0/instances/... のようなパスを常に示します。これらはかなり新しく、仮想マシンがサポートされた LXD 3.19 で導入されました。

コンテナーのみをサポートする古いリリースでは全く同じ API を /1.0/containers/... で利用します。

後方互換性の理由で LXD は /1.0/containers API を引き続き公開しサポートしますが、簡潔さのため以下では両方をドキュメントはしないことにしました。

/1.0/virtual-machines に追加のエンドポイントも存在し、 /1.0/containers とほぼ同様ですが、仮想マシンのタイプのインスタンスのみを表示します。

API 構造

/
/1.0
/1.0/certificates
/1.0/certificates/<fingerprint>
/1.0/instances
/1.0/instances/<name>
- /1.0/instances/<name>/console
- /1.0/instances/<name>/exec
- /1.0/instances/<name>/files
- /1.0/instances/<name>/snapshots
- /1.0/instances/<name>/snapshots/<name>
- /1.0/instances/<name>/state
- /1.0/instances/<name>/logs
- /1.0/instances/<name>/logs/<logfile>
- /1.0/instances/<name>/metadata
- /1.0/instances/<name>/metadata/templates
- /1.0/instances/<name>/backups
- /1.0/instances/<name>/backups/<name>
- /1.0/instances/<name>/backups/<name>/export
/1.0/events
/1.0/images
/1.0/images/<fingerprint>
- /1.0/images/<fingerprint>/export
- /1.0/images/<fingerprint>/refresh
- /1.0/images/<fingerprint>/secret
/1.0/images/aliases
- /1.0/images/aliases/<name>
/1.0/networks
/1.0/networks/<name>
/1.0/networks/<name>/state
/1.0/operations
/1.0/operations/<uuid>
- /1.0/operations/<uuid>/wait
- /1.0/operations/<uuid>/websocket
/1.0/profiles
/1.0/profiles/<name>
/1.0/projects
/1.0/projects/<name>
/1.0/storage-pools
/1.0/storage-pools/<name>
- /1.0/storage-pools/<name>/resources
- /1.0/storage-pools/<name>/volumes
- /1.0/storage-pools/<name>/volumes/<type>
  - /1.0/storage-pools/<pool>/volumes/<type>/<name>
  - /1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots
    - /1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/<name>
/1.0/resources
/1.0/cluster
/1.0/cluster/members
- /1.0/cluster/members/<name>

API 詳細

`/`

GET

説明: サポートされている API の一覧
認証: guest
操作: 同期
戻り値: サポートされている API エンドポイントの URL の一覧

戻り値

[
    "/1.0"
]

`/1.0/`

GET

説明: サーバの設定と環境情報
認証: guest, untrusted, trusted のいずれか
操作: 同期
戻り値: サーバの状態を表す dict

戻り値 (trusted の場合)

{
    "api_extensions": [],                           // stable とマークされた API 以降に追加された API 拡張の一覧
    "api_status": "stable",                         // API の実装状態 (development, stable, deprecated のいずれか)
    "api_version": "1.0",                           // 文字列表記での API バージョン
    "auth": "trusted",                              // 認証状態 ("guest", "untrusted", "trusted" のいずれか)
    "config": {                                     // ホストの設定
        "core.trust_password": true,
        "core.https_address": "[::]:8443"
    },
    "environment": {                                // ホストの様々な情報 (OS, カーネル, ...)
        "addresses": [
            "1.2.3.4:8443",
            "[1234::1234]:8443"
        ],
        "architectures": [
            "x86_64",
            "i686"
        ],
        "certificate": "PEM certificate",
        "driver": "lxc",
        "driver_version": "1.0.6",
        "kernel": "Linux",
        "kernel_architecture": "x86_64",
        "kernel_version": "3.16",
        "server": "lxd",
        "server_pid": 10224,
        "server_version": "0.8.1"}
        "storage": "btrfs",
        "storage_version": "3.19",
    },
    "public": false,                                // クライアントにとってサーバを公開された (読み取り専用の) リモートとして扱うべきかどうか
}

戻り値 (guest または untrusted の場合)

{
    "api_extensions": [],                   // stable とマークされた API 以降に追加された API 拡張の一覧
    "api_status": "stable",                 // API の実装状態 (development, stable, deprecated のいずれか)
    "api_version": "1.0",                   // 文字列表記での API バージョン
    "auth": "guest",                        // 認証状態 ("guest", "untrusted", "trusted" のいずれか)
    "public": false,                        // クライアントにとってサーバを公開された (読み取り専用の) リモートとして扱うべきかどうか
}

PUT (ETag サポートあり)

説明: サーバ設定や他の設定を置き換えます
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (既存の全ての設定を指定された設定で置き換えます)

{
    "config": {
        "core.trust_password": "my-new-password",
        "core.https_address": "1.2.3.4:8443"
    }
}

PATCH (ETag サポートあり)

説明: サーバ設定や他の設定を更新します
導入: patch API 拡張により
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (指定されたキーだけを更新し、残りの既存の設定はそのまま残ります)

{
    "config": {
        "core.trust_password": "my-new-password"
    }
}

`/1.0/certificates`

GET

説明: 信頼された証明書の一覧を返します
認証: trusted
操作: 同期
戻り値: 信頼された証明書の URL の一覧

戻り値

[
    "/1.0/certificates/3ee64be3c3c7d617a7470e14f2d847081ad467c8c26e1caad841c8f67f7c7b09"
]

POST

説明: 信頼された証明書を追加します
認証: trusted または untrusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "type": "client",                       // 証明書の種別 (keyring)、現在は client のみ
    "certificate": "PEM certificate",       // 提供される場合は有効な x509 形式の証明書。提供されない場合は接続のクライアント証明書が使用される
    "name": "foo",                          // 証明書の名前を指定可能。指定しない場合はリクエストの TLS ヘッダーのホスト名が使用される。
    "password": "server-trust-password"     // そのサーバのトラスト・パスワード (untrusted の場合にのみ必須)
}

`/1.0/certificates/<fingerprint>`

GET

説明: 信頼された証明書の情報
認証: trusted
操作: 同期
戻り値: 信頼された証明書を表す dict

出力

{
    "type": "client",
    "certificate": "PEM certificate",
    "name": "foo",
    "fingerprint": "SHA256 Hash of the raw certificate"
}

PUT (ETag サポートあり)

説明: 証明書のプロパティを置き換えます
導入: certificate_update API 拡張により
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "type": "client",
    "name": "bar"
}

PATCH (ETag サポートあり)

説明: 証明書のプロパティを更新します
導入: certificate_update API 拡張により
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "baz"
}

DELETE

説明: 信頼された証明書を削除します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

レスポンスの HTTP ステータスコードは 202 (Accepted)。

`/1.0/instances`

GET

説明: インスタンスの一覧
認証: trusted
操作: 同期
戻り値: このサーバがホストしているインスタンスの URL の一覧

戻り値

[
    "/1.0/instances/blah",
    "/1.0/instances/blah1"
]

POST (`?target=<member>` を任意で指定可能)

説明: 新しいインスタンスを作成します
認証: trusted
操作: 同期
戻り値: バックグラウンド操作または標準のエラー

入力 ("ubuntu/devel" というエイリアスを持つローカルイメージをベースとするインスタンス)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "instance_type": "c2.micro",                                        // リミットのベースとして使用するための任意で指定可能なインスタンスタイプ
    "source": {"type": "image",                                         // "image", "migration", "copy", "none" のいずれかを指定可能
               "alias": "ubuntu/devel"},                                // エイリアスの名前
}

入力 (フィンガープリントで識別されるローカルのイメージをベースとするインスタンス)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "image",                                         // "image", "migration", "copy", "none" のいずれかを指定可能
               "fingerprint": "SHA-256"},                               // フィンガープリント
}

入力 (指定したイメージのプロパティに対して最も最近マッチしたイメージをベースとするインスタンス)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "image",                                         // "image", "migration", "copy", "none" のいずれかを指定可能
               "properties": {                                          // プロパティ
                    "os": "ubuntu",
                    "release": "18.04",
                    "architecture": "x86_64"
                }},
}

入力 (事前に作成済みの rootfs を除いたインスタンス、既存のインスタンスにアタッチする際に有用)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "none"},                                         // "image", "migration", "copy", "none" のいずれかを指定可能
}

入力 (公開されたリモートのイメージを使用)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "image",                                         // "image", "migration", "copy", "none" のいずれかを指定可能
               "mode": "pull",                                          // "local" (デフォルト) か "pull" のいずれか
               "server": "https://10.0.2.3:8443",                       // リモートサーバ (pull モードのときのみ)
               "protocol": "lxd",                                       // プロトコル (lxd か simplestreams のいずれか、デフォルトは lxd)
               "certificate": "PEM certificate",                        // PEM 証明書を指定可能。未指定の場合はシステムの CA が使用される。
               "alias": "ubuntu/devel"},                                // エイリアスの名前
}

入力 (プライベートなリモートのイメージをそのイメージのシークレットを取得した後に使用)

{
    "name": "my-new-instance",                                          // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                            // プロファイルの一覧
    "ephemeral": true,                                                  // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                      // 設定のオーバーライド
    "devices": {                                                        // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "image",                                         // "image", "migration", "copy", "none" のいずれかを指定可能
               "mode": "pull",                                          // "local" (デフォルト) か "pull" のいずれか
               "server": "https://10.0.2.3:8443",                       // リモートサーバ (pull モードのときのみ)
               "secret": "my-secret-string",                            // イメージを取得するために使用するシークレット (pull モードのときのみ)
               "certificate": "PEM certificate",                        // PEM 証明書を指定可能。未指定の場合はシステムの CA が使用される。
               "alias": "ubuntu/devel"},                                // エイリアスの名前
}

入力 (マイグレーション・ウェブソケットで送られるリモートのインスタンスを使用)

{
    "name": "my-new-instance",                                                      // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                                        // プロファイルの一覧
    "ephemeral": true,                                                              // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                                  // 設定のオーバーライド
    "devices": {                                                                    // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "migration",                                                 // "image", "migration", "copy", "none" のいずれかを指定可能
               "mode": "pull",                                                      // 現状 "pull" と "push" がサポートされる
               "operation": "https://10.0.2.3:8443/1.0/operations/<UUID>",          // リモート操作への完全な URL
               "certificate": "PEM certificate",                                    // PEM 証明書を指定可能。未指定の場合はシステムの CA が使用される。
               "base-image": "<fingerprint>",                                       // 任意で指定可能。インスタンスが作られたベースのイメージ
               "instance_only": true,                                               // スナップショットなしでインスタンスだけをマイグレーションするかどうか。 "true" か "false" のいずれか。
               "secrets": {"control": "my-secret-string",                           // マイグレーションのソースと通信する際に使用するシークレット
                           "criu":    "my-other-secret",
                           "fs":      "my third secret"}
    }
}

入力 (ローカルのインスタンスを使用)

{
    "name": "my-new-instance",                                                      // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "profiles": ["default"],                                                        // プロファイルの一覧
    "ephemeral": true,                                                              // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                                  // 設定のオーバーライド
    "devices": {                                                                    // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "copy",                                                      // "image", "migration", "copy", "none" のいずれかを指定可能
               "instance_only": true,                                               // スナップショットなしでインスタンスだけをマイグレーションするかどうか。 "true" か "false" のいずれか。
               "source": "my-old-instance"}                                         // 作成元のインスタンスの名前
}

入力 (クライアントプロキシ経由でマイグレーションウェブソケット越しに push モードで送られるリモートインスタンスを使用)

{
    "name": "my-new-instance",                                                      // 最大 64 文字、 ASCII が使用可、スラッシュ、コロン、カンマは使用不可
    "architecture": "x86_64",
    "profiles": ["default"],                                                        // プロファイルの一覧
    "ephemeral": true,                                                              // シャットダウン時にインスタンスを破棄するかどうか
    "config": {"limits.cpu": "2"},                                                  // 設定のオーバーライド
    "devices": {                                                                    // インスタンスが持つデバイスの任意で指定可能なリスト
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        },
    },
    "source": {"type": "migration",                                                 // "image", "migration", "copy", "none" のいずれかを指定可能
               "mode": "push",                                                      // "pull" と "push" がサポートされている
               "base-image": "<fingerprint>",                                       // 任意で指定可能。インスタンスが作られたベースのイメージ
               "live": true,                                                        // マイグレーションが live で実行されるかどうか
               "instance_only": true}                                               // スナップショットなしでインスタンスだけをマイグレーションするかどうか。 "true" か "false" のいずれか。
}

入力 (バックアップを使用)

バックアップダウンロードにより提供される生の圧縮された tarball

`/1.0/instances/<name>`

GET

説明: インスタンスの情報
認証: trusted
操作: 同期
戻り値: インスタンスの設定と現在の状態の dict `

出力

{
    "architecture": "x86_64",
    "config": {
        "limits.cpu": "3",
        "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
        "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
    },
    "created_at": "2016-02-16T01:05:05Z",
    "devices": {
        "rootfs": {
            "path": "/",
            "type": "disk"
        }
    },
    "ephemeral": false,
    "expanded_config": {    // プロファイルを展開したものにインスタンスのローカルの設定を追加した結果
        "limits.cpu": "3",
        "volatile.base_image":  "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
        "volatile.eth0.hwaddr":: "00:16:3e:1c:94:38"
    },
    "expanded_devices": {   // プロファイルを展開したものにインスタンスのローカルのデバイスを追加した結果
        "eth0": {
            "name": "eth0",
            "nictype": "bridgedd",
            "parent": "lxdbr0",,
            "type": "nic"
        },
        "root": {
            "path": "/",
            "type": "disk"
        }
    },
    "last_used_at": "2016-02-166T01:05:05Z",
    "name": "my-instance",
    "profiles": [
        "default"
    ],
    "stateful": false,      // true の場合はインスタンスがスタートアップ時に復元できる何らかの保管された状態を持つことを意味する
    "status": "Running",
    "status_code": 103
}

PUT (ETag サポートあり)

説明: インスタンスの設定を置き換えるかスナップショットをリストアします
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (インスタンスの設定を更新します)

{
    "architecture": "x86_64",
    "config": {
        "limits.cpu": "4",
        "volatile.base_image": "97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
        "volatile.eth0.hwaddr": "00:16:3e:1c:94:38"
    },
    "devices": {
        "rootfs": {
            "path": "/",
            "type": "disk"
        }
    },
    "ephemeral": true,
    "profiles": [
        "default"
    ]
}

GET の戻り値と同じ構造を持つが、名前の変更は許されず (以下の POST 参照)、 status の sub-dict への変更も許されません (status の sub-dict は読み取り専用のため)。

入力 (スナップショットをリストアします)

{
    "restore": "snapshot-name"
}

PATCH (ETag サポートあり)

説明: インスタンスの設定を更新します
導入: patch API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "limits.cpu": "4"
    },
    "devices": {
        "rootfs": {
            "size": "5GB"
        }
    },
    "ephemeral": true
}

POST (`?target=<member>` を任意で指定可能)

説明: インスタンスをリネーム／マイグレーションするのに用いられます
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

既に存在する名前にリネームしようとすると 409 (Conflict) という HTTP ステータスコードを返します。

入力 (単純なリネーム)

{
    "name": "new-name"
}

入力 (lxd インスタンスまたは lxd クラスタメンバ間でのマイグレーション)

{
    "name": "new-name",
    "migration": true,
    "live": "true"
}

誰か (つまり他の lxd インスタンス) が全てのウェブソケットに接続してソースと交渉を始めるまでは、マイグレーションは実際には開始されません。

クラスタメンバ間でマイグレーションするには ?target=<member> オプションが必要です。

メタデータセクション内の出力 (マイグレーションの場合)

{
    "control": "secret1",       // マイグレーション制御ソケット
    "criu": "secret2",          // 状態転送ソケット (ライブマイグレーションのときのみ)
    "fs": "secret3"             // ファイルシステム転送ソケット
}

これらは作成の呼び出し時に渡すべきシークレットです。

DELETE

説明: インスタンスを削除します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP レスポンスのステータスコードは 202 (Accepted) です。

`/1.0/instances/<name>/console`

GET

説明: インスタンスのコンソールログの内容を返します
認証: trusted
操作: 該当なし
戻り値: コンソールログの内容

POST

説明: インスタンスのコンソールデバイスにアタッチします
認証: trusted
操作: 非同期
戻り値: 標準のエラー

入力 (/dev/console にアタッチします)

{
    "width": 80,                    // 端末の初期の幅 (任意で指定可能)
    "height": 25                    // 端末の初期の高さ (任意で指定可能)
}

制御用ウェブソケットがコンソールセッションの out-of-band メッセージの送信に使用されます。現状ではウィンドウサイズの変更に使われています。

制御 (ウィンドウサイズの変更)

{
    "command": "window-resize",
    "args": {
        "width": "80",
        "height": "50"
    }
}

DELETE

説明: インスタンスのコンソールログを空にします
認証: trusted
操作: 同期
戻り値: 空のレスポンスまたは標準のエラー

`/1.0/instances/<name>/exec`

POST

説明: リモートコマンドを実行します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作 + 任意で指定可能な websocket 情報あるいは標準のエラー

入力 (bash を実行する例です)

{
    "command": ["/bin/bash"],       // コマンドと引数
    "environment": {},              // 追加で設定する任意で指定可能な環境変数
    "wait-for-websocket": false,    // プロセスを開始する前に接続を待つかどうか
    "record-output": false,         // 標準出力と標準エラー出力を記録するかどうか (wait-for-websocket=false のときのみ有効) (container_exec_recording API 拡張が必要)
    "interactive": true,            // PIPE の代わりに pts デバイスを割り当てるかどうか
    "width": 80,                    // 端末の初期の幅 (任意で指定可能)
    "height": 25,                   // 端末の初期の高さ (任意で指定可能)
    "user": 1000,                   // コマンドを実行するユーザー (任意で指定可能)
    "group": 1000,                  // コマンドを実行するグループ (任意で指定可能)
    "cwd": "/tmp"                   // 現在の作業ディレクトリ (任意で指定可能)
}

wait-for-websocket は操作をブロックしウェブソケットの接続が (オプショナルである control を除く) 全ての利用可能なファイルディスクリプタに対して開始するのを待つか、あるいは即座に開始するかを指示します。これによりユーザーが標準入力を渡したり、標準出力や標準エラー出力の出力をバイト列として読み取る選択肢を提供します。

即座に開始する場合、 /dev/null が標準入力、標準出力、標準エラー出力に使われます。これは record-output が true に設定されない場合です。 true に設定される場合は、標準出力と標準エラー出力はログファイルにリダイレクトされます。

interactive が true に設定される場合は、 1 つのウェブソケットが返され、それが実行されたプロセスの標準入力、標準出力、標準エラー出力用の pts デバイスにマッピングされます。

interactive が false (デフォルト) に設定される場合は、標準入力、標準出力、標準エラー出力に 1 つずつ、合計 3 つのパイプがセットアップされます。

interactive フラグの状態によって、 1 つまたは 3 つのウェブソケットとシークレットの組が返され、それはこの操作の /websocket エンドポイントに接続するのに有効です。

実行セッションの間、制御用のウェブソケットが out-of-band メッセージを送るのに利用できます。これは現状はウィンドウサイズの変更とシグナルのフォワーディングに使われています。

制御 (ウィンドウサイズの変更)

{
    "command": "window-resize",
    "args": {
        "width": "80",
        "height": "50"
    }
}

制御 (SIGUSR1 シグナル)

{
    "command": "signal",
    "signal": 10
}

戻り値 (wait-for-websocket=true で interactive=false の場合)

{
    "fds": {
        "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
        "1": "464dcf9f8fdce29d0d6478284523a9f26f4a31ae365d94cd38bac41558b797cf",
        "2": "25b70415b686360e3b03131e33d6d94ee85a7f19b0f8d141d6dca5a1fc7b00eb",
        "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
    }
}

戻り値 (wait-for-websocket=true で interactive=true の場合)

{
    "fds": {
        "0": "f5b6c760c0aa37a6430dd2a00c456430282d89f6e1661a077a926ed1bf3d1c21",
        "control": "20c479d9532ab6d6c3060f6cdca07c1f177647c9d96f0c143ab61874160bd8a5"
    }
}

戻り値 (interactive=false で record-output=true の場合)

{
    "output": {
        "1": "/1.0/instances/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stdout",
        "2": "/1.0/instances/example/logs/exec_b0f737b4-2c8a-4edf-a7c1-4cc7e4e9e155.stderr"
    },
    "return": 0
}

実行コマンドが終了した時は、終了ステータスが操作のメタデータに含まれます。

{
    "return": 0
}

`/1.0/instances/<name>/files`

GET (`?path=/path/inside/the/instance`)

説明: ファイルかディレクトリの内容をインスタンスからダウンロードします
認証: trusted
操作: 同期
戻り値: ファイルの種別がディレクトリの場合、戻り値はメタデータにディレクトリの内容の一覧を含んだ同期的なレスポンスになり、それ以外の種別の場合はファイルの生の内容になります。

次のヘッダがセットされます (標準のサイズと MIME タイプのヘッダに加えて)

X-LXD-uid: 0
X-LXD-gid: 0
X-LXD-mode: 0700
X-LXD-type: directory か file のいずれか

これはコマンドラインあるいはウェブブラウザからでさえ簡単に使えるように設計されています。

POST (`?path=/path/inside/the/instance`)

説明: インスタンスにファイルをアップロードします
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 * 標準的な HTTP のファイルアップロード

クライアントは次のヘッダを設定しても構いません。

X-LXD-uid: 0
X-LXD-gid: 0
X-LXD-mode: 0700
X-LXD-type: directory, file, symlink のいずれか
X-LXD-write: overwrite (か append。 append は file_append API 拡張によって導入されます)

これはコマンドラインあるいはウェブブラウザからでさえ簡単に使えるように設計されています。

DELETE (`?path=/path/inside/the/instance`)

説明: インスタンス内のファイルを削除します
導入: file_delete API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

`/1.0/instances/<name>/snapshots`

GET

説明: スナップショットの一覧
認証: trusted
操作: 同期
戻り値: このインスタンスのスナップショットの URL の一覧

戻り値

[
    "/1.0/instances/blah/snapshots/snap0"
]

POST

説明: 新しいスナップショットを作成します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "name": "my-snapshot",          // スナップショットの名前
    "stateful": true                // 状態も含めるかどうか
}

`/1.0/instances/<name>/snapshots/<name>`

GET

説明: スナップショットの情報
認証: trusted
操作: 同期
戻り値: スナップショットを表す dict

戻り値

{
    "architecture": "x86_64",
    "config": {
        "security.nesting": "true",
        "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
        "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
        "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
    },
    "created_at": "2016-03-08T23:55:08Z",
    "devices": {
        "eth0": {
            "name": "eth0",
            "nictype": "bridged",
            "parent": "lxdbr0",
            "type": "nic"
        },
        "root": {
            "path": "/",
            "type": "disk"
        },
    },
    "ephemeral": false,
    "expanded_config": {
        "security.nesting": "true",
        "volatile.base_image": "a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
        "volatile.eth0.hwaddr": "00:16:3e:ec:65:a8",
        "volatile.last_state.idmap": "[{\"Isuid\":true,\"Isgid\":false,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536},{\"Isuid\":false,\"Isgid\":true,\"Hostid\":100000,\"Nsid\":0,\"Maprange\":65536}]",
    },
    "expanded_devices": {
        "eth0": {
            "name": "eth0",
            "nictype": "bridged",
            "parent": "lxdbr0",
            "type": "nic"
        },
        "root": {
            "path": "/",
            "type": "disk"
        },
    },
    "name": "blah",
    "profiles": [
        "default"
    ],
    "size": 738476032,
    "stateful": false
}

POST

説明: スナップショットをリネーム／マイグレートします
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (スナップショットをリネーム)

{
    "name": "new-name"
}

入力 (マイグレーション元をセットアップ)

{
    "name": "new-name",
    "migration": true,
    "live": "true"
}

戻り値 (migration=true の場合)

{
    "control": "secret1",       // マイグレーション制御ソケット
    "fs": "secret3"             // ファイルシステム転送ソケット
}

既に存在する名前にリネームしようとすると 409 (Conflict) という HTTP ステータスコードが返ります。

default プロファイルをリネームしようとすると 403 (Forbidden) という HTTP ステータスコードが返ります。

DELETE

説明: スナップショットを削除します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (現在は何もなし)

{
}

PUT

説明: スナップショットを更新します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

Input:

{
    "expires_at": "2019-01-16T12:34:56+02:00"
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

`/1.0/instances/<name>/state`

GET

説明: 現在の状態
認証: trusted
操作: 同期
戻り値: 現在の状態を表す dict

出力

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "metadata": {
        "status": "Running",
        "status_code": 103,
        "cpu": {
            "usage": 4986019722
        },
        "disk": {
            "root": {
                "usage": 422330368
            }
        },
        "memory": {
            "usage": 51126272,
            "usage_peak": 70246400,
            "swap_usage": 0,
            "swap_usage_peak": 0
        },
        "network": {
            "eth0": {
                "addresses": [
                    {
                        "family": "inet",
                        "address": "10.0.3.27",
                        "netmask": "24",
                        "scope": "global"
                    },
                    {
                        "family": "inet6",
                        "address": "fe80::216:3eff:feec:65a8",
                        "netmask": "64",
                        "scope": "link"
                    }
                ],
                "counters": {
                    "bytes_received": 33942,
                    "bytes_sent": 30810,
                    "packets_received": 402,
                    "packets_sent": 178
                },
                "hwaddr": "00:16:3e:ec:65:a8",
                "host_name": "vethBWTSU5",
                "mtu": 1500,
                "state": "up",
                "type": "broadcast"
            },
            "lo": {
                "addresses": [
                    {
                        "family": "inet",
                        "address": "127.0.0.1",
                        "netmask": "8",
                        "scope": "local"
                    },
                    {
                        "family": "inet6",
                        "address": "::1",
                        "netmask": "128",
                        "scope": "local"
                    }
                ],
                "counters": {
                    "bytes_received": 86816,
                    "bytes_sent": 86816,
                    "packets_received": 1226,
                    "packets_sent": 1226
                },
                "hwaddr": "",
                "host_name": "",
                "mtu": 65536,
                "state": "up",
                "type": "loopback"
            },
            "lxdbr0": {
                "addresses": [
                    {
                        "family": "inet",
                        "address": "10.0.3.1",
                        "netmask": "24",
                        "scope": "global"
                    },
                    {
                        "family": "inet6",
                        "address": "fe80::68d4:87ff:fe40:7769",
                        "netmask": "64",
                        "scope": "link"
                    }
                ],
                "counters": {
                    "bytes_received": 0,
                    "bytes_sent": 570,
                    "packets_received": 0,
                    "packets_sent": 7
                },
                "hwaddr": "6a:d4:87:40:77:69",
                "host_name": "",
                "mtu": 1500,
                "state": "up",
                "type": "broadcast"
           },
           "zt0": {
                "addresses": [
                    {
                        "family": "inet",
                        "address": "29.17.181.59",
                        "netmask": "7",
                        "scope": "global"
                    },
                    {
                        "family": "inet6",
                        "address": "fd80:56c2:e21c:0:199:9379:e711:b3e1",
                        "netmask": "88",
                        "scope": "global"
                    },
                    {
                        "family": "inet6",
                        "address": "fe80::79:e7ff:fe0d:5123",
                        "netmask": "64",
                        "scope": "link"
                    }
                ],
                "counters": {
                    "bytes_received": 0,
                    "bytes_sent": 806,
                    "packets_received": 0,
                    "packets_sent": 9
                },
                "hwaddr": "02:79:e7:0d:51:23",
                "host_name": "",
                "mtu": 2800,
                "state": "up",
                "type": "broadcast"
            }
        },
        "pid": 13663,
        "processes": 32
    }
}

PUT

説明: インスタンスの状態を変更する
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "action": "stop",       // 状態を変更するアクション (stop, start, restart, freeze, unfreeze のいずれか)
    "timeout": 30,          // 状態の変更が失敗したと判定するまでのタイムアウト
    "force": true,          // 状態の変更を強制する (現状では stop と restart でのみ有効で、インスタンスを強制停止することを意味します)
    "stateful": true        // 停止または開始する前の状態を保管または復元するかどうか (stop と start でのみ有効、デフォルトは false)
}

`/1.0/instances/<name>/logs`

GET

説明: このインスタンスで利用可能なログファイルの一覧を返します。作成の失敗についてのログを取得できるようにするため、この操作は削除が完了した (あるいは一度も作られなかった) インスタンスに対しても動作します。
認証: trusted
操作: 同期
戻り値: 利用可能なログファイルの一覧

戻り値

[
    "/1.0/instances/blah/logs/forkstart.log",
    "/1.0/instances/blah/logs/lxc.conf",
    "/1.0/instances/blah/logs/lxc.log"
]

`/1.0/instances/<name>/logs/<logfile>`

GET

説明: 特定のログファイルの中身を返します
認証: trusted
操作: 該当なし
戻り値: ログファイルの中身

DELETE

説明: 特定のログファイルを削除します
認証: trusted
操作: 同期
戻り値: 空のレスポンスまたは標準のエラー

`/1.0/instances/<name>/metadata`

GET

説明: インスタンスのメタデータ
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: インスタンスのメタデータを表す dict

戻り値

{
    "architecture": "x86_64",
    "creation_date": 1477146654,
    "expiry_date": 0,
    "properties": {
        "architecture": "x86_64",
        "description": "BusyBox x86_64",
        "name": "busybox-x86_64",
        "os": "BusyBox"
    },
    "templates": {
        "/template": {
            "when": [
                ""
            ],
            "create_only": false,
            "template": "template.tpl",
            "properties": {}
        }
    }
}

PUT (ETag サポートあり)

説明: インスタンスのメタデータを置き換える
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "architecture": "x86_64",
    "creation_date": 1477146654,
    "expiry_date": 0,
    "properties": {
        "architecture": "x86_64",
        "description": "BusyBox x86_64",
        "name": "busybox-x86_64",
        "os": "BusyBox"
    },
    "templates": {
        "/template": {
            "when": [
                ""
            ],
            "create_only": false,
            "template": "template.tpl",
            "properties": {}
        }
    }
}

`/1.0/instances/<name>/metadata/templates`

GET

説明: インスタンステンプレートの一覧
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: インスタンステンプレート名の一覧

戻り値

[
    "template.tpl",
    "hosts.tpl"
]

GET (`?path=<template>`)

説明: インスタンステンプレートの中身
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: テンプレートの中身

POST (`?path=<template>`)

説明: インスタンステンプレートを追加します
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 * 標準的な HTTP のファイルアップロード

PUT (`?path=<template>`)

説明: テンプレートの中身を置き換えます
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 * 標準的な HTTP のファイルアップロード

DELETE (`?path=<template>`)

説明: コンテナーテンプレートを削除します
導入: container_edit_metadata API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

`/1.0/instances/<name>/backups`

GET

説明: インスタンスのバックアップの一覧
導入: container_backup API 拡張によって
認証: trusted
操作: 同期
戻り値: インスタンスのバックアップの一覧

戻り値

[
    "/1.0/instances/c1/backups/c1/backup0",
    "/1.0/instances/c1/backups/c1/backup1",
]

POST

説明: 新しいバックアップを作成します
導入: container_backup API 拡張によって
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "name": "backupName",      // バックアップのユニークな識別子
    "expiry": 3600,            // いつ自動的にバックアップを削除するか
    "instance_only": true,     // true の場合、スナップショットは含まれません
    "optimized_storage": true  // true の場合 btrfs send または zfs send がインスタンスとスナップショットに対して使用されます
}

`/1.0/instances/<name>/backups/<name>`

GET

説明: バックアップの情報
導入: container_backup API 拡張によって
認証: trusted
操作: 同期
戻り値: バックアップの dict

出力

{
    "name": "backupName",
    "creation_date": "2018-04-23T12:16:09+02:00",
    "expiry_date": "2018-04-23T12:16:09+02:00",
    "instance_only": false,
    "optimized_storage": false
}

DELETE

説明: バックアップを削除します
導入: container_backup API 拡張によって
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

POST

説明: バックアップをリネームします
導入: container_backup API 拡張によって
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "name": "new-name"
}

`/1.0/instances/<name>/backups/<name>/export`

GET

説明: バックアップの tarball を取得します
導入: container_backup API 拡張によって
認証: trusted
操作: 同期
戻り値: バックアップの tarball を含む dict

出力

{
    "data": "<byte-stream>"
}

`/1.0/events`

この URL は真の REST API エンドポイントではなく、代わりに GET クエリを実行すると接続をウェブソケットにアップグレードし、そのウェブソケット上で通知が送信されます。

GET (`?type=operation,logging`)

説明: ウェブソケットへのアップグレード
認証: trusted
操作: 同期
戻り値: なし (イベントのフローが終わることはありません)

サポートされる引数は次のとおりです。

type: 購読する通知のカンマ区切りリスト (デフォルトは all)

通知の種別は次のとおりです。

operation (作成、更新、終了という全てのバックグラウンド操作についての通知)
logging (サーバからの全てのログエントリー)
lifecycle (インスタンスのライフサイクルイベント)

このエンドポイントの出力が完了することはありません。それぞれの通知は個別の JSON dict として送られます。

{
    "timestamp": "2015-06-09T19:07:24.379615253-06:00",                // 現在のタイムスタンプ
    "type": "operation",                                               // 通知の種別
    "metadata": {}                                                     // リソースまたはタイプに特有な追加のメタデータ
}

{
    "timestamp": "2016-02-17T11:44:28.572721913-05:00",
    "type": "logging",
    "metadata": {
        "context": {
            "ip": "@",
            "method": "GET",
            "url": "/1.0/instances/xen/snapshots",
        },
        "level": "info",
        "message": "handling"
    }
}

`/1.0/images`

GET

説明: (public または private の) イメージの一覧
認証: guest または trusted
操作: 同期
戻り値: このサーバが提供しているイメージの URL の一覧

戻り値

[
    "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
    "/1.0/images/97d97a3d1d053840ca19c86cdd0596cf1be060c5157d31407f2a4f9f350c78cc",
    "/1.0/images/a49d26ce5808075f5175bf31f5cb90561f5023dcd408da8ac5e834096d46b2d8",
    "/1.0/images/c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
]

POST

説明: 新しいイメージを作成し提供する
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (次のいずれか 1 つ)

標準の HTTP ファイルアップロード
作成元のイメージの dict (リモートのイメージを転送する場合)
作成元のインスタンスの dict (ローカルインスタンスからイメージを作成する場合)
リモートのイメージの URL の dict (リモートのイメージをダウンロードする場合)

HTTP ファイルアップロードの場合、次のヘッダがクライアントにより設定可能です。

X-LXD-fingerprint: SHA-256 (設定された場合はアップロードされたファイルのフィンガープリントが一致する必要があります)
X-LXD-filename: FILENAME (エクスポートの際に使用されます)
X-LXD-public: true/false (デフォルトは false)
X-LXD-properties: 重複したキーを除いたキーと値のペアを URL エンコードしたもの (任意で指定可能なプロパティ)

作成元としてイメージを使う場合、次の dict を使用する必要があります。

{
    "filename": filename,                   // エクスポートの際に使用されます (任意で指定可能)
    "public": true,                         // 信頼されないユーザーがイメージをダウンロードしてよいか (デフォルトは false)
    "auto_update": true,                    // イメージを自動更新するかどうか (任意で指定可能、デフォルトは false)
    "properties": {                         // イメージのプロパティ (任意で指定可能、作成元のプロパティに追加して適用されます)
        "os": "Ubuntu"
    },
    "aliases": [                            // 初期のエイリアスを設定します ("image_create_aliases" API 拡張)
        {"name": "my-alias",
         "description": "A description"}
    ],
    "source": {
        "type": "image",
        "mode": "pull",                     // 現在は pull のみがサポートされています
        "server": "https://10.0.2.3:8443",  // リモートサーバ (pull モードのときのみ)
        "protocol": "lxd",                  // プロトコル (lxd または simplestreams、デフォルトは lxd)
        "secret": "my-secret-string",       // シークレット (pull モードのときのみ、 private なイメージのみ)
        "certificate": "PEM certificate",   // 任意で指定可能な PEM 証明書。指定されない場合はシステム CA が使用されます
        "fingerprint": "SHA256",            // イメージのフィンガープリント (エイリアスを指定しない場合は必須です)
        "alias": "ubuntu/devel",            // エイリアスの名前 (フィンガープリントを指定しない場合は必須です)
    }
}

作成元にインスタンスを使う場合、次の dict を使用する必要があります。

{
    "compression_algorithm": "xz",  // イメージの圧縮アルゴリズムをオーバーライドします (任意で指定可能)
    "filename": filename,           // エクスポートの際に使用されます (任意で指定可能)
    "public":   true,               // 信頼されないユーザーがイメージをダウンロードしてよいか (デフォルトは false)
    "properties": {                 // イメージのプロパティ (任意で指定可能)
        "os": "Ubuntu"
    },
    "aliases": [                    // 初期のエイリアスを設定します ("image_create_aliases" API 拡張)
        {"name": "my-alias",
         "description": "A description""}
    ],
    "source": {
        "type": "instance",         // "instance" か "snapshot" のいずれか
        "name": "abc"
    }
}

リモートイメージの URL の場合は、次の dict を使用する必要があります。

{
    "filename": filename,                           // エクスポートの際に使用されます (任意で指定可能)
    "public":   true,                               // 信頼されないユーザーがイメージをダウンロードしてよいか (デフォルトは false)
    "properties": {                                 // イメージのプロパティ (任意で指定可能)
        "os": "Ubuntu"
    },
    "aliases": [                                    // 初期のエイリアスを設定します ("image_create_aliases" API 拡張)
        {"name": "my-alias",
         "description": "A description"}
    ],
    "source": {
        "type": "url",
        "url": "https://www.some-server.com/image"  // イメージの URL
    }
}

LXD が入力を受け取った後、バックグラウンド操作が開始され、イメージをストアに追加し、場合によってバックエンドファイルシステムに特有ななんらかの最適化を行います。

`/1.0/images/<fingerprint>`

GET (`?secret=SECRET` を任意に指定可能)

説明: イメージの説明とメタデータ
認証: guest または trusted
操作: 同期
戻り値: イメージのプロパティを表す dict

出力

{
    "aliases": [
        {
            "name": "bionic",
            "description": "",
        }
    ],
    "architecture": "x86_64",
    "auto_update": true,
    "cached": false,
    "fingerprint": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473",
    "filename": "ubuntu-bionic-18.04-amd64-server-20180201.tar.xz",
    "properties": {
        "architecture": "x86_64",
        "description": "Ubuntu 18.04 LTS server (20180601)",
        "os": "ubuntu",
        "release": "bionic"
    },
    "update_source": {
        "server": "https://10.1.2.4:8443",
        "protocol": "lxd",
        "certificate": "PEM certificate",
        "alias": "ubuntu/bionic/amd64"
    },
    "public": false,
    "size": 123792592,
    "created_at": "2016-02-01T21:07:41Z",
    "expires_at": "1970-01-01T00:00:00Z",
    "last_used_at": "1970-01-01T00:00:00Z",
    "uploaded_at": "2016-02-16T00:44:47Z"
}

PUT (ETag サポートあり)

説明: イメージのプロパティを置き換えたり、情報や公開状態を変更します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "auto_update": true,
    "properties": {
        "architecture": "x86_64",
        "description": "Ubuntu 18.04 LTS server (20180601)",
        "os": "ubuntu",
        "release": "bionic"
    },
    "public": true,
}

PATCH (ETag サポートあり)

説明: イメージのプロパティを変更したり、情報や公開状態を変更します
導入: patch API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "properties": {
        "os": "ubuntu",
        "release": "bionic"
    },
    "public": true,
}

DELETE

説明: イメージを削除します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

`/1.0/images/<fingerprint>/export`

GET (`?secret=SECRET` を任意で指定可能)

説明: イメージの tarball をダウンロードします
認証: guest または trusted
操作: 同期
戻り値: 生のファイルまたは標準のエラー

信頼されていない LXD が別の LXD に保管されている private なイメージから新しいインスタンスを起動する場合は secret の文字列が必要です。

2 つの LXD の間で信頼関係を要求する代わりに、クライアントは /1.0/images/<fingerprint>/export に POST のリクエストを送ってシークレットトークンを取得し、それをエクスポート先の LXD に渡すことが出来ます。エクスポート先の LXD はシークレットトークンを渡してイメージを guest として取得します。

`/1.0/images/<fingerprint>/refresh`

POST

説明: イメージをオリジンからリフレッシュします
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

これは指定されたイメージをオリジンからリフレッシュする操作を作成します。

`/1.0/images/<fingerprint>/secret`

POST

説明: ランダムなトークンを生成し、ゲストが使用することを LXD に伝えます
認証: guest または trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
}

戻り値

{
    "secret": "52e9ec5885562aa24d05d7b4846ebb8b5f1f7bf5cd6e285639b569d9eaf54c9b"
}

メタデータ内の "secret" に生成されたシークレットの文字列が設定された標準のバックグランド操作です。

シークレットはそれを使うイメージ URL にアクセスされてから 5 秒後に自動的に無効化されます。これによりイメージの情報の取得とその後の /export の呼び出しの両方に同じシークレットが使えます。

`/1.0/images/aliases`

GET

説明: エイリアスの一覧 (イメージの公開状態に応じて public または private なエイリアスが含まれます)
認証: guest または trusted
操作: 同期
戻り値: このサーバが知っているエイリアスの URL の一覧

戻り値

[
    "/1.0/images/aliases/sl6",
    "/1.0/images/aliases/bionic",
    "/1.0/images/aliases/xenial"
]

POST

説明: 新しいエイリアスを作成します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "description": "The alias description",
    "target": "SHA-256",
    "name": "alias-name"
}

`/1.0/images/aliases/<name>`

GET

説明: エイリアスの説明とターゲット
認証: guest または trusted
操作: 同期
戻り値: エイリアスの説明とターゲットを表す dict

出力

{
    "name": "test",
    "description": "my description",
    "target": "c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
}

PUT (ETag サポートあり)

説明: エイリアスのターゲットまたは説明を置き換えます
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "description": "New description",
    "target": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
}

PATCH (ETag サポートあり)

説明: エイリアスのターゲットまたは説明を更新します
導入: patch API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "description": "New description"
}

POST

説明: エイリアスをリネームします
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "new-name"
}

既に存在する名前にリネームしようとすると 409 (Conflict) の HTTP ステータスコードを返します。

DELETE

説明: エイリアスを削除します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

`/1.0/networks`

GET

説明: ネットワークの一覧
認証: trusted
操作: 同期
戻り値: ホストに現在定義されているネットワークの URL の一覧

戻り値

[
    "/1.0/networks/eth0",
    "/1.0/networks/lxdbr0"
]

POST

説明: 新しいネットワークを定義します
導入: network API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "my-network",
    "description": "My network",
    "config": {
        "ipv4.address": "none",
        "ipv6.address": "2001:470:b368:4242::1/64",
        "ipv6.nat": "true"
    }
}

`/1.0/networks/<name>`

GET

説明: ネットワークについての情報
認証: trusted
操作: 同期
戻りt: ネットワークを表す dict

戻り値

{
    "config": {},
    "name": "lxdbr0",
    "managed": false,
    "type": "bridge",
    "used_by": [
        "/1.0/instances/blah"
    ]
}

PUT (ETag サポートあり)

説明: ネットワークの情報を置き換えます
導入: network API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "bridge.driver": "openvswitch",
        "ipv4.address": "10.0.3.1/24",
        "ipv6.address": "fd1:6997:4939:495d::1/64"
    }
}

初期の作成や GET での情報取得結果と同じ dict です。ただし、 config のキーだけが使用され、それ以外の全てのキーは無視されます。

PATCH (ETag supported)

説明: ネットワークの情報を更新します。
導入: network API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "dns.mode": "dynamic"
    }
}

POST

説明: ネットワークをリネームします
導入: network API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (ネットワークをリネームします)

{
    "name": "new-name"
}

HTTP ステータスコードは 204 (No content) で Location ヘッダはリネーム後のリソースの URL を指します。

既に存在する名前にリネームしようとすると 409 (Conflict) の HTTP ステータスコードを返します。

DELETE

説明: ネットワークを削除します
導入: network API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

`/1.0/networks/<name>/state`

GET

説明: ネットワークの状態
認証: trusted
操作: 同期
戻り値: ネットワークの状態を表す dict

戻り値

{
    "addresses": [
        {
            "family": "inet",
            "address": "10.87.252.1",
            "netmask": "24",
            "scope": "global"
        },
        {
            "family": "inet6",
            "address": "fd42:6e0e:6542:a212::1",
            "netmask": "64",
            "scope": "global"
        },
        {
            "family": "inet6",
            "address": "fe80::3419:9ff:fe9b:f9aa",
            "netmask": "64",
            "scope": "link"
        }
    ],
    "counters": {
        "bytes_received": 0,
        "bytes_sent": 17724,
        "packets_received": 0,
        "packets_sent": 95
    },
    "hwaddr": "36:19:09:9b:f9:aa",
    "mtu": 1500,
    "state": "up",
    "type": "broadcast"
}

`/1.0/operations`

GET

説明: 操作の一覧
認証: trusted
操作: 同期
戻り値: 状態ごとの現在実行中またはキューに追加された操作の URL の一覧を表す dict

戻り値

{
    "success": [
        "/1.0/operations/c0fc0d0d-a997-462b-842b-f8bd0df82507"
    ],
    "running": [
        "/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
    ]
}

`/1.0/operations/<uuid>`

GET

説明: バックグラウンド操作
認証: trusted
操作: 同期
戻り値: バックグラウンド操作を表す dict

戻り値

{
    "id": "b8d84888-1dc2-44fd-b386-7f679e171ba5",
    "class": "token",                                                                       // "task" (バックグラウンドのタスク), "websocket" (ウェブソケットと認証情報の組) あるいは "token" (一時的な認証情報)
    "created_at": "2016-02-17T16:59:27.237628195-05:00",                                    // 作成時のタイムスタンプ
    "updated_at": "2016-02-17T16:59:27.237628195-05:00",                                    // 最終更新時のタイムスタンプ
    "status": "Running",
    "status_code": 103,
    "resources": {                                                                          // 影響を受けるリソースの一覧
        "images": [
            "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
        ]
    },
    "metadata": {                                                                           // 操作についての追加情報 (action, target, ...)
        "secret": "c9209bee6df99315be1660dd215acde4aec89b8e5336039712fc11008d918b0d"
    },
    "may_cancel": true,                                                                     // (DELETE で) 操作をキャンセルできるかどうか
    "err": ""
}

DELETE

説明: 操作をキャンセルします。この API を呼び出すとエントリーを実際に削除するのではなく状態を "cancelling" に変更します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

`/1.0/operations/<uuid>/wait`

GET (`?timeout=30` を任意で指定可能)

説明: 操作が完了するのを待ちます
認証: trusted
操作: 同期
戻り値: 操作が最終の状態に達した後の操作の dict

入力 (最終の状態まで無限に待つ場合): 引数なし

入力 (同様に最終の状態まで待つが 30 秒後にタイムアウトする場合): ?timeout=30

`/1.0/operations/<uuid>/websocket`

GET (`?secret=SECRET`)

説明: この接続はウェブソケットの接続にアップグレードされ、操作の種別毎に定義されたプロトコルを話します。例えば exec 操作の場合、ウェブソケットは標準入力／標準出力／標準エラー出力のための双方向のパイプになり、インスタンス内のプロセスの入出力をやりとりします。 migration の場合はマイグレーション情報を通信するプライマリのインターフェースになります。ここで使用するシークレットは操作を作るときに指定していたのと同じものを指定します。正しいシークレットを指定すればゲストもこのエンドポイントに接続できます。
認証: guest または trusted
操作: 同期
戻り値: ウェブソケットのストリームまたは標準のエラー

`/1.0/profiles`

GET

説明: 設定プロファイルの一覧
認証: trusted
操作: 同期
戻り値: 定義されているプロファイルの URL の一覧

戻り値

[
    "/1.0/profiles/default"
]

POST

説明: 新しいプロファイルを定義します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "my-profilename",
    "description": "Some description string",
    "config": {
        "limits.memory": "2GB"
    },
    "devices": {
        "kvm": {
            "type": "unix-char",
            "path": "/dev/kvm"
        }
    }
}

`/1.0/profiles/<name>`

GET

説明: プロファイルの設定
認証: trusted
操作: 同期
戻り値: プロファイルの設定を表す dict

出力

{
    "name": "test",
    "description": "Some description string",
    "config": {
        "limits.memory": "2GB"
    },
    "devices": {
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        }
    },
    "used_by": [
        "/1.0/instances/blah"
    ]
}

PUT (ETag サポートあり)

説明: プロファイルの情報を置き換えます
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "limits.memory": "4GB"
    },
    "description": "Some description string",
    "devices": {
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        }
    }
}

初期の作成や GET での情報取得結果と同じ dict です。 name プロパティは変更できません (変更するには POST を参照してください)。

PATCH (ETag サポートあり)

説明: プロファイルの情報を変更します
導入: patch API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "limits.memory": "4GB"
    },
    "description": "Some description string",
    "devices": {
        "kvm": {
            "path": "/dev/kvm",
            "type": "unix-char"
        }
    }
}

POST

説明: プロファイルをリネームします
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (プロファイルをリネームします)

{
    "name": "new-name"
}

HTTP ステータスコードは 204 (No content) で Location ヘッダはリネーム後のリソースの URL を指します。

既に存在する名前にリネームしようとすると 409 (Conflict) の HTTP ステータスコードを返します。

DELETE

説明: プロファイルを削除します
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

default プロファイルを削除しようとすると 403 (Forbidden) という HTTP ステータスコードが返ります。

`/1.0/projects`

GET

説明: プロジェクトの一覧
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: 定義済みのプロジェクトの URL の一覧

戻り値

[
    "/1.0/projects/default"
]

POST

説明: 新しいプロジェクトを定義します
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "test",
    "config": {
        "features.images": "true",
        "features.profiles": "true",
    },
    "description": "Some description string"
}

`/1.0/projects/<name>`

GET

説明: プロジェクトの設定
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: プロジェクトの内容を表す dict

出力

{
    "name": "test",
    "config": {
        "features.images": "true",
        "features.profiles": "true",
    },
    "description": "Some description string",
    "used_by": [
        "/1.0/instances/blah"
    ]
}

PUT (ETag サポートあり)

説明: プロジェクトの情報を置き換えます
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "features.images": "true",
        "features.profiles": "true",
    },
    "description": "Some description string"
}

初期作成への入力と GET の戻り値は同じ形式の dict が使用されます。 name プロパティは変更できません (その用途には POST を参照してください)。

PATCH (ETag サポートあり)

説明: プロジェクトの情報を更新します
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "features.images": "true",
    },
    "description": "Some description string"
}

POST

説明: プロジェクトをリネームします
導入: projects API 拡張によって
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (プロジェクトをリネームします)

{
    "name": "new-name"
}

HTTP ステータスコードは 204 (No content) で Location ヘッダはリネーム後のリソースの URL を指します。

既に存在する名前にリネームしようとすると 409 (Conflict) の HTTP ステータスコードを返します。

default プロジェクトをリネームしようとすると 403 (Forbidden) という HTTP ステータスコードが返ります。

DELETE

説明: プロジェクトを削除します
導入: projects API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

この操作に対する HTTP ステータスコードは 202 (Accepted) です。

default プロジェクトを削除しようとすると 403 (Forbidden) という HTTP ステータスコードが返ります。

`/1.0/storage-pools`

GET

説明: ストレージプールの一覧
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: ホストに現在定義されているストレージプールの一覧

戻り値

[
    "/1.0/storage-pools/default",
    "/1.0/storage-pools/pool1",
    "/1.0/storage-pools/pool2",
    "/1.0/storage-pools/pool3",
    "/1.0/storage-pools/pool4"
]

POST

説明: 新しいストレージプールを作成します
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "size": "10GB"
    },
    "driver": "zfs",
    "name": "pool1"
}

`/1.0/storage-pools/<name>`

GET

説明: ストレージプールの情報
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: ストレージプールを表す dict

戻り値

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "operation": "",
    "error_code": 0,
    "error": "",
    "metadata": {
        "name": "default",
        "driver": "zfs",
        "used_by": [
            "/1.0/instances/alp1",
            "/1.0/instances/alp10",
            "/1.0/instances/alp11",
            "/1.0/instances/alp12",
            "/1.0/instances/alp13",
            "/1.0/instances/alp14",
            "/1.0/instances/alp15",
            "/1.0/instances/alp16",
            "/1.0/instances/alp17",
            "/1.0/instances/alp18",
            "/1.0/instances/alp19",
            "/1.0/instances/alp2",
            "/1.0/instances/alp20",
            "/1.0/instances/alp3",
            "/1.0/instances/alp4",
            "/1.0/instances/alp5",
            "/1.0/instances/alp6",
            "/1.0/instances/alp7",
            "/1.0/instances/alp8",
            "/1.0/instances/alp9",
            "/1.0/images/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
        ],
        "config": {
            "size": "61203283968",
            "source": "/home/chb/mnt/l2/disks/default.img",
            "volume.size": "0",
            "zfs.pool_name": "default"
        }
    }
}

PUT (ETag サポートあり)

説明: ストレージプールの情報を置き換えます
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "size": "15032385536",
        "source": "pool1",
        "volume.block.filesystem": "xfs",
        "volume.block.mount_options": "discard",
        "lvm.thinpool_name": "LXDThinPool",
        "lvm.vg_name": "pool1",
        "volume.size": "10737418240"
    }
}

PATCH

説明: ストレージプールの設定を変更します
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "volume.block.filesystem": "xfs",
    }
}

DELETE

説明: ストレージプールを削除します
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

`/1.0/storage-pools/<name>/resources`

GET

説明: ストレージプールで利用可能なリソースに関する情報
導入: resources API 拡張によって
認証: trusted
操作: 同期
戻り値: ストレージプールのリソースを表す dict

戻り値

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "operation": "",
    "error_code": 0,
    "error": "",
    "metadata": {
        "space": {
            "used": 207111192576,
            "total": 306027577344
        },
        "inodes": {
            "used": 3275333,
            "total": 18989056
        }
    }
}

`/1.0/storage-pools/<name>/volumes`

GET

説明: ストレージボリュームの一覧
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 指定されたストレージプール上に現在存在するストレージボリュームの一覧

戻り値

[
    "/1.0/storage-pools/default/volumes/container/alp1",
    "/1.0/storage-pools/default/volumes/container/alp10",
    "/1.0/storage-pools/default/volumes/container/alp11",
    "/1.0/storage-pools/default/volumes/container/alp12",
    "/1.0/storage-pools/default/volumes/container/alp13",
    "/1.0/storage-pools/default/volumes/container/alp14",
    "/1.0/storage-pools/default/volumes/container/alp15",
    "/1.0/storage-pools/default/volumes/container/alp16",
    "/1.0/storage-pools/default/volumes/container/alp17",
    "/1.0/storage-pools/default/volumes/container/alp18",
    "/1.0/storage-pools/default/volumes/container/alp19",
    "/1.0/storage-pools/default/volumes/container/alp2",
    "/1.0/storage-pools/default/volumes/container/alp20",
    "/1.0/storage-pools/default/volumes/container/alp3",
    "/1.0/storage-pools/default/volumes/container/alp4",
    "/1.0/storage-pools/default/volumes/container/alp5",
    "/1.0/storage-pools/default/volumes/container/alp6",
    "/1.0/storage-pools/default/volumes/container/alp7",
    "/1.0/storage-pools/default/volumes/container/alp8",
    "/1.0/storage-pools/default/volumes/container/alp9",
    "/1.0/storage-pools/default/volumes/image/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
]

POST

説明: 指定されたストレージプール上に新しいストレージボリュームを作成します
導入: storage API 拡張によって
認証: trusted
操作: 同期または (既存のボリュームをコピーする場合は) 非同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {},
    "name": "vol1",
    "type": "custom"
}

入力 (ボリュームをコピーする場合)

{
    "config": {},
    "name": "vol1",
    "type": "custom",
    "source": {
        "pool": "pool2",
        "name": "vol2",
        "type": "copy"
    }
}

入力 (ボリュームをマイグレーションする場合)

{
    "config": {},
    "name": "vol1",
    "type": "custom"
    "source": {
        "pool": "pool2",
        "name": "vol2",
        "type": "migration",
        "mode": "pull"        // "pull" (デフォルト), "push", "relay" のいずれか
    }
}

`/1.0/storage-pools/<pool>/volumes/<type>`

POST

説明: 指定のストレージプール上に特定のタイプのストレージボリュームを作成します
導入: storage API 拡張によって
認証: trusted
操作: 同期または (既存のボリュームをコピーする場合は) 非同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {},
    "name": "vol1",
}

入力 (ボリュームをコピーする場合)

{
    "config": {},
    "name": "vol1",
    "source": {
        "pool": "pool2",
        "name": "vol2",
        "type": "copy"
    }
}

入力 (ボリュームをマイグレーションする場合)

{
    "config": {},
    "name": "vol1",
    "source": {
        "pool": "pool2",
        "name": "vol2",
        "type": "migration"
        "mode": "pull",      // "pull" (デフォルト), "push", "relay" のいずれか
    }
}

`/1.0/storage-pools/<pool>/volumes/<type>/<name>`

POST

説明: 指定のストレージプール上のストレージボリュームをリネームします
導入: storage_api_volume_rename API 拡張によって
認証: trusted
操作: 同期または (別のプールに移動する場合は) 非同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "name": "vol1",
    "pool": "pool3"
}

入力 (lxd インスタンス間でマイグレーションする場合)

{
    "name": "vol1",
    "pool": "pool3",
    "migration": true
}

誰か (つまり他の lxd インスタンス) が全てのウェブソケットに接続してソースと交渉を始めるまでは、マイグレーションは実際には開始されません。

出力のメタデータのセクション (マイグレーションの場合)

{
    "control": "secret1",       // マイグレーション制御ソケット
    "fs": "secret2"             // ファイルシステム転送ソケット
}

これらは作成の呼び出し時に渡すべきシークレットです。

GET

説明: ストレージプール上の指定のタイプのストレージボリュームの情報
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: ストレージボリュームを表す dict

戻り値

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "error_code": 0,
    "error": "",
    "metadata": {
        "type": "custom",
        "used_by": [],
        "name": "vol1",
        "config": {
            "block.filesystem": "ext4",
            "block.mount_options": "discard",
            "size": "10737418240"
        }
    }
}

PUT (ETag サポートあり)

説明: ストレージボリュームの情報を置き換えるかスナップショットから復元します
導入: storage, storage_api_volume_snapshots API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

(訳注: ストレージボリュームの情報を置き換える場合の入力)

{
    "config": {
        "size": "15032385536",
        "source": "pool1",
        "used_by": "",
        "volume.block.filesystem": "xfs",
        "volume.block.mount_options": "discard",
        "lvm.thinpool_name": "LXDThinPool",
        "lvm.vg_name": "pool1",
        "volume.size": "10737418240"
    }
}

(訳注: スナップショットから復元する場合の入力)

{
    "restore": "snapshot-name"
}

PATCH (ETag サポートあり)

説明: ストレージボリュームの情報を変更します
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "config": {
        "volume.block.mount_options": "",
    }
}

DELETE

説明: 指定したストレージプール上の指定したタイプのストレージボリュームを削除します
導入: storage API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力 (現在は何もなし)

{
}

`/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`

GET

説明: ボリュームスナップショットの一覧
認証: trusted
操作: 同期
戻り値: このボリュームのスナップショットの URL の一覧

戻り値

[
    "/1.0/storage-pools/default/volumes/custom/foo/snapshots/snap0"
]

POST

説明: 新規のボリュームスナップショットを作成する
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "name": "my-snapshot",          // スナップショットの名前
}

`/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/name`

GET

説明: スナップショットの情報
認証: trusted
操作: 同期
戻り値: スナップショットを表す dict

戻り値

{
    "config": {},
    "description": "",
    "name": "snap0"
}

PUT

説明: ボリュームスナップショットの情報
認証: trusted
操作: 同期
戻り値: ボリュームスナップショットを表す dict

入力

{
    "description": "new-description"
}

POST

説明: ボリュームスナップショットをリネームするのに使用されます
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力

{
    "name": "new-name"
}

DELETE

説明: ボリュームスナップショットを削除します
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

レスポンスの HTTP ステータスコードは 202 (Accepted)。

`/1.0/resources`

GET

説明: LXD サーバで利用可能なリソースに関する情報
導入: resources API 拡張によって
認証: guest, untrusted または trusted
操作: 同期
戻り値: システムリソースを表す dict

戻り値

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "operation": "",
    "error_code": 0,
    "error": "",
    "metadata": {
        "cpu": {
            "sockets": [
               {
                   "cores": 2,
                   "frequency": 2691,
                   "frequency_turbo": 3400,
                   "name": "GenuineIntel",
                   "vendor": "Intel(R) Core(TM) i5-3340M CPU @ 2.70GHz",
                   "threads": 4
               }
            ],
            "total": 4
        },
        "memory": {
            "used": 4454240256,
            "total": 8271765504
        }
    }
}

`/1.0/cluster`

GET

説明: クラスタの情報 (ネットワークやストレージプールなど)
導入: clustering API 拡張によって
認証: trusted または untrusted
操作: 同期
戻り値: クラスタを表す dict

戻り値

{
    "server_name": "node1",
    "enabled": true,
    "member_config": [
        {
            "entity": "storage-pool",
            "name": "local",
            "key": "source",
            "description": "\"source\" property for storage pool \"local\"",
        },
        {
            "entity": "network",
            "name": "lxdbr0",
            "key": "bridge.external_interfaces",
            "description": "\"bridge.external_interfaces\" property for network \"lxdbr0\"",
        },
    ],
}

PUT

説明: このノード上のクラスタをブートストラップしたりクラスタに参加したり、クラスタリングを無効にします
導入: clustering API 拡張によって
認証: trusted
操作: 同期または非同期
戻り値: 入力によってさまざまなペイロード

入力 (新しいクラスタをブートストラップする場合)

{
    "server_name": "lxd1",
    "enabled": true,
}

バックグラウンド操作か標準のエラーを返します。

入力 (既存のクラスタに参加を依頼する場合)

{
    "server_name": "node2",
    "server_address": "10.1.1.102:8443",
    "enabled": true,
    "cluster_address": "10.1.1.101:8443",
    "cluster_certificate": "-----BEGIN CERTIFICATE-----MIFf\n-----END CERTIFICATE-----",
    "cluster_password": "sekret",
    "member_config": [
        {
            "entity": "storage-pool",
            "name": "local",
            "key": "source",
            "value": "/dev/sdb"
        },
        {
            "entity": "network",
            "name": "lxdbr0",
            "key": "bridge.external_interfaces",
            "value": "vlan0"
        }
    ]
}

入力 (このノード上のクラスタリングを無効にする場合)

{
    "enabled": false
}

`/1.0/cluster/members`

GET

説明: クラスタ内の LXD メンバの一覧
導入: clustering API 拡張によって
認証: trusted
操作: 同期
戻り値: クラスタメンバの一覧

戻り値

[
    "/1.0/cluster/members/lxd1",
    "/1.0/cluster/members/lxd2"
]

`/1.0/cluster/members/<name>`

GET

説明: メンバの情報と状態を取得します
導入: clustering API 拡張によって
認証: trusted
操作: 同期
戻り値: メンバを表す dict

戻り値

{
    "server_name": "lxd1",
    "url": "https://10.1.1.101:8443",
    "database": true,
    "status": "Online",
    "message":"fully operational"
}

POST

説明: クラスタメンバをリネームします
導入: clustering API 拡張によって
認証: trusted
操作: 同期
戻り値: 標準の戻り値または標準のエラー

入力

{
    "server_name": "node1"
}

DELETE (`?force=1` を任意で指定可能)

説明: クラスタのメンバを削除します
導入: clustering API 拡張によって
認証: trusted
操作: 非同期
戻り値: バックグラウンド操作または標準のエラー

入力 (現在は何もなし)

{
}

REST API

イントロダクション

API のバージョニング

戻り値

標準の戻り値

バックグラウンド操作

エラー

ステータスコード

現在使用されているステータスコード一覧

再帰

フィルタ

非同期操作

通知

PUT と PATCH の使い分け

インスタンス、コンテナーと仮想マシン

API 構造

API 詳細

/

GET

/1.0/

GET

PUT (ETag サポートあり)

PATCH (ETag サポートあり)

/1.0/certificates

GET

POST

/1.0/certificates/<fingerprint>

GET

PUT (ETag サポートあり)

PATCH (ETag サポートあり)

DELETE

/1.0/instances

GET

POST (?target=<member> を任意で指定可能)

/1.0/instances/<name>

GET

PUT (ETag サポートあり)

PATCH (ETag サポートあり)

POST (?target=<member> を任意で指定可能)

DELETE

/1.0/instances/<name>/console

GET

POST

DELETE

/1.0/instances/<name>/exec

POST

/1.0/instances/<name>/files

GET (?path=/path/inside/the/instance)

POST (?path=/path/inside/the/instance)

DELETE (?path=/path/inside/the/instance)

/1.0/instances/<name>/snapshots

GET

POST

/1.0/instances/<name>/snapshots/<name>

GET

POST

DELETE

PUT

/1.0/instances/<name>/state

GET

PUT

/1.0/instances/<name>/logs

GET

/1.0/instances/<name>/logs/<logfile>

GET

DELETE

/1.0/instances/<name>/metadata

GET

PUT (ETag サポートあり)

/1.0/instances/<name>/metadata/templates

GET

GET (?path=<template>)

POST (?path=<template>)

PUT (?path=<template>)

DELETE (?path=<template>)

/1.0/instances/<name>/backups

GET

POST

/1.0/instances/<name>/backups/<name>

GET

`/`

`/1.0/`

`/1.0/certificates`

`/1.0/certificates/<fingerprint>`

`/1.0/instances`

POST (`?target=<member>` を任意で指定可能)

`/1.0/instances/<name>`

POST (`?target=<member>` を任意で指定可能)

`/1.0/instances/<name>/console`

`/1.0/instances/<name>/exec`

`/1.0/instances/<name>/files`

GET (`?path=/path/inside/the/instance`)

POST (`?path=/path/inside/the/instance`)

DELETE (`?path=/path/inside/the/instance`)

`/1.0/instances/<name>/snapshots`

`/1.0/instances/<name>/snapshots/<name>`

`/1.0/instances/<name>/state`

`/1.0/instances/<name>/logs`

`/1.0/instances/<name>/logs/<logfile>`

`/1.0/instances/<name>/metadata`

`/1.0/instances/<name>/metadata/templates`

GET (`?path=<template>`)

POST (`?path=<template>`)

PUT (`?path=<template>`)

DELETE (`?path=<template>`)

`/1.0/instances/<name>/backups`

`/1.0/instances/<name>/backups/<name>`

`/1.0/instances/<name>/backups/<name>/export`

`/1.0/events`

GET (`?type=operation,logging`)

`/1.0/images`

`/1.0/images/<fingerprint>`

GET (`?secret=SECRET` を任意に指定可能)

`/1.0/images/<fingerprint>/export`

GET (`?secret=SECRET` を任意で指定可能)

`/1.0/images/<fingerprint>/refresh`

`/1.0/images/<fingerprint>/secret`

`/1.0/images/aliases`

`/1.0/images/aliases/<name>`

`/1.0/networks`

`/1.0/networks/<name>`

`/1.0/networks/<name>/state`

`/1.0/operations`

`/1.0/operations/<uuid>`

`/1.0/operations/<uuid>/wait`

GET (`?timeout=30` を任意で指定可能)

`/1.0/operations/<uuid>/websocket`

GET (`?secret=SECRET`)

`/1.0/profiles`

`/1.0/profiles/<name>`

`/1.0/projects`

`/1.0/projects/<name>`

`/1.0/storage-pools`