vm.gowatana.jp

NEOにほんごVMware（仮）

NSX-T のタグを REST API で VM に割り当てる。

NSX (NSX-T) NSX-T DFW

NSX-T では、分散ファイアウォールのサードパーティ製品連携などで、VM へのタグ割り当て機能が利用されています。

今回は、VM へのタグ割り当てを API で設定してみます。

 

今回の内容です。

 

この環境について

vSphere / NSX-T

今回のラボは、下記のように構築しています。
ただし、NSX-T のバージョンは 3.1.2 です。

 

vSphere には、テスト用の VM「vm01」を用意してあります。

f:id:gowatana:20211119013822p:plain

 

NSX Manager でも、「インベントリ」→「仮想マシン」にて、vm01 の存在が確認できます。この時点では、タグが設定されていないので「0」になっています。

f:id:gowatana:20211119013917p:plain

 

そして NSX-T での vm01 の ID（external_id）は、500137e3-e3db-9939-1449-600aaa134c6a と表示されています。

f:id:gowatana:20211119014038p:plain

 

クライアント環境

API は、Linux クライアントからコールします。curl と jq を利用します。

$ cat /etc/oracle-release
Oracle Linux Server release 7.9
$ rpm -q curl jq
curl-7.29.0-59.0.1.el7_9.1.x86_64
jq-1.5-1.0.1.el7.x86_64

 

タグ設定で使用する API

NSX-T の REST API リファレンスは下記で確認できます。

 

このうち、次の API メソッドを利用します。

  • 3.4.3.10 Tags（/policy/api/v1/infra/tags）
    Policy > Infra > Tags
  • 3.6.1.2.6.2 Virtual Machines（/api/v1/fabric/virtual-machines）
    System Administration > Configuration > Fabric > Inventory > Virtual Machines

 

VM の ID は、/api/v1/fabric/virtual-machines で確認できます。そして、タグの割り当てには 2種類のメソッドが利用できます。

  • POST /api/v1/fabric/virtual-machines?action=add_tags
  • PUT /policy/api/v1/infra/tags/tag-operations/<operation-id>

 

NSX-T REST API でのタグ操作

API での VM External ID 確認

VM へのタグ割り当てでは、対象 VM の ID が必要になります。これは NSX Manager でも確認できますが、API でも取得できます。

今回の API コールでは、ユーザ、パスワード、NSX Manager アドレスを変数に代入して利用します。

$ USER=admin
$ PASS='VMware1!VMware1!'
$ MGR=lab-nsx-21.go-lab.jp

 

今回の環境では vm01 という名前の VM が 1台しかいないので、単純に display_name をもとに情報取得してみます。まだ tags は空欄です。

$ curl -ks -u "$USER:$PASS" -X GET --url https://$MGR/api/v1/fabric/virtual-machines | jq -r '.results[] | select(.display_name=="vm01")'
{
  "host_id": "6c91dd0d-99c6-43e0-b3b9-69a7719bab0d",
  "source": {
    "target_id": "6c91dd0d-99c6-43e0-b3b9-69a7719bab0d",
    "target_display_name": "192.168.10.121",
    "target_type": "HostNode",
    "is_valid": true
  },
  "external_id": "500137e3-e3db-9939-1449-600aaa134c6a",
  "power_state": "VM_RUNNING",
  "local_id_on_host": "3",
  "compute_ids": [
    "moIdOnHost:3",
    "hostLocalId:3",
    "locationId:564dad38-1ce1-2175-4e99-8565a7fafa5a",
    "instanceUuid:500137e3-e3db-9939-1449-600aaa134c6a",
    "externalId:500137e3-e3db-9939-1449-600aaa134c6a",
    "biosUuid:42011e87-5917-0a84-8177-ca22023e3d61"
  ],
  "type": "REGULAR",
  "guest_info": {
    "os_name": "VMware Photon OS (64-bit)",
    "computer_name": "photon-machine"
  },
  "resource_type": "VirtualMachine",
  "display_name": "vm01",
  "tags": [],
  "_last_sync_time": 1637193854452
}

 

