Meraki Dashboard API 活用。PostmanとTerraformを試してみた。

はじめに

本記事は、シスコの有志による Cisco Systems Japan Advent Calendar 2024 シリーズ2 の22日目として投稿しています。

Cisco Systems Japan Advent Calendar 過去記事一覧（クリックして展開）

2017年版： https://qiita.com/advent-calendar/2017/cisco
2018年版： https://qiita.com/advent-calendar/2018/cisco
2019年版： https://qiita.com/advent-calendar/2019/cisco
2020年版： https://qiita.com/advent-calendar/2020/cisco
2021年版： https://qiita.com/advent-calendar/2021/cisco
2022年版： https://qiita.com/advent-calendar/2022/cisco
2023年版： https://qiita.com/advent-calendar/2023/cisco
2024年版： https://qiita.com/advent-calendar/2024/cisco

22日目は、Meraki ダッシュボードAPIの利用方法についてまとめたいと思います。
Postmanと、Terraformに利用についてまとめます。

Postman

Postmanは、API（アプリケーションプログラミングインターフェース）の開発、テスト、および管理を支援するためのツールです。Postmanを利用すると簡単にMerakiのAPIを試すことが可能です。

手順

最初に、Postmanをダウンロードしてインストールします。
Postmanは、APIのリクエストを簡単に作成、送信できる強力なツールです。
ダウンロードサイト

Meraki API keyの生成

MerakiのAPI Keyの生成方法はこちらの公式ドキュメントをご参照ください。

Postmanの設定

Postmanアプリを開き、右上の環境変数設定用のメニューから、Base_URLを記載。

作った環境をここで選択しておきます。ホスト名やユーザIDが異なる環境にアクセスしたい時などは、環境を複数作っておいて、ここで切り替えることができます。

Vaultを利用すると機密データを暗号化してローカルに保存します。
環境変数の場合はチーム内で共有される場合があります。
API Keyはここで設定します。API Keyが流出した場合は、その環境の情報流出や不正な操作に繋がります。
ハンズオンのAPIキーに関しては一定期間毎の更新などを検討ください。

Postman Vaultについてはこちらを参照ください。
https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/

Allowed domains(この値が利用できるドメイン)を指定。
https://api.meraki.com

Merakiダッシュボード上のネットワークデバイス一覧を取得するAPIを実行します。
https://developer.cisco.com/meraki/api-v1/get-organization-inventory-devices/

Organization IDが必要になります。以下のAPIを利用し取得可能です。
https://developer.cisco.com/meraki/api-v1/get-organizations/

もしくは、Merakiダッシュボード画面の最下部に記載があります。
(手っ取り早く確認できます。)

Postmanに戻り、環境変数としてOrganization IDを追加しましょう。

PostmanでAPIリクエスト実行

以下のGETリクエストを試してみましょう。

{{base_url}}/organizations/{{org_id}}/inventory/devices

VaultからAPIキーを参照するように指定認証情報を指定し、リクエストを送信します。

[200 OK]で成功していることを確認します。

出力結果を確認

JSON形式でデバイス一覧が表示されます。
今回の環境には、Cloud Monitoring for Catalyst / Catalyst Wirelessで稼働している機器があります。Merakiのダッシュボードから、Catalystスイッチ(例：Catalyst 9300)や無線LANコントローラやアクセスポイント(Catalyst 9800,9100)をモニタリングできる機能です。どのような出力か見てみましょう。
※詳細情報は、マスキングしております。
Cloud Monitoringという値などがあることがわかります。MerakiダッシュボードAPIを利用することで、IOS-XEで動作するCatalystスイッチや無線機器の情報を取得することが一部できます。モニタリングなので基本はGET関連のメソッドのみ。

Catalyst 9800/9100の情報

{
        "mac": "XX:XX:XX:XX:XX:XX",
        "serial": "XXXX-XXXX-XXXX",
        "name": "C9800",
        "model": "C9800-L-C-K9",
        "networkId": "N_XXXXXXXXXXXX",
        "orderNumber": null,
        "claimedAt": "2024-12-XXXXXXXX",
        "tags": [],
        "productType": "wirelessController",
        "countryCode": null,
        "details": [
            {
                "name": "Catalyst serial",
                "value": "XXXXXXXX"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Monitoring version",
                "value": "2"
            }
        ]
    },
 {
        "mac": "XX:XX:XX:XX:XX:XX",
        "serial": "XXXX-XXXX-XXXX",
        "name": "CW9164I",
        "model": "CW9164I-Q",
        "networkId": "L_XXXXXXXXXXXXXX",
        "orderNumber": null,
        "claimedAt": "2024-12-XXXXXXXX",
        "tags": [
            "recently-added"
        ],
        "productType": "wireless",
        "countryCode": "J4 ",
        "details": [
            {
                "name": "Catalyst serial",
                "value": "XXXXXXXX"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Monitoring version",
                "value": "2"
            }
        ]
    },

Catalyst 9200Lの情報

{
        "mac": "XX:XX:XX:XX:XX:XX",
        "serial": "XXXX-XXXX-XXXX",
        "name": "C9200L",
        "model": "C9200L-48T-4X",
        "networkId": "L_XXXXXXXXXXXXXX",
        "orderNumber": null,
        "claimedAt": "2024-10-XXXXXXXXXXXXXX",
        "tags": [
            "recently-added"
        ],
        "productType": "switch",
        "countryCode": null,
        "details": [
            {
                "name": "Catalyst serial",
                "value": "XXXXXXXXXXXX"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Cloud configuration",
                "value": "monitoring"
            },
            {
                "name": "Monitoring version",
                "value": "1"
            }
        ]
    }

