2018年1月10日水曜日

VMware Admiral v1.3.0 で REST API を使ってみた

概要

VMware Admiral には swagger ベースの API が実装されています
専用の UI でもいろいろと操作できますが API を使うこともできるので試してみました
Admiral のバージョンは最新の v1.3.0 を使っています

環境

  • Ubuntu 16.04.3
  • docker 17.05.0-ce
  • Admiral v1.3.0

Admiral の起動

  • docker run -d -p 8282:8282 --name admiral vmware/admiral

で http://localhost:8282/ にアクセスすると Admiral の管理 UI が表示されると思います

Swagger UI でドキュメントを確認する

まずは API のドキュメントを確認しましょう
Admiral にはすでに Swagger UI が組み込まれているので以下の URL にアクセスするだけでドキュメントが表示されます

http://localhost:8282/discovery/swagger/ui/

このドキュメントを元に API をコールしてみます

が実は、、、

Swagger はドキュメントの生成にのみ使われているようで更新も滞っているようです
https://github.com/vmware/admiral/issues/245
Wikiに最新版を作成中とのことなので現状はブラウザのネットワークコンソールを使ってリクエスト情報を確認しながらやるのがベストとのことでした
なので、今回もブラウザを使いながら curl リクエストを作成しています

プロジェクトの一覧を取得する

GET /projects を使って取得します
curl で以下のようにコールしましょう

  • curl -X GET http://localhost:8282/projects
{
  "documentLinks": [
    "/projects/default-project"
  ],
  "documentCount": 1,
  "queryTimeMicros": 1,
  "documentVersion": 0,
  "documentUpdateTimeMicros": 0,
  "documentExpirationTimeMicros": 0,
  "documentOwner": "a2f3cdc3-6d79-48e5-98ba-c88281cecff9"
}

Admiral はデフォルトで default-project というプロジェクトを持っているのでそれが表示されると思います
またデフォルトだと認証がないので REST API を認証なしでコールすることができます

プロジェクトを登録する

新規でプロジェクト作成してみます
POST /projects を使用します

  • curl -X POST http://localhost:8282/projects -H "Content-Type: application/json" -d '{"name":"test"}'

これでプロジェクトの追加ができます
Public のフラグなどは適宜変更してください

{
  "isPublic": false,
  "administratorsUserGroupLinks": [
    "/core/authz/user-groups/9cdba64fae7cbc75562520652cfa0_project-admins"
  ],
  "membersUserGroupLinks": [
    "/core/authz/user-groups/9cdba64fae7cbc75562520652cfa0_project-members"
  ],
  "viewersUserGroupLinks": [
    "/core/authz/user-groups/9cdba64fae7cbc75562520652cfa0_project-viewers"
  ],
  "id": "050ead14-58f7-4d1c-9795-336c604e4168",
  "name": "test3",
  "customProperties": {
    "__projectIndex": "550951311"
  },
  "tenantLinks": [
    "/projects/9cdba64fae7cbc75562520652cfa0"
  ],
  "creationTimeMicros": 1515479316485,
  "documentVersion": 0,
  "documentEpoch": 0,
  "documentKind": "com:vmware:admiral:auth:project:ProjectService:ProjectState",
  "documentSelfLink": "/projects/9cdba64fae7cbc75562520652cfa0",
  "documentUpdateTimeMicros": 1515479316484001,
  "documentUpdateAction": "POST",
  "documentExpirationTimeMicros": 0,
  "documentOwner": "a2f3cdc3-6d79-48e5-98ba-c88281cecff9"
}

プロジェクトを削除する

登録したテスト用のプロジェクトを削除してみましょう
DELETE /projects/{projectId} を使います

  • curl -X DELETE http://localhost:8282/projects/9cdba64fae7cbc755624ef84d4938

が、現状は 503 になり削除できませんでした
おそらくバグだと思います

クラスタを登録してみる

プロジェクト内にクラスタを登録してみましょう
POST /resources/clusters を使います

少し長いですがリクエストは以下の通りです

  • curl -X POST http://localhost:8282/resources/clusters -H "Content-Type: application/json" -H "x-project: /projects/default-project" -d '{"hostState":{"address":"http://192.168.100.11:2376","customProperties":{"__containerHostType":"DOCKER","__adapterDockerType":"API","__clusterName":"cluster001","__clusterDetails":"test","acceptCertificate":"false"}}}'