このうち、VM の ID は「external_id」から取得できます。

$ curl -ks -u "$USER:$PASS" -X GET --url https://$MGR/api/v1/fabric/virtual-machines | jq -r '.results[] | select(.display_name=="vm01") | .external_id'
500137e3-e3db-9939-1449-600aaa134c6a

 

API でのタグ割り当て： /api/v1/fabric/virtual-machines

それでは、vm01 にタグを設定してみます。

POST /api/v1/fabric/virtual-machines?action=add_tags メソッドのための JSON 形式のファイルを用意しておきます。ここで、VM の external_id も指定します。

 

tag-01.json

{
  "external_id": "500137e3-e3db-9939-1449-600aaa134c6a",
  "tags": [
    {
      "scope": "App",
      "tag": "Web"
    },
    {
      "scope": "Environment",
      "tag": "Dev"
    }
  ]
}

 

タグを追加してみます。

$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X POST -d @tag-01.json --url "https://$MGR/api/v1/fabric/virtual-machines?action=add_tags"

 

あらためて vm01 の情報を取得してみると、tags でタグが割り当てられたことが確認できます。

$ curl -ks -u "$USER:$PASS" -X GET --url https://$MGR/api/v1/fabric/virtual-machines | jq -r '.results[] | select(.display_name=="vm01")'
{
  "host_id": "6c91dd0d-99c6-43e0-b3b9-69a7719bab0d",
  "source": {
    "target_id": "6c91dd0d-99c6-43e0-b3b9-69a7719bab0d",
    "target_display_name": "192.168.10.121",
    "target_type": "HostNode",
    "is_valid": true
  },
  "external_id": "500137e3-e3db-9939-1449-600aaa134c6a",
  "power_state": "VM_RUNNING",
  "local_id_on_host": "3",
  "compute_ids": [
    "moIdOnHost:3",
    "hostLocalId:3",
    "locationId:564dad38-1ce1-2175-4e99-8565a7fafa5a",
    "instanceUuid:500137e3-e3db-9939-1449-600aaa134c6a",
    "externalId:500137e3-e3db-9939-1449-600aaa134c6a",
    "biosUuid:42011e87-5917-0a84-8177-ca22023e3d61"
  ],
  "type": "REGULAR",
  "guest_info": {
    "os_name": "VMware Photon OS (64-bit)",
    "computer_name": "photon-machine"
  },
  "resource_type": "VirtualMachine",
  "display_name": "vm01",
  "tags": [
    {
      "scope": "App",
      "tag": "Web"
    },
    {
      "scope": "Environment",
      "tag": "Dev"
    }
  ],
  "_last_sync_time": 1637193854452
}

 

NSX Manager でも、vm01 のタグが「2」になったことが確認できます。

そして、数字部分をクリックすると、割り当てられたタグを確認できます。

f:id:gowatana:20211119022833p:plain

 

「インベントリ」→「タグ」でも、タグが表示されます。

f:id:gowatana:20211119023246p:plain

 

API でのタグ割り当て解除： /api/v1/fabric/virtual-machines

タグの割り当てを解除する場合は、同じ JSON ファイル（tag-01.json）を指定しつつ、URL のパラメータを「action=remove_tags」にします。

$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X POST -d @tag-01.json --url "https://$MGR/api/v1/fabric/virtual-machines?action=remove_tags"

 

API でのタグ割り当て： /policy/api/v1/infra/tags

つぎは、別のメソッドで vm01 にタグを設定してみます。

PUT /policy/api/v1/infra/tags/tag-operations メソッドのための JSON 形式のファイルを用意しておきます。こちらは、apply_to に複数の VM を指定できます。代わりに、タグは1つずつ指定します。

 

