FJCT Tech blog

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

富士通クラウドテクノロジーズ

FJCT/Tech blog

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

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

はじめに

こんにちは。富士通クラウドテクノロジーズ株式会社の樋口です。 普段は 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 GuideAPI Method を見るとカテゴリ分けがされています。 カテゴリについての説明を見つけることはできませんでしたが、カテゴリ名とカテゴリ内の API から以下のように分けられていることがわかります。

  1. Cloud Service Manager
    NSX Cloud(NSX-T からパブリッククラウドのネットワークを管理する機能) 関連の API
  2. Federation
    フェデレーション機能関連の API
  3. Management Plane API
      マネージャーモードでの設定をする API
    NSX-T がリリースされたときから存在する。
    可能な限り、ほぼ同等の設定をすることができる後述のポリシーモードを利用することが推奨されている。
    f:id:higc_fjct:20201217213158p:plain
    UI でいうと右上のポリシーを選択した時のように詳細設定ができる
  4. Policy
    ポリシーモードでの設定をする API
    NSX2.4 以降から利用できるようになった。
    宣言的な API になっている。
    マネージャーモードでできる設定が一部出来ないことがある。
    ポリシーモードとマネージャーモードの詳細な違いについては、NSX-T Data Center インストール ガイドに詳細な説明がある。
    f:id:higc_fjct:20201217213330p:plain
    UI でいうと右上のポリシーを選択した時と同じ機能が使える
  5. Search
    クエリ文字列で検索できる API
    たとえば display_name:*block* AND resource_type:FirewallRule とリクエストすると表示名に block を含んだファイアウォールルールが返却される。
    f:id:higc_fjct:20201217212959p:plain
    UI でいうと右上のルーペをクリックしたときの検索と同等の機能が利用できる
  6. System Administration
    システム管理用の API
    NSX 自体の管理者向け。ネットワーク機能のみを操作したい場合は使わない。
    具体的には、コンピュートマネージャの追加や Edge クラスタの管理、システムの正常性の監視などにはこちらを使う。
    UI でいうと NSX-T > ホーム 以下の画面や、 NSX-T > システム 以下の画面で確認できる箇所の操作ができる。
    f:id:higc_fjct:20201217213501p:plain
    NSX-T > システム 以下の NSX Manager 自身の管理画面
    f:id:higc_fjct:20201217213427p:plain
    NSX-T > ホーム 以下のモニタリングページ

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

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

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

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 ではなく、実際にどういったリクエストをしてどういった操作をしているかを明確にしてサポートを受ける必要がありそうです。

調査対象

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

公開されている 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-nsxtSwagger 等の独自実装を利用するのがよいと思います。

おまけ: 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 さん、ありがとうございました。)