 本記事は TechHarmony Advent Calendar 2024 12/12付の記事です。 |
2024年11月18日のCatoクラウドのアップデート情報 にて、Catoクラウドの管理操作や設定作業に利用できるツールのソースコードを GitHub 上で公開したと唐突にアナウンスされました。
今回のブログ記事では、実際にどのようなものが公開され、どのような時に活用できるものなのか紹介したいと思います。
GitHub 上で公開されているもの
各種ソースコードは、GitHub 上の Cato Networks 社の Organization 配下で公開されています。
2024年12月12日時点では、実際に使えそうなものとして次のものが含まれています。
- API をコマンドライン操作で実行できる CLI ツール
- API を Go 言語のプログラムから操作するための SDK
- Cato クラウドの各種設定作業を行うための Terraform 用のプロバイダ
- Cato クラウドと AWS や Azure との間で vSocket 接続や IPsec 接続を行うための Terraform 用のモジュール
- API を Python から操作するためのサンプルコードや Jupyter Notebook
これらは全てオープンソースライセンス (Apache License Version 2.0) で配布されていますので、ツール類を自由に利用できるのはもちろんですし、ソースコードを自由に改造して利用することもできます。ただし、提供されているツール類は Cato クラウドの商用サポートがあるわけではなく、使い物になるレベルのものになっているかどうかは保証されていないため、利用の際にはその点を認識しておく必要があります。
以降では、これら提供されているものがどのようなものか、少し詳しく解説していきます。
CLI ツール
CLI ツール概要
CLI ツールのソースコードは GitHub の catonetworks/cato-cli リポジトリで公開されています。
CLI は Python 言語で開発されており、README に記載の通り pip を用いて catocli パッケージをインストールして利用できます。利用するには Python 3.6 以上の実行環境が別途必要となります。
これまで API を実行するには多少なりともプログラムを書かざるを得ませんでしたので、CLI ツールはずっと待ち望んでいたものでした。なので、あとは CLI を上手く使えばいろいろと捗ります！と言いたいところですが、2024年12月12日時点ではドキュメントもヘルプもあまり整備されていないため、簡単に使えるものではないというのが実情です…。しょうがないのでソースコードを読み、おおよその使い方がわかってきましたのでその内容を共有します。
まず、CLI を利用する前提として、Cato クラウドの API について理解している必要があります。それには弊社の過去記事を参考にしつつ公式の API Reference を参照ください。
“catocli -h” コマンドを実行してヘルプを見てみると、次の4つのパラメータがあります。
- query
- mutation
- entity
- raw
query と mutation は、それぞれ Queries と Mutations の分類の API を実行する際に指定するパラメータであり、API 名と引数を続けて指定してすれば API を実行できます。entity は query の中の entityLookup API を少しだけ実行しやすくしたものですが、使っても使わなくても良い特殊な存在のように思えます。raw は GraphQL のクエリそのものや引数を指定して API を実行するもので、これを通常使う必要はないですが、新しい API が用意されたけど CLI はまだサポートしていない場合などに使うものかもしれません。
entityLookup API の実行例
では、手始めに Query の entityLookup API を実行してみましょう。
まずは “catocli query entityLookup -h” コマンドを実行してヘルプを確認するわけですが、これを見ても引数の指定方法はさっぱりわかりませんね…。
$ catocli query entityLookup -h
usage:
EXAMPLES:
catocli query entityLookup -h
catocli query entityLookup
catocli query entityLookup "$(cat < entityLookup.json)"
catocli query entityLookup '{"entityIDs": ["ID"], "entityInput": {"id": {"id": "ID"}, "name": {"name": "String"}, "type": {"type": "enum(EntityType)"}}, "from": "Int", "helperFields": ["String"], "limit": "Int", "lookupFilterInput": {"filter": {"filter": "enum(LookupFilterType)"}, "value": {"value": "String"}}, "search": "String", "sortInput": {"field": {"field": "String"}, "order": {"order": "enum(DirectionInput)"}}, "type": "enum(EntityType)"}'
positional arguments:
json Variables in JSON format.
optional arguments:
-h, --help show this help message and exit
-accountID ACCOUNTID Override the CATO_ACCOUNT_ID environment variable with this value.
-t [T] Print test request preview without sending api call
-v [V] Verbose output
-p [P] Pretty print
結論として、CLI にどのような引数を指定すれば利用できるのかを知るには、現状では CLI のソースコードの一部を見て把握せざるを得ませんでした。
Query の entityLookup API の場合、見るべきものは次の2つのファイルです。
- https://github.com/catonetworks/cato-cli/blob/main/catocli/parsers/query_entityLookup/README.md
- https://github.com/catonetworks/cato-cli/blob/main/queryPayloads/query.entityLookup.json
1つ目のファイルは改行がうまく表示されないため見づらいですが、entityLookup API を実行するコマンドには10個の引数が用意されており、その中でも accountID と type の2つが必須の引数であることがわかります。
また、2つ目のファイルを見ると、実際に実行される GraphQL のクエリや引数の型や構造がわかります。このファイルには “enum(EntityType)” や “enum(LookupFilterType)” といった列挙型のような記載もありますが、それらの具体的な値は API Reference のほうに記載されています。
これら情報を踏まえて、accountID 引数のみコマンドラインで用意されたパラメータで指定し、それ以外の引数を JSON 形式の文字列として指定すれば、CLI で API を実行できました。
例えば、自アカウントに登録済の Site の一覧を取得したい場合、次のように CLI を実行すれば JSON 形式で結果を取得できます。
$ export CATO_TOKEN=APIキー
$ catocli query entityLookup -accountID=アカウントID '{"type":"site"}'
{
"data": {
"entityLookup": {
"items": [
{
"description": "BRANCH ",
"entityEntity": {
"entityTypeType": "site",
"id": "XXXXX",
"name": "XXXXX"
},
"helperFields": {
"connectionType": "Socket X1500",
"creationDate": "Aug 24, 2023 8:02:44 AM",
"description": "",
"isHA": "false",
"lastModified": "Oct 25 2024 1:04:32 AM",
"operationalStatus": "active",
"protoID": "XXXXX",
"type": "BRANCH"
}
},
省略
],
"total": 9
}
}
}
ここまで実行できれば、後は jq コマンドなどを使ってデータ抽出や加工もできますね。
events API の実行例
もう少し複雑な例として、Query の events API も CLI で実行してみます。今回は「2024年11月の Internet Firewall のルールごとのイベント数を降順で取得する」といったことを試してみます。
まず、events API の引数は次の2つを見るとわかります。
- https://github.com/catonetworks/cato-cli/blob/main/catocli/parsers/query_events/README.md
- https://github.com/catonetworks/cato-cli/blob/main/queryPayloads/query.events.json
これらの内容をもとに、次のような引数を与えると実現できます。引数の内容については 過去のブログ記事 もご参照ください。
{
"timeFrame": "utc.{2024-11-01/00:00:00--2024-12-01/00:00:00}",
"eventsMeasure": [
{ "fieldName": "event_count", "aggType": "sum" }
],
"eventsDimension": [
{ "fieldName": "rule" }
],
"eventsFilter": [
{ "fieldName": "event_sub_type", "operator": "is", "values": [ "Internet Firewall" ] }
],
"eventsSort": [
{ "fieldName": "event_count", "order": "desc" }
]
}
entityLookup API の実行例と同様に上記の引数をコマンドラインで直接指定しても良いですが、長いのでいったんファイルに記載しておき、ファイルから引数を渡して次のように CLI を実行すると少しスマートです。
$ vim events-request.json
引数の JSON を記載する
$ catocli query events -accountID=アカウントID "$(cat < events-request.json)"
{
"data": {
"events": {
"from": "2024-11-01T00:00:00Z",
"id": "XXXX",
"records": [
{
"flatFields": [
[
"event_count",
"17987"
],
[
"rule",
"Any Allow"
]
],
"prevTimeFrame": null,
"trends": null
},
省略
],
"to": "2024-12-01T00:00:00Z",
"total": 7,
"totals": {
"event_count": 21090,
"rule": null
}
}
}
}
なかなか良い感じです。
同じようなやり方で他の API も CLI ツールで実行できますが、Cato クラウドの API や GraphQL の構文などについて十分理解していないと使いこなせないため、CLI ツールがあるからといって簡単に API を実行できるわけではないというのが辛いところですね…。
Go Client SDK
Cato クラウドの API を Go 言語のプログラムから操作するための SDK は、GitHub の catonetworks/cato-go-sdk リポジトリで公開されています。
Go 言語のプログラムを書く人であれば上記リポジトリの examples ディレクトリにあるサンプルコードを見れば一目瞭然だと思いますが、cato-go-sdk を import し、CatoClient インターフェースのインスタンスを New すれば、あとは Visual Studio Code などで入力補完を利かしながらプログラムを書けます。SDK があるのと無いのとではプログラムの書きやすさが段違いです！
Cato クラウドの API について理解していないと使いこなせないというのは変わりませんが、GraphQL の部分の多くが隠蔽されているので、GraphQL をそこまで理解していなくてもプログラムが書けそうです。
他の言語（特に Python）向けの公式の SDK の提供を期待しています。
Terraform
Cato クラウドを扱うための Terraform 用のプロバイダやモジュールのソースコードは、名前に terraform を含む複数のリポジトリ で公開されています。
2024年12月12日時点では次のものが用意されています。
- Cato クラウドの各種設定項目を Terraform のリソースとして扱うためのプロバイダ
- Cato クラウドと AWS や Azure との間で vSocket で接続するためのモジュール
- Cato クラウドと AWS や Azure との間で IPsec で接続するためのモジュール
これらは Terraform Registry の catonetworks 名前空間 で配布されていますので、GitHub からソースコードを入手する必要はなく、自分の Terraform コード内から参照して利用できます。
Cato クラウド用 Terraform プロバイダ
Cato クラウド用の Terraform プロバイダには現時点では次のリソース（合計9種類）が含まれています。
- Socket / vSocket サイトや IPsec サイトを操作するリソース
- サイトのネットワークやホストを操作するリソース
- Socket / vSocket サイトの WAN インターフェースを操作するリソース
- Internet Firewall のルールやセクションを操作するリソース
- WAN Firewall のルールやセクションを操作するリソース
プロバイダやリソースの利用方法を記載した ドキュメント も用意されていますので、そちらも合わせてご参照ください。
Terraform で操作可能な範囲はまだ限られていますが、比較的頻繁に設定を追加・変更するものが Terraform で操作できるようになっている印象を受けます。特に、多数のサイトを追加して管理する必要がある場合には Terraform を使ってみるのは良さそうです。
Cato クラウドの API ですと他のリソースも扱えますので、Terraform で扱えるリソースも今後拡充されていくものと思います。
Cato クラウド用の Terraform モジュール
用意されている Terraform モジュールは、単に Cato クラウド側の設定を行うだけでなく、AWS や Azure 側にも必要なリソースを構築してくれるものとなっています。
AWS と Azure のどちらを利用するか、vSocket と IPsec サービスのどちらを利用するか、vSocket を利用する場合に VPC / VNet を作成するか既存のものを利用するか、といった違いにより6種類のモジュールが用意されていますので、どのように構築したいかに応じて使い分けることになります。
特に、vSocket を利用する場合はパブリッククラウド側で作成・設定すべきリソースの量が多く手動で構築するのは大変ですので、用意された Terraform モジュールを利用すると良さそうに思います。逆に IPsec サービスを利用する場合は、Terraform モジュールではなくプロバイダを使ってリソースを作成するというのでも十分かもしれません。
なお、モジュールのドキュメントはほぼ用意されていませんが、利用例のコード が用意されていますので、そちらを見るとどのようにコードを書けばよいか概ねわかるかと思います。ただ、どのような変数を与えるべきかについては少し悩む部分があり、Cato クラウド側の設定値に関する変数はともかく、パブリッククラウド側の変数を決めるには当然パブリッククラウド側の構築に関する知識も必要ですので、一筋縄ではいかないかもしれません。
まとめ
Cato クラウドが GitHub 上でオープンソースライセンスで公開したものについてざっくりと説明しました。簡単に利用できるものではありませんが、ソフトウェア開発者であれば十分乗り越えられるでしょう。
最近は Cato クラウドの API が拡充されつつあり、CLI やプログラムからも操作しやすくなってきたことで、ようやく開発者にとっても Cato クラウドがクラウドサービスになってきたと実感しています。また、オープンソースとして公開されていると安心感がありますし、開発者の性としてそのエコシステムに対して何らかの形で貢献しようという意欲も沸いてきました。