インスタンス〜ホスト間の通信¶
ホストされているワークロード（インスタンス）とそのホストのコミュニケーションは 厳密には必要とされているわけではないですが、とても便利な機能です。
Incus ではこの機能は /dev/incus/sock というノードを通して実装されており、
このノードはすべての Incus のインスタンスに対して作成、セットアップされます。
このファイルはインスタンス内部のプロセスが接続できる Unix ソケットです。 マルチスレッドで動いているので複数のクライアントが同時に接続できます。
注釈
インスタンスのソケットへのアクセスを許可するには security.guestapi を true（これがデフォルトです）に設定する必要があります。
実装詳細¶
ホストでは Incus は /var/lib/incus/guestapi/sock をバインドして新しいコネクションの
リッスンを開始します。
このソケットは、Incus が開始させたすべてのインスタンス内の /dev/incus/sock に
公開されます。
4096 を超えるインスタンスを扱うのに単一のソケットが必要です。そうでなければ、 Incus は各々のインスタンスに異なるソケットをバインドする必要があり、 ファイルディスクリプター数の上限にすぐ到達してしまいます。
認証¶
/dev/incus/sock への問い合わせは依頼するインスタンスに関連した情報のみを
返します。リクエストがどこから来たかを知るために、 Incus は初期のソケットの
ユーザークレデンシャルを取り出し、 Incus が管理しているインスタンスのリストと比較します。
プロトコル¶
/dev/incus/sock のプロトコルは JSON メッセージを用いたプレーンテキストの
HTTP であり、 Incus プロトコルのローカル版に非常に似ています。
メインの Incus API とは異なり、 /dev/incus/sock API にはバックグラウンド処理と
認証サポートはありません。
REST-API¶
API の構造¶
//1.0/1.0/config/1.0/config/{key}
/1.0/devices/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",
"location": "foo.example.com",
"instance_type": "container",
"state": "Started",
}
PATCH¶
説明: インスタンスの状態を更新する（有効な状態は
ReadyとStarted）戻り値: 無し
入力:
{
"state": "Ready"
}
/1.0/config¶
GET¶
説明: 設定キーの一覧
出力: 設定キー URL のリスト
設定キーの名前はインスタンスの設定の名前と一致するようにしています。
しかし、設定の namespace のすべてが /dev/incus/sock にエクスポート
されているわけではありません。
現在は cloud-init.* と user.* キーのみがインスタンスにアクセス可能となっています。
現時点ではインスタンスが書き込み可能な名前空間はありません。
戻り値:
[
"/1.0/config/user.a"
]
/1.0/config/<KEY>¶
GET¶
説明: そのキーの値
出力: プレーンテキストの値
戻り値:
blah
/1.0/devices¶
GET¶
説明: インスタンスのデバイスのマップ
出力: dict
戻り値:
{
"eth0": {
"name": "eth0",
"network": "incusbr0",
"type": "nic"
},
"root": {
"path": "/",
"pool": "default",
"type": "disk"
}
}
/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: af6a01c7-f847-4688-a2a4-37fddd744625
local-hostname: abc