インスタンス〜ホスト間の通信

イントロダクション

ホストされているワークロード (インスタンス) とそのホストのコミュニケーションは厳密には必要とされているわけではないですが、とても便利な機能です。

LXD ではこの機能は /dev/lxd/sock というノードを通して実装されており、このノードは全ての LXD のインスタンスに対して作成、セットアップされます。

このファイルはインスタンス内部のプロセスが接続できる Unix ソケットです。マルチスレッドで動いているので複数のクライアントが同時に接続できます。

実装詳細

ホストでは LXD は /var/lib/lxd/devlxd/sock をバインドして新しいコネクションのリッスンを開始します。

このソケットは、LXD が開始させたすべてのインスタンス内の /dev/lxd/sock に公開されます。

4096 を超えるインスタンスを扱うのに単一のソケットが必要です。そうでなければ、 LXD は各々のインスタンスに異なるソケットをバインドする必要があり、ファイルディスクリプタ数の上限にすぐ到達してしまいます。

認証

/dev/lxd/sock への問い合わせは依頼するインスタンスに関連した情報のみを返します。リクエストがどこから来たかを知るために、 LXD は初期のソケットの ucred 構造体を取り出し、 LXD が管理しているインスタンスのリストと比較します。

プロトコル

/dev/lxd/sock のプロトコルは JSON メッセージを用いたプレーンテキストの HTTP であり、 LXD プロトコルのローカル版に非常に似ています。

メインの LXD API とは異なり、 /dev/lxd/sock API にはバックグラウンド処理と認証サポートはありません。

REST-API

API の構造

/
/1.0
- /1.0/config
- /1.0/config/{key}
- /1.0/events
- /1.0/images/{fingerprint}/export
- /1.0/meta-data

API の詳細

`/`

GET

* 説明: サポートされている API のリスト * 出力: サポートされている API エンドポイント URL のリスト (デフォルトでは ['/1.0']`)

戻り値:

[
    "/1.0"
]

`/1.0`

GET

* 説明: 1.0 API についての情報 * 出力: dict 形式のオブジェクト

戻り値:

{
    "api_version": "1.0"
}

`/1.0/config`

GET

* 説明: 設定キーの一覧 * 出力: 設定キー URL のリスト

設定キーの名前はインスタンスの設定の名前と一致するようにしています。しかし、設定の namespace の全てが /dev/lxd/sock にエクスポートされているわけではありません。現在は user.* キーのみがインスタンスにアクセス可能となっています。

現時点ではインスタンスが書き込み可能な名前空間はありません。

戻り値:

[
    "/1.0/config/user.a"
]

`/1.0/config/<KEY>`

GET

* 説明: そのキーの値 * 出力: プレーンテキストの値

戻り値:

blah

`/1.0/events`

GET

* 説明: この API ではプロトコルが websocket にアップグレードされます。 * 出力: 無し (イベントのフローが終わることがなくずっと続く)

サポートされる引数は以下の通りです。

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

通知の種別には以下のものがあります。

config (あらゆる user.* 設定キーの変更)
device (あらゆるデバイスの追加、変更、削除)

この API は決して終了しません。それぞれの通知は別々の JSON の dict として送られます。

{
    "timestamp": "2017-12-21T18:28:26.846603815-05:00",
    "type": "device",
    "metadata": {
        "name": "kvm",
        "action": "added",
        "config": {
            "type": "unix-char",
            "path": "/dev/kvm"
        }
    }
}

{
    "timestamp": "2017-12-21T18:28:26.846603815-05:00",
    "type": "config",
    "metadata": {
        "key": "user.foo",
        "old_value": "",
        "value": "bar"
    }
}

`/1.0/images/<FINGERPRINT>/export`

GET

* 説明: 公開されたあるいはキャッシュされたイメージをホストからダウンロードする * 出力: 生のイメージあるいはエラー * アクセス権: security.devlxd.images を true に設定する必要があります

戻り値:

LXD デーモン API の /1.0/images/<FINGERPRINT>/export を参照してください。

`/1.0/meta-data`

GET

* 説明: cloud-init と互換性のあるコンテナーのメタデータ * 出力: cloud-init のメタデータ

戻り値:

#cloud-config
instance-id: abc
local-hostname: abc