2018年1月12日金曜日

VMware VIC v1.3.0 の REST API を試してみた

概要
環境
インストール
API サーバを起動する
動作確認
(おまけ) Swagger UI でドキュメントを表示する
最後に
参考サイト

概要

VMware VIC v1.3.0 で VCH を REST API で作成できる機能が追加されました
とりあえず触ってみたので備忘録として残しておきます

環境

Ubuntu 16.04.3
VIC v1.3.0

インストール

実は執筆時点ではまだバイナリを直接ダウンロードすることはできません
My VMware から OVA をダウンロードすることはできます
今回はソースをダウンロードして自分でビルドしました
過去にやり方を紹介しているのでビルド方法はそちらを参照してください

最終的に vic-machine-server というバイナリがあれば OK です

API サーバを起動する

先程のビルドで生成されたものを使います

cd bin
./vic-machine-server --scheme=http --host=0.0.0.0 --port 18080

--port は好きなポートに変更してください

動作確認

curl を使っていろいろとコールしてみました

Hello World

とりあえずプロセスが正常に起動しているか確認してみましょう

curl -u 'vcenter-user:pass' 'http://localhost:18080/container/hello'

で「You have successfully accessed the VCH Management API.」と出れば起動成功です
ベースパスが /container になっているようなので必ず先頭に付与してください
今回認証はベーシック認証を使っています
vSphere Client などを使ってログインするユーザ名とパスワードを使ってログインしてください

vch を作成する

まずは vch を作成してみます
POST /taraget/{vcenterIP}/datacenter/{datacenterId}/vch を使います
必要な情報はリクエストボディに JSON を設定して送信します

curl \
-X POST \
-u 'vcenter-user:vcenter-pass' \
'http://localhost:18080/container/target/192.168.100.10/datacenter/datacenter-21/vch?thumbprint=F9%3A03%3A2C%3A25%3A45%3A07%3ACE%3A24%3A4F%3A14%3A70%3A95%3A7E%3AB4%3A68%3A87%3AB1%3A2E%3AC1%3AEC' \
-H 'content-type: application/json' \
-d @- << EOF
{
  "name": "test_vch",
  "compute": {
    "resource": {
      "name": "Cluster001"
    }
  },
  "storage": {
    "volume_stores": [{
      "datastore": "datastore1/test",
      "label": "default"
    }],
    "image_stores": ["datastore1"]
  },
  "network": {
    "bridge": {
      "ip_range": "172.16.0.0/12",
      "port_group": {
        "name": "vic-bridge-001"
      }
    },
    "public": {
      "port_group": {
        "name": "public_net"
      }
    }
  }
}
EOF

192.168.100.10 の部分は vCenter の IP を入力してください
また今回は vCenter が IP ベースの通信になるので thumbprint を指定します
compute-resource はクラスタ名を入力してください

ここでポイントなのがデータセンターの指定方法ですが vSphere Client で表示される名前ではないことに注意してください
dcli や mob で確認することができるデータセンター ID　になります
vSphere Client のブラウザ版であれば URL の部分に「objectId=urn:vmomi:Datacenter:datacenter-21」みたいな部分があるのでその値を使ってください
(クラスタ名は名前でいいのにデータセンター名は ID でなければいけない理由がよくわかりませんでした、、、)

そして重要なリクエストボディです
まず name で作成する vch 名を指定します
次に compute -> resource -> name でクラスタ名を指定します
上述の通りクラスタ名は mobID ではなく名前で OK です
あとは storage と network を指定します
storage は volume_stores と image_stores を指定します
image_stores は文字列でデータストア名を指定するだけなのですが、volume_stores は少し指定の仕方が違うので注意してください
network は bridge と public を指定します
bridge に関してはコンテナが起動した際に接続するネットワークのレンジを指定する必要があるので設定しましょう

これで VCH を作成することができます
他にも別のネットワークを設定したり証明書を設定したりすることができるパラメータがあります
詳しくは後述するドキュメントを参照してみてください

vch の一覧を取得する

