LXCF - LXC Facility
Fork
edit= [[Embed(lxcficon.jpg)]] LXCFのREST-API
[FrontPage 元のページに戻る]
== LXCFのREST-API
REST APIは、WebのプロトコルHTTPを使ったネットワーク経由のインタフェースです。[[BR]]
次のような特徴を持ちます。[[BR]]
{{{
- ステートレスなクライアント/サーバプロトコル
- すべてのリソースに適用できる操作セット
- すべてのリソースは URI で表される一意的なアドレスを持つ
- アプリケーションの情報と状態遷移の両方を扱う
}}}
LXCFのREST APIは、主にHTTPのPOSTとGETの操作を使用します。[[BR]]
また、APIの発行時にはパスワードを付けてPOSTを行います。パスワードは空にすることができます。[[BR]]
=== 1. Browseable REST API
LXCFのAPI操作は、HTTPのPOST操作とGET操作を使用します。[[BR]]
POST操作でAPIの発行をします。[[BR]]
GET操作では、POST操作のためのhtmlを返します。[[BR]]
curlのようなネットワークツールを使用する場合には、POST操作だけでAPIを操作できます。[[BR]]
たとえば、コンテナの一覧を表示するlistは以下のようにします。
POST操作[[BR]]
{{{
$ curl -F " passwd='' " http://アドレス:ポート/lxcfv1/list
}}}
しかし、!FireFoxのようなブラウザでもLXCFの操作が可能になります。[[BR]]
ブラウザでアドレスバーに、REST APIを入力してEnterキーを押すと、GETが発行され、POST操作のための画面が表示されます。[[BR]]
アドレスバーには、"http://アドレス:ポート/lxcfv1/list"と入力します。[[BR]]
[[BR]]
[[Embed(lxcf-list-get.jpg)]]
[[BR]]
この画面上でパスワードを入力して、ボタンを押すと、アドレスバーに入力したAPIが発行されます。[[BR]]
[[BR]]
[[Embed(lxcf-list-post.jpg)]]
[[BR]]
簡単なGUIのように、ブラウザだけでLXCFを操作できます。[[BR]]
[[BR]]
このようなREST APIを、ここでは'''「Browseable REST API」'''と呼びます。[[BR]]
[[BR]]
=== 2. Browseable REST APIサービスの起動
Browseable REST APIは、デフォルトでは無効になっています。[[BR]]
Browseable REST APIを有効にするには、lxcf-apiサービスを起動する必要があります。[[BR]]
systemdまたはupstartのlxcf-apiサービスは、"lxcf api enable"コマンドで有効になります。[[BR]]
[[BR]]
{{{
# lxcf api enable
}}}
また、Browseable REST APIのアドレスとポート番号は、/etc/lxcf/lxcf.confで定義します。[[BR]]
初期値はlocalhostと8080が設定されています。[[BR]]
[[BR]]
{{{
#
# IP address and port for REST API
#
[rest_api]
ipaddr=localhost
port=8080
}}}
localhostが設定されていると、外部からはアクセスできません。[[BR]]
外部から接続するには、接続可能なIPアドレスかドメイン名を設定する必要があります。[[BR]]
[[BR]]
一度enabledにすれば、システムをrebootしてもenabledのままです。[[BR]]
Browseable REST APIをdisabledにするには、"lxcf api disable"コマンドを使います。[[BR]]
[[BR]]
{{{
# lxcf api disable
}}}
=== 3. Browseable REST APIの認証
Browseable REST APIのパスワードは以下のように"lxcf api-passwd"コマンドで設定します。[[BR]]
[[BR]]
{{{
# lxcf api-passwd
New password:
Retype new password:
}}}
エンターキーだけを押すと、パスワードは空になります。
=== 4. Browseable REST API リクエストの送信
LXCFのREST APIは、主にHTTPのPOSTとGETの操作を使用します。[[BR]]
また、APIの発行時にはパスワードを付けてPOSTを行います。パスワードは空にすることもできます。[[BR]]
REST APIを発行するときのURLのパスでAPIは規定されます。[[BR]]
URLは以下のような形式です。[[BR]]
[[BR]]
{{{
http://アドレス:ポート番号/lxcfv1/APIのパス
}}}
APIのパスは、lxcfコマンドで実行するときの空白を'/'に変えたものを指定します。[[BR]]
たとえば、a-srvというコンテナを作るコマンドは以下です。[[BR]]
[[BR]]
{{{
# lxcf sysgen a-srv
}}}
[[BR]]
これと同じ指定をREST APIで行う場合は以下です。[[BR]]
[[BR]]
{{{
http://アドレス:ポート番号/lxcfv1/sysgen/a-srv
}}}
=== 5. Browseable REST APIのデータ形式
Brouseable REST APIの返すデータ形式は以下のような形式です。[[BR]]
[[BR]]
{{{
<html>
<head>
ｈｔｍｌヘッド情報
</head>
<body>
<pre>
status=ステータス番号
返りメッセージ
</pre>
POST用html
</body>
</html>
}}}
ほとんどは、POST操作用のフォームを表示するためのHTML情報です。[[BR]]
大事なのは、その中の以下です。[[BR]]
{{{
status=ステータス番号
返りメッセージ
}}}
[[BR]]
ステータス番号は、正常ならば0が設定されています。[[BR]]
それ以外の値はエラーを示します。[[BR]]
帰りメッセージは、実行結果のメッセージが表示されます。[[BR]]
たとえば、次はlistのAPIの結果です。
[[BR]]
{{{
<html>
<head><title>LXCF API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
</head>
<body>
<pre>
status=0
Name Mode State Autostart Path
-------------------------------------------------------------------------
a-srv joint stopped n /opt/lxcf/a-srv
a0001 joint stopped n /opt/lxcf/a0001
</pre>
<HR><form action="http://localhost:8080/lxcfv1/list" method="POST" AcceptEncoding="utf-8">
<dl>
<dt>password</dt>
<dd><input type="password" name="password" value=""/></dd>
</dl>
<input type="submit" name="save" value="Execution" />
</form></body></html>
}}}
[[BR]]
<pre>から</pre>までが、APIの結果を示します。[[BR]]
=== 6. コマンドラインクライアント
ブラウザを使わないで、コマンドラインからcurlコマンドでREST APIを操作しましょう。
curlのようなネットワークツールを使用する場合には、POST操作だけでAPIを操作できます。[[BR]]
POST操作[[BR]]
{{{
$ curl -F " passwd=''パスワード " URL
}}}
URLは以下のような形式です。
[[BR]]
{{{
http://アドレス:ポート番号/lxcfv1/APIのパス
}}}
APIのパスは、lxcfコマンドで実行するときの空白を'/'に変えたものを指定します。[[BR]]
実行結果は<pre> 〜 </pre>に囲まれているので、たとえば以下のようにすると簡単に取り出せます。[[BR]]
[[BR]]
{{{
$ curl -F " passwd=''パスワード " URL | awk 'BEGIN{f=1}{if ($0~/pre/){f=f*(-1)}else if (f == -1) print}'
}}}
これらを組み合わせれば、シェルスクリプトで簡単にLXCFを操作する運用プログラムを作成できることでしょう。[[BR]]
Python, Perl, C言語のネットワークプログラムからも同様に扱えます。[[BR]]
=== 7. Browseable REST APIの一覧
resource controls [[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/cpun/(LXCFNAME or UUID)/CPU_NUMBER/
http://HOSTNAME:PORT/lxcfv1/cpurate/(LXCFNAME or UUID)/CPU_RATE/
http://HOSTNAME:PORT/lxcfv1/numa/(LXCFNAME or UUID)/NUMA_NUMBER/
http://HOSTNAME:PORT/lxcfv1/memlimit/(LXCFNAME or UUID)/MEMORY_LIMIT/
http://HOSTNAME:PORT/lxcfv1/memswlimit/(LXCFNAME or UUID)/MEMORY&SWAP_LIMIT/
http://HOSTNAME:PORT/lxcfv1/blkio_r/(LXCFNAME or UUID)/BLKIO_READ_LIMIT/
http://HOSTNAME:PORT/lxcfv1/blkio_w/(LXCFNAME or UUID)/BLKIO_WRITE_LIMIT/
http://HOSTNAME:PORT/lxcfv1/blkiops_r/(LXCFNAME or UUID)/BLKIOPS_READ_LIMIT/
http://HOSTNAME:PORT/lxcfv1/blkiops_w/(LXCFNAME or UUID)/BLKIOPS_WRITE_LIMIT/
http://HOSTNAME:PORT/lxcfv1/net_cls/(LXCFNAME or UUID)/NET_CLS_ID/
http://HOSTNAME:PORT/lxcfv1/show/[ (LXCFNAME or UUID) ]/
http://HOSTNAME:PORT/lxcfv1/set/[-c/CPURATE/][-i/CPU番号/ ][-n/NUMA番号/][-m/MEMLIMIT/][-s/MEMSWLIMIT/](LXCFNAME | UUID)/.../
}}}
container management[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/sysgen/[-p/パス/]コンテナ名/.../
http://HOSTNAME:PORT/lxcfv1/clone/[-p/パス/](元コンテナ名 or UUID)/新コンテナ名/.../
http://HOSTNAME:PORT/lxcfv1/erase/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/list/[-q/][(コンテナ名 or UUID)/.../]
http://HOSTNAME:PORT/lxcfv1/log/[-f/]
http://HOSTNAME:PORT/lxcfv1/autostart/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/rename/LXCFNAME/NEW-LXCFNAME/
}}}
start/stop management[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/start/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/stop/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/suspend/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/resume/(LXCFNAME or UUID)/.../
http://HOSTNAME:PORT/lxcfv1/run/(LXCFNAME or UUID)/CMD/
}}}
複数コンテナの操作[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/sysgen-n/[-p/path/ ][-c/resource-file/]コンテナ名プレフィックス/[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/clone-n/[-p/path/]コンテナ名プレフィックス/[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/erase-n/コンテナ名プレフィックス/[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/start-n/コンテナ名プレフィックス/[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/stop-n/コンテナ名プレフィックス/[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/resume-n/コンテナ名プレフィックス[数字初期値/]数字終了値/
http://HOSTNAME:PORT/lxcfv1/set-n/[-c/CPURATE/][-a/Num-of-CPU/][-i/CPU-Number/][-n/NUMA-Number/][-m/MEMLIMIT/][-s/ MEMSWLIMIT/]name-prefix/[start-number/]end-number/
http://HOSTNAME:PORT/lxcfv1/atuostart-n/[-d/]コンテナ名プレフィックス/[数字初期値/]数字終了値/
}}}
battch queue[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/submit/LXCFコマンド/
http://HOSTNAME:PORT/lxcfv1/queue/cancel/UUID/
http://HOSTNAME:PORT/lxcfv1/queue/clear/[-h/][-q/][-l/][-a/]
http://HOSTNAME:PORT/lxcfv1/queue/list/
http://HOSTNAME:PORT/lxcfv1/queue/move/[-h/][-q/][-l/]UUID /
http://HOSTNAME:PORT/lxcfv1/queue/multi/数/
}}}
snapshot & restore[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/snapshot/[-f/][-p/PATH/][-n/SNAPSHOT_IMAGE/](UUID | NAME)/
http://HOSTNAME:PORT/lxcfv1/restore/[-n/NEW_NAME/][-p/PATH/][-f/][-s/]SNAPSHOT_IMAGE/
http://HOSTNAME:PORT/lxcfv1/snapshot-pull/[-f/][-s/][-p/PASSWORD/][-n/NEW_SNAP_NAME/]SERVER_NAME:PORT/SNAPSHOT_NAME/
http://HOSTNAME:PORT/lxcfv1/snapshot-list/[-p/PASSWORD/][-i/SERVERNAME:PORT/][SNAPSHOT_IMAGE/...]/
http://HOSTNAME:PORT/lxcfv1/snapshot-erase/[-f/]SNAPSHOT_IMAGE/.../
}}}
export[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/export-docker/(UUID | NAME)/.../
}}}
help[[BR]]
{{{
http://HOSTNAME:PORT/lxcfv1/helpcmd/
http://HOSTNAME:PORT/lxcfv1/version/
}}}
[FrontPage 元のページに戻る]