NSX-T の Go 言語 SDK について調査しました(2020/12版)

vExperts Advent Calender 2020 に参加しています。 17日目の記事です。
(明日は富士通クラウドテクノロジーズ Advent Calendar 2020で NSX-v に関する記事を投稿するのでよろしくお願いします)

はじめに
SDK を選ぶ時のポイントにしたこと
調査対象
公開されている SDK の開発状況について
比較結果
- 比較表
- 結果まとめ
おまけ: vsphere-automation-sdk-go の使い方
さいごに

はじめに

こんにちは。富士通クラウドテクノロジーズ株式会社の樋口です。普段は NSX を中心にニフクラのインフラ運用管理をしています。 NSX-T の操作をするアプリケーションの開発を始めた都合で、チームで Go 言語の SDK について調査する機会がありました。検討の際にしらべたことを記事にいたします。

f:id:higc_fjct:20201217212138j:plain — 最近vExpert2020刺繍つきニフクラパーカーを社内で作ってもらいました

SDK を選ぶ時のポイントにしたこと

どの種類の NSX-T API が使えるか

NSX-T の API にはいくつか種類があります。

まず、ローカルマネージャー用の API とグローバルマネージャー用 API に分かれます。 NSX-T は3.0.0 よりフェデレーションという機能が追加され、複数の NSX を連携させることが可能になりました。

ローカルマネージャは一つのサイトを管理する NSX Manager, グローバルマネージャーは複数のローカルマネージャーと連携する NSX Manager のようなシステムです。

できることも違うので、ドキュメントもローカルマネージャー用の NSX-T Data Center API Guide とグローバルマネージャー用の NSX-T Data Center Global Policy API Guide に分かれています。

この記事では、グローバルマネージャー用の API については扱わず、ローカルマネージャー用の API のみを取り扱います。また、 NSX-T 3.1.0 を前提にいたします。

NSX-T Data Center API Guideの API Method を見るとカテゴリ分けがされています。カテゴリについての説明を見つけることはできませんでしたが、カテゴリ名とカテゴリ内の API から以下のように分けられていることがわかります。

Cloud Service Manager
NSX Cloud(NSX-T からパブリッククラウドのネットワークを管理する機能) 関連の API
Federation
フェデレーション機能関連の API。
Management Plane API
　　マネージャーモードでの設定をする API。
NSX-T がリリースされたときから存在する。
可能な限り、ほぼ同等の設定をすることができる後述のポリシーモードを利用することが推奨されている。
UI でいうと右上のポリシーを選択した時のように詳細設定ができる
Policy
ポリシーモードでの設定をする API。
NSX2.4 以降から利用できるようになった。
宣言的な API になっている。
マネージャーモードでできる設定が一部出来ないことがある。
ポリシーモードとマネージャーモードの詳細な違いについては、NSX-T Data Center インストールガイドに詳細な説明がある。
UI でいうと右上のポリシーを選択した時と同じ機能が使える
Search
クエリ文字列で検索できる API。
たとえば display_name:*block* AND resource_type:FirewallRule とリクエストすると表示名に block を含んだファイアウォールルールが返却される。

UI でいうと右上のルーペをクリックしたときの検索と同等の機能が利用できる
System Administration
システム管理用の API。
NSX 自体の管理者向け。ネットワーク機能のみを操作したい場合は使わない。
具体的には、コンピュートマネージャの追加や Edge クラスタの管理、システムの正常性の監視などにはこちらを使う。
UI でいうと NSX-T > ホーム以下の画面や、 NSX-T > システム以下の画面で確認できる箇所の操作ができる。
NSX-T > システム以下の NSX Manager 自身の管理画面

NSX-T > ホーム以下のモニタリングページ

SDK を選ぶ際は、これらのうちどの API を利用したか考えて、それが利用できる SDK を選ぶ必要があります。

Cloud Service Manager と Federation については調査しなかったのでこの記事では触れません。

ポリシー API の時にリソースの削除はどうすればいいのか、ポリシー API とマネージメントプレーン API での用語の対応づけがどうなのかという情報は以下のサイトに詳しく記載されていました。

VMware のブログ
https://blogs.vmware.com/networkvirtualization/2020/06/navigating-nsxt-policy-apis.html/
NSX Policy API Getting Started Guide
https://communities.vmware.com/t5/VMware-NSX-Documents/NSX-Policy-API-Getting-Started-Guide-v1-0-pdf/ta-p/2775137

NSX は以下の URL にアクセスすると OpenAPI で定義された API 定義を取得することができます。

Management Plane, System Adminstration に関連した API 定義
- JSON 版
  https://<nsx-mgr>/api/v1/spec/openapi/nsx_api.json
- YAML 版
  https://<nsx-mgr>/api/v1/spec/openapi/nsx_api.yml