Meraki APIドキュメントに行くとWireless Contorollerの項目も少しありました。

今後のAPIの種類が増えていくことを期待します！

Terraform

Terraformは以下の公式サイトをご確認ください。
https://developer.hashicorp.com/terraform/install

Terraformは、インフラストラクチャをコードで管理するためのIaCツールです。

余談ですが、Teraformを少し試そうと思ったきっかけが以下の記事です。
Starbucksでは、Terraformを広く使用しているおり、4万台のデバイスと25万超のエンドポイントにわたって1万超のネットワークで構成されており、ネットワークインフラでCisco Merakiを利用しています。
Starbucksが Meraki向け Terraform プロバイダーをオープンソース化しています。
Terraformプロバイダは、Terraformがさまざまなクラウドサービスやインフラストラクチャプラットフォームとやり取りするためのプラグインです。プロバイダは、Terraformを使用して管理したい特定のリソースやサービスに対するAPI呼び出しを抽象化し、リソースの作成、管理、削除を行うための手段を提供します。
つまり公開されているプロバイダーを利用すると、簡単にMerakiネットワークの構成変更、展開を実施することが可能となります。

手順

Terraformインストール

Terraform は公式 Web サイトからダウンロードしてインストールできます。
Terraformの基礎的な利用方法は割愛しております。

Merakiの公式APIページです。
Terraform をインストール手順も記載されています。

主なterraformのコマンド
terraform init: ワークスペースを初期化し、必要なプロバイダをダウンロードします。
terraform plan: 設定ファイルに基づき、どのような変更が行われるかを確認します。
terraform apply: 実際にインフラストラクチャを構築、変更します。
terraform destroy: 構築したリソースを削除します。

プロバイダのインストール

.tfファイルを作成し、Meraki Terraform プロバイダのインストール

main.tf

terraform {
  required_providers {
    meraki = {
      source = "cisco-open/meraki"
      version = "0.1.0-alpha"
    }
  }
}

provider "meraki" {
  # Configuration options
}

プロバイダーをインストールするコマンドを実行します。

terraform init

Meraki の Terraform プロバイダーは、API Keyに環境変数を使用できます。
注意: 機密情報 (資格情報や API キーなど) を暗号化されていないファイルに保存しないでください。

次のコマンドは、前の手順で作成されたファイルのデータを使用して Terraform 環境変数を設定します。

export MERAKI_DASHBOARD_API_KEY=<your API key>

Meraki Terraform プロバイダーには 多くのリソース/データ ソースが用意されているため、タスクに適したリソースを見つける方法を理解することが重要です。リソースの名前はパスに基づいて付けられ、パスはダッシュボード APIドキュメントサイトで確認できます。

ネットワーク スイッチ設定の操作のURL は次のようになります

/networks/{networkId}/switch/settings

そのリソースは以下のように設定されています。

meraki_networks_switch_settings

Planを実行

また、Meraki のダッシュボードAPIを使用すると、さまざまな情報を照会できます。
以下のPlanを実行すると組織のインベントリ内のすべてのデバイスを取得することが出来ます。

plan.tf

terraform {
  required_providers {
    meraki = {
      source = "cisco-open/meraki"
      version = "0.1.0-alpha"
    }
  }
}

provider "meraki" {
  # Configuration options
}

data "meraki_devices" "example" {

  organization_id = "XXXXXXXX" # 対象のorganization IDを指定
}

output "meraki_devices_example" {
  value = data.meraki_devices.example.items
}

以下の出力例。JSONに似た形式で出力される。

      + {
          + address      = ""
          + firmware     = "ios-xe-17-12-3"
          + lan_ip       = "XX.XX.XX.XX"
          + lat          = XX.XXXXXXXXXXX
          + lng          = -XXX.XXXXXXXXXX
          + mac          = "XX:XX:XX:XX:XX:XX"
          + model        = "C9200L-48T-4X"
          + name         = "C9200L-A02-1"
          + network_id   = "L_XXXXXXXXXXXXXXXXXXXX"
          + notes        = ""
          + product_type = "switch"
          + serial       = "XXXX-XXXX-XXXX"
          + tags         = [
              + "recently-added",
            ]
        },

新しいネットワークの作成

例えば、新しいネットワークを作成するために、以下のリソースを定義します。

resource "meraki_network" "example_network" {
  name     = "Example Network"
  type     = "wireless"
  timezone = "Japan/Tokyo"
}

以下を実行するとMerakiダッシュボードに新しいネットワークが作成されます。

terraform init
terraform apply

おわり

最後まで本記事を読んでくださりありがとうございました。
PostmanとTerraformは、それぞれ異なるアプローチでMeraki APIと連携する強力なツールです。PostmanはAPIのテストやデバッグに便利で、Terraformはインフラストラクチャの自動化に最適です。どちらのツールも、ネットワーク管理の効率化で利用できますので試してみてはいかがでしょうか。

[この記事はCisco Advent Calendar 2024の一部として投稿されました。]

免責事項

本サイトおよび対応するコメントにおいて表明される意見は、投稿者本人の個人的意見であり、シスコの意見ではありません。本サイトの内容は、情報の提供のみを目的として掲載されており、シスコや他の関係者による推奨や表明を目的としたものではありません。各利用者は、本Webサイトへの掲載により、投稿、リンクその他の方法でアップロードした全ての情報の内容に対して全責任を負い、本Web サイトの利用に関するあらゆる責任からシスコを免責することに同意したものとします。