次に作成した vch の情報を取得してみます
GET /taraget/{vcenterIP}/datacenter/{datacenterId}/vch/ を使います

curl \
-X GET \
-u 'vcenter-user:vcenter-pass' \
'http://localhost:18080/container/target/192.168.100.10/datacenter/datacenter-21/vch/vm-1304?thumbprint=F9%3A03%3A2C%3A25%3A45%3A07%3ACE%3A24%3A4F%3A14%3A70%3A95%3A7E%3AB4%3A68%3A87%3AB1%3A2E%3AC1%3AEC'

先ほどの登録とほぼ同じです
vchId を指定しないことで一覧を取得することができます
vchId を指定することで特定に vch の詳細情報を取得することができます
vic-machine コマンドで言うところの inspect 相当の情報が取得できます (後述)

レスポンスは以下の通りです

{
 "vchs": [
   {
     "admin_portal": "https://192.168.200.10:2378",
     "docker_host": "192.168.200.10:2375",
     "id": "vm-1293",
     "name": "test_vch",
     "upgrade_status": "VCH has newer version",
     "version": "v1.2.1-13858-c3db65f"
   }
 ]
}

ここで気がついたんですが version のところが v1.2.1 になっていました
My VMware でも v1.2 は配布していたのでもしかすると Github のバージョンは v1.3.0 でしたが、公式では v1.2 でも API 機能が含まれているかもしれません
単なる勘違いでした
API 経由で作成すれば問題なく v1.3.0 になっています

vch の詳細を取得する

指定した vch のみ取得してみましょう
GET /taraget/{vcenterIP}/datacenter/{datacenterId}/vch/{vchId} を使います

curl \
-X GET \
-u 'vcenter-user:vcenter-pass' \
'http://localhost:18080/container/target/192.168.100.10/datacenter/datacenter-21/vch/vm-1304?thumbprint=F9%3A03%3A2C%3A25%3A45%3A07%3ACE%3A24%3A4F%3A14%3A70%3A95%3A7E%3AB4%3A68%3A87%3AB1%3A2E%3AC1%3AEC'

ここでまたポイントなのですが vch を作成するときは vchId の部分に名前を指定しましたが詳細を取得する場合には ID を指定します
datacenter 同様 vch も ID を指定しないとそんな vch 見つからないと言われてエラーとなります

vch を削除する

最後に vch を削除してみます
先ほどの詳細を取得する API を DELETE でコールするだけです

curl \
-X DELETE \
-u 'vcenter-user:vcenter-pass' \
'http://localhost:18080/container/target/192.168.100.10/datacenter/datacenter-21/vch/vm-1302?thumbprint=F9%3A03%3A2C%3A25%3A45%3A07%3ACE%3A24%3A4F%3A14%3A70%3A95%3A7E%3AB4%3A68%3A87%3AB1%3A2E%3AC1%3AEC'

~~ただ以下のエラーが返ってきました~~

{
 "message": "VCH version \"v1.2.1-13858-c3db65f\" is different than API version v1.3.0-rc1-0-4c17da5"
}

~~おそらくバグかなと思います~~
~~vic-machine-linux であれば --force オプションを付与すれば削除することができました~~
~~My VMware からダウンロードできる公式版であればこのエラーは出ないのかもしれません~~
これも勘違いでした
問題なく削除できます

(おまけ) Swagger UI でドキュメントを表示する

swagger serve "http://127.0.0.1:18080/swagger.json" --port=28080 --no-open --host=0.0.0.0

--port で LISTEN するポートは好きに変更してください
これで http://127.0.0.1:28080/docs にブラウザでアクセスすると go-swagger の UI が表示されます

最後に

VMware VIC v1.3.0 で追加された API 機能を試してみました
バイナリを動かすだけなので簡単です
ドキュメントがまだ整備されていないので何ともですが swagger UI を見ながら頑張れば何とかなると思います

参考サイト

https://vmware.github.io/vic-product/assets/files/html/1.3/

hawksnowlog