tag-02_App_add.json

{
  "tag": {
    "scope": "App",
    "tag": "Web"
  },
  "apply_to": [
    {
      "resource_type": "VirtualMachine",
      "resource_ids": [
        "500137e3-e3db-9939-1449-600aaa134c6a"
      ]
    }
  ]
}

 

tag-02_Env_add.json

{
  "tag": {
    "scope": "Environment",
    "tag": "Dev"
  },
  "apply_to": [
    {
      "resource_type": "VirtualMachine",
      "resource_ids": [
        "500137e3-e3db-9939-1449-600aaa134c6a"
      ]
    }
  ]
}

 

さきほどのメソッドとは異なり URL で ID 指定が必要なので、今回は uuidgen で生成しています。ただし、これは UUID ではない文字列でも大丈夫です。

$ OPID=$(uuidgen)
$ echo $OPID
f00753fc-fe8a-4945-b2ba-bc1415d0a7b0

 

そして、下記のように API をコールすると、さきほどと同様にタグが割り当てられます。

1つめ

$ OPID=$(uuidgen)
$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X PUT -d @tag-02_App_add.json --url "https://$MGR/policy/api/v1/infra/tags/tag-operations/$OPID"

 

2つめ

$ OPID=$(uuidgen)
$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X PUT -d @tag-02_Env_add.json --url "https://$MGR/policy/api/v1/infra/tags/tag-operations/$OPID"

 

API でのタグ割り当て解除： /policy/api/v1/infra/tags

/policy/api/v1/infra/tags でのタグの解除は、割り当てと同じメソッドを利用します。そして、JSON の内容が apply_to を remove_from に変更します。

 

tag-02_App_remove.json

{
  "tag": {
    "scope": "App",
    "tag": "Web"
  },
  "remove_from": [
    {
      "resource_type": "VirtualMachine",
      "resource_ids": [
        "500137e3-e3db-9939-1449-600aaa134c6a"
      ]
    }
  ]
}

 

tag-02_Env_remove.json

{
  "tag": {
    "scope": "Environment",
    "tag": "Dev"
  },
  "remove_from": [
    {
      "resource_type": "VirtualMachine",
      "resource_ids": [
        "500137e3-e3db-9939-1449-600aaa134c6a"
      ]
    }
  ]
}

 

そして API をコールすると、タグが解除されます。

 

1つめ

$ OPID=$(uuidgen)
$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X PUT -d @tag-02_App_remove.json --url "https://$MGR/policy/api/v1/infra/tags/tag-operations/$OPID"

 

2つめ

$ OPID=$(uuidgen)
$ curl -ks -u "$USER:$PASS" -H "Content-Type: application/json" -X PUT -d @tag-02_Env_remove.json --url "https://$MGR/policy/api/v1/infra/tags/tag-operations/$OPID"

 

API でのタグ確認

VM のタグの割り当ては、さきほどのように VM の情報を取得すると、「tags」から確認できます。

ほかにも、指定したタグが割り当てられている VM を取得することも可能です。たとえば、つぎのように 「scope=App、tag=Web」タグの割り当てられた VM を取得できます。

$ curl -ks -u "$USER:$PASS" -X GET --url "https://$MGR/policy/api/v1/infra/tags/effective-resources?scope=App&tag=Web"
{
  "results" : [ {
    "target_id" : "500137e3-e3db-9939-1449-600aaa134c6a",
    "target_display_name" : "vm01",
    "target_type" : "VirtualMachine"
  } ],
  "result_count" : 1,
  "sort_ascending" : true,
  "cursor" : "1"
}

 

参考情報

「インベントリ」→「タグ」画面では、VM に割り当てられていない「割り当て先 = 0」のタグがしばらく残ります。

f:id:gowatana:20211119034558p:plain

 

これは、クリーンアップを 5日ほど待つ必要があります。

 

以上、NSX-T のタグを API で操作してみる話でした。