Policy, Search に関連した API 定義
- JSON 版
  https://<nsx-mgr>/api/v1/spec/openapi/nsx_policy_api.json
- YAML 版
  https://<nsx-mgr>/api/v1/spec/openapi/nsx_policy_api.yml

この定義を Postman や、後述の Swagger にインポートして利用すると便利です。

継続して更新されそうか

SDK ですが、使い続けることを考えると、継続して更新されるかが重要になってきます。
更新されるかの直接的な記載がありませんでしたが、主要な OSS で利用されているかや、生成方法から予想します。

サポート

2020/12 現在、 Go 言語では SDK サポートが受けられる SDK はなさそうでした。サポートを受ける場合 SDK ではなく、実際にどういったリクエストをしてどういった操作をしているかを明確にしてサポートを受ける必要がありそうです。

調査対象

GitHub の VMware のグループ https://github.com/vmware に存在する SDK と、 Open API から生成する方法を調査し検討しました。

vsphere-automation-sdk-go (Beta)
https://github.com/vmware/vsphere-automation-sdk-go
go-vmware-nsxt
https://github.com/vmware/go-vmware-nsxt
OpenAPI から Swagger Codegen からクライアント生成(以下、Swagger と記載)
https://swagger.io/tools/swagger-codegen/

公開されている SDK の開発状況について

継続して更新されそうかを考えるために、公開されている SDK vsphere-automation-sdk-go, go-vmware-nsxt の開発、利用状況について調べました。
以下のような状況でした。

vsphere-automation-sdk-go, go-vmware-nsxt どちらも NSX-T の Terraform プロバイダで利用されている
vsphere-automation-sdk-go は新しい API が多く対応している(おそらく nsx_policy_api.yaml をもとに生成されている)
vsphere-automation-sdk-go は古い API が多く対応している(おそらく nsx_api.yaml をもとに生成されている)
どちらも更新頻度は同程度

比較結果

比較表

項目	vsphere-automation-sdk-go	go-vmware-nsxt	Swagger
Policy API 対応	⭕	🔺	⭕
Management Plane API 対応	❌	⭕	⭕
Search API 対応	⭕	❌	⭕
System Administration API 対応	❌	⭕	⭕
継続して更新されそうか	⭕	❌	-
クライアントの生成が必要ない	⭕	⭕	❌
その他の良い点	vCenter など VMware の他の製品にも対応している		NSX からダウンロードできる OpenAPI で定義されている API 以外にも応用することが可能

結果まとめ

すべての API に対応して、運用性に問題ない SDK は現在のところ存在しませんでした。場合に応じて使い分けるのが今のところ一番よいと思います。

特に理由が無ければ、 Policy API が推奨されているので、まずは vsphere-automation-sdk-go を利用し、それでできないことがある場合のみ go-vmware-nsxt や Swagger 等の独自実装を利用するのがよいと思います。

おまけ: vsphere-automation-sdk-go の使い方

vsphere-automation-sdk-go に関しては、ドキュメントに利用方法があまり書いていなくて難しかったのでサンプルを記載します。

package main

import (
        "net/http"
        "crypto/tls"
        "fmt"
        "github.com/vmware/vsphere-automation-sdk-go/runtime/protocol/client"
        "github.com/vmware/vsphere-automation-sdk-go/runtime/security"
        "github.com/vmware/vsphere-automation-sdk-go/services/nsxt/infra"
)

func main(){
        url := "REPLACE_YOUR_NSX_IP_ADDRESS"
        username := "REPLACE_YOUR_NSX_USER_NAME"
        password := "REPLACE_YOUR_NSX_PASSWORD"

        tr := &http.Transport{
                TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
        }
        c := client.NewRestConnector(url, http.Client{Transport: tr})
        ctx := security.NewUserPasswordSecurityContext(username,password)
        c.SetSecurityContext(ctx)

        ddclient := infra.NewDefaultDomainsClient(c)
        l, _ := ddclient.List(nil, nil, nil, nil, nil, nil)
        r := l.Results[0]
        fmt.Println(*r.Id, *r.DisplayName)
}

実行結果

default default

デフォルトドメインの ID とデフォルトドメインの表示名が取得できている。

さいごに

2020年12月現在の調査結果を記載しました。
NSX-T の基本的な話や、 Go 言語を利用する場合に限定した話でしたがどなたかの参考になるとうれしいです。

明日の vExperts Advent Calendar 2020、18日目は masanara さんがネットワーク関連の話を書かれるそうです。楽しみですね。

(謝辞: この記事を書くにあたり検証内容の提供とレビューを実施してくださった yaaamaaaguuu さん、ありがとうございました。)

FJCT Tech blog

富士通クラウドテクノロジーズ公式エンジニアブログです