192.168.100.11 は TCP 2376 を LISTEN にした docker サーバです
(2376 ポートを有効にして docker をリモートから操作できるようにする方法はこちらの記事を参考にしてください)

クラスタ名は cluster001 でプロジェクト default-project にクラスタとホストを追加します
ポイントとしてはプロジェクトは x-project というヘッダで指定します
また body 側ではホストの情報とコンテナホストが docker or vch を指定する必要があります
成功すると以下のレスポンスが返ってきます

{
 "name": "cluster001",
 "type": "DOCKER",
 "status": "ON",
 "clusterCreationTimeMicros": 1515543281334,
 "details": "test",
 "containerCount": 0,
 "systemContainersCount": 0,
 "totalMemory": 0,
 "memoryUsage": 0,
 "nodeLinks": [
   "/resources/compute/9cdba64fae7cbc7556260eaed6c20"
 ],
 "nodes": {
   "/resources/compute/9cdba64fae7cbc7556260eaed6c20": {
     "address": "http://192.168.100.11:2376",
     "powerState": "ON",
     "documentVersion": 1,
     "documentEpoch": 0,
     "documentKind": "com:vmware:photon:controller:model:resources:ComputeService:ComputeState",
     "documentSelfLink": "/resources/compute/9cdba64fae7cbc7556260eaed6c20",
     "documentUpdateTimeMicros": 1515543281381009,
     "documentUpdateAction": "PATCH",
     "documentExpirationTimeMicros": 0,
     "documentOwner": "a2f3cdc3-6d79-48e5-98ba-c88281cecff9"
   }
 },
 "totalCpu": 0,
 "cpuUsage": 0,
 "documentVersion": 0,
 "documentSelfLink": "/resources/clusters/9cdba64fae7cbc7556260eaecfad8",
 "documentUpdateTimeMicros": 0,
 "documentExpirationTimeMicros": 0
}

Admiral の管理画面で確認すると以下のようになっています
admiral_api1.jpg

クラスタを取得する

登録したクラスタ情報を API で取得してみます
GET /resources/clusters を使います

  • curl -X GET -H "x-project: /projects/default-project" http://localhost:8282/resources/clusters

指定のプロジェクト配下にあるクラスタを取得する場合は POST 時と同様にヘッダでプロジェクトを指定します
ヘッダの指定がない場合はすべてのクラスタを取得します
レスポンスは以下のように取得できます

{
 "documentLinks": [
   "/resources/clusters/9cdba64fae7cbc7556260eaecfad8"
 ],
 "documentCount": 1,
 "documentVersion": 0,
 "documentUpdateTimeMicros": 0,
 "documentExpirationTimeMicros": 0
}

更にクラスタの詳細を取得したい場合はクラスタの ID を URI に含めるだけで OK です

  • curl -X GET http://localhost:8282/resources/clusters/9cdba64fae7cbc7556260eaecfad8

クラスタを削除する

登録したクラスタを削除してみましょう
DELETE /resources/cluster/{clusterId} を使います
先ほどのクラスタの詳細を取得するリクエストのメソッドを DELETE に変更するだけです

  • curl -X DELETE http://localhost:8282/resources/clusters/9cdba64fae7cbc7556260eaecfad8

成功時のレスポンスボディはないのでレスポンスステータスで削除できたかどうか確認しましょう

最後に

VMware Admiral の REST API を curl から操作してみました
ドキュメントが整備されていないので UI を元に自分でリクエストを解析する必要がありますが、それほど難しくはないと思います

今回はプロジェクトとクラスタの操作しか紹介しませんでしたが他にもユーザ操作やレジストリ操作、クラスタへのホスト追加などいろいろな操作があるので必要に応じてブラウザとにらめっこしながらやれば同じようにリクエストを生成できると思います

時刻:
ラベル: ,

1 件のコメント:

  1. hawksnowlog2018年1月11日 20:15

    プロジェクトの削除ができないバグですがユーザ認証を有効にしてユーザでログインした状態で削除すると問題なく削除できるようです
    おそらく挙動的にバグなので今後修正される可能性はあると思います

    返信削除

登録: コメントの投稿 (Atom)