Azure CLI を使用した大規模な IoT Edge モジュールのデプロイと監視

2025-05-20

適用対象: IoT Edge 1.5

重要

IoT Edge 1.5 LTS は、サポートされているリリースです。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日をもってサポートが終了しています。以前のリリースの場合は、「IoT Edge を更新する」を参照してください。

Azure CLI を使用して、 Azure IoT Edge の自動デプロイを作成し、多数のデバイスのデプロイを一度に管理します。 IoT Edge の自動展開は、Azure IoT Hub のデバイス管理機能の一部です。デプロイを使用すると、複数のモジュールを複数のデバイスにデプロイし、モジュールの状態と正常性を追跡し、必要に応じ変更を加えます。

この記事では、Azure CLI と IoT 拡張機能をセットアップします。次に、モジュールを一連の IoT Edge デバイスにデプロイし、CLI コマンドを使用して進行状況を監視します。

前提条件

Azure サブスクリプション内の IoT ハブ。
1 つまたは複数の IoT Edge デバイス。

IoT Edge デバイスがセットアップされていない場合は、Azure 仮想マシンで作成できます。仮想 Linux デバイスの作成または仮想 Windows デバイスの作成に関するクイックスタート記事のいずれかの手順に従います。
環境内の Azure CLI。 Azure CLI のバージョンが 2.0.70 以降である必要があります。 az --versionを使用して確認します。このバージョンでは、az 拡張機能のコマンドがサポートされ、Knack コマンドフレームワークが導入されています。
Azure CLI 向け IoT 拡張機能。

配置マニフェストを構成する

配置マニフェストは、デプロイするモジュール、モジュール間のデータフロー方法、およびモジュールツインの必要なプロパティについて説明する JSON ドキュメントです。詳細については、モジュールのデプロイと IoT Edge へのルートの確立の方法の学習に関する記事をご覧ください。

Azure CLI を使用してモジュールをデプロイするには、配置マニフェストを .txt ファイルとしてローカル環境に保存します。次のセクションのファイルパスは、コマンドを実行してデバイスに構成を適用するときに使用します。

1 つのモジュールを例にした基本的な配置マニフェストを次に示します。

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

注

このサンプルのデプロイマニフェストでは、IoT Edge エージェントとハブにスキーマバージョン 1.1 を使用します。スキーマバージョン 1.1 は、IoT Edge バージョン 1.0.10 と共にリリースされます。これにより、モジュールの起動順序やルートの優先順位付けなどの機能を使用できます。

多層デプロイ

階層型デプロイは、互いに積み重ねることができる自動デプロイの一種です。多層デプロイの詳細については、「1 台のデバイスまたは多数のデバイスを対象とした IoT Edge 自動展開について」を参照してください。

自動デプロイと同様に、Azure CLI を使用して階層化されたデプロイを作成および管理できます。いくつかの違いがあります。階層化デプロイを作成した後、Azure CLI は、すべてのデプロイの場合と同じように、階層化されたデプロイに対して機能します。多層デプロイを作成するには、create コマンドに --layered フラグを追加します。

2 つ目の違いは、配置マニフェストの作成方法です。標準の自動デプロイには、システムランタイムモジュールと任意のユーザーモジュールを含める必要があります。階層化デプロイには、ユーザーモジュールのみを含めることができます。多層デプロイには、システムランタイムモジュールなど、すべての IoT Edge デバイスに必要なコンポーネントを提供するために、標準の自動展開もデバイス上に必要です。

例として、1 つのモジュールを含む基本的な階層化配置マニフェストを次に示します。

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

注

この多層配置マニフェストの形式は、標準的な配置マニフェストとは若干異なります。ランタイムモジュールの必要なプロパティは階層化されており、ドット表記を使用します。 Azure portal が多層デプロイを認識するためには、この書式が必要となります。次に例を示します。

properties.desired.modules.<module_name>
properties.desired.routes.<route_name>

前の例は、モジュールの properties.desired 階層展開設定を示しています。この階層展開が、同じモジュールが既に適用されているデバイスを対象とする場合は、既存の必要なプロパティが上書きされます。必要なプロパティを上書きするのではなく更新するには、新しいサブセクションを定義します。次に例を示します。

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

次の構文を使用して、同じ内容を表現することもできます。

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

注

現時点では、すべての階層化されたデプロイには、有効な edgeAgent オブジェクトが含まれている必要があります。多層デプロイで更新されるのがモジュールのプロパティだけだとしても、空のオブジェクトを追加してください。 (例: "$edgeAgent":{})。空のedgeAgent オブジェクトを含む階層展開は、モジュールツインの対象として表示edgeAgent、適用されません。

階層展開を作成するには:

Azure CLI の create コマンドに --layered フラグを追加します。
システムモジュールは含めないでください。
$edgeAgent と $edgeHub では、完全なドット表記を使用します。

多層デプロイでのモジュールツインの構成の詳細については、多層デプロイに関するページを参照してください。

タグを使用してデバイスを識別する

展開を作成する前に、影響を与えるデバイスを指定する必要があります。 Azure IoT Edge では、デバイスツイン内の "タグ" を使用してデバイスを識別します。

各デバイスには、対象のソリューションにとって意味のある方法で定義した複数のタグを設定することができます。たとえば、スマートビルのキャンパスを管理する場合は、次のタグをデバイスに追加できます。

"tags":{
  "___location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

デバイスツインとタグの詳細については、「IoT Hub のデバイスツインの理解と使用」を参照してください。

デプロイの作成

配置マニフェストとその他のパラメーターを含む配置を作成して、ターゲットデバイスにモジュールをデプロイします。

az iot edge deployment create コマンドを実行してデプロイを作成します。

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

--layered フラグを追加して、階層化デプロイを作成します。

az iot edge deployment create コマンドでは、次のパラメーターを使用します。

--layered: デプロイを階層化されたデプロイとして識別する省略可能なフラグ。
--deployment-id: IoT ハブで作成されたデプロイの名前。最大 128 文字の小文字で一意の名前を使用します。スペースと無効な文字を使用しないでください: & ^ [ ] { } \ | " < > /。このパラメーターは必須です。
--content: 配置マニフェスト JSON へのファイルパス。このパラメーターは必須です。
--hub-name: デプロイが作成される IoT ハブの名前。ハブは現在のサブスクリプションにある必要があります。 az account set -s <subscription-name>を実行して、現在のサブスクリプションを変更します。
--labels: デプロイの追跡に役立つ名前と値のペア。ラベルでは、名前と値に JSON 形式が使用されます。 (例: {"HostPlatform":"Linux", "Version":"3.0.1"})。
--target-condition: この展開の対象となるデバイスを決定する条件。条件は、デバイスツインタグか、デバイスツインから報告されるプロパティに基づいて指定し、式の形式に一致させる必要があります。 (例: tags.environment='test' and properties.reported.devicemodel='4000x')。ターゲット条件を指定しない場合、展開はどのデバイスにも適用されません。
--priority: 正の整数。 2 つ以上のデプロイが同じデバイスを対象とする場合は、優先度が最も高いデプロイが適用されます。
--metrics: 報告されたプロパティ edgeHub クエリを実行してデプロイの状態を追跡するメトリック。メトリックでは、JSON 入力またはファイルパスが使用されます。 (例: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}')。

Azure CLI を使用してデプロイを監視するには、「 IoT Edge デプロイの監視」を参照してください。

注

新しい IoT Edge デプロイを作成すると、IoT Hub が新しい構成を処理し、新しい必要なプロパティをターゲットデバイスに送信するまでに最大 5 分かかることがあります。

デプロイの変更

デプロイを変更すると、その変更はすべての対象デバイスに直ちにレプリケートされます。

ターゲット条件を更新すると、次の変更が発生します。

デバイスが古いターゲット条件を満たしていないが、新しいターゲット条件を満たしていて、この展開がそのデバイスの最も高い優先順位である場合、この展開はデバイスに適用されます。
現在この展開を実行しているデバイスがターゲット条件を満たさなくなった場合、この展開はアンインストールされ、 次に優先度の高い 展開が実行されます。
現在この展開を実行しているデバイスがターゲット条件を満たさなくなり、他の展開のターゲット条件を満たしていない場合、デバイスで変更は行われません。デバイスは現在のモジュールを現在の状態で実行し続けますが、このデプロイの一部として管理されなくなります。デバイスは、別の展開のターゲット条件を満たした後、この展開をアンインストールし、新しい展開を引き受けます。

配置マニフェストで定義されたモジュールとルートを含むデプロイの内容は更新できません。展開の内容を更新するには、優先順位の高い同じデバイスを対象とする新しい展開を作成します。ターゲット条件、ラベル、メトリック、優先順位など、既存のモジュールの特定のプロパティを変更できます。

デプロイを更新するには、az iot edge deployment update コマンドを使用します。

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

deployment update コマンドでは、次のパラメーターを使用します。

--deployment-id: IoT ハブ内のデプロイの名前。
--hub-name: デプロイが存在する IoT ハブの名前。ハブは現在のサブスクリプションにある必要があります。別のサブスクリプションに切り替えるには、 az account set -s <subscription-name>を実行します。
--set: 展開のプロパティを変更します。次のプロパティを変更できます。
- targetCondition (例: targetCondition=tags.___location.state='Oregon')
- labels
- priority
--add: ターゲット条件やラベルを含む新しいプロパティを展開に追加します。
--remove: ターゲット条件やラベルを含む既存のプロパティを削除します。

デプロイの削除

展開を削除すると、デバイスは次に優先順位の高い展開を使用します。デバイスが別のデプロイのターゲット条件を満たしていない場合、デプロイを削除してもモジュールは削除されません。

az iot edge deployment delete コマンドを実行してデプロイを削除します。

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

deployment delete コマンドでは、次のパラメーターを使用します。

--deployment-id。IoT ハブに存在するデプロイの名前。
--hub-name。デプロイが存在する IoT ハブの名前。ハブは現在のサブスクリプションにある必要があります。 az account set -s [subscription name] コマンドを使用して目的のサブスクリプションに切り替えます。

次のステップ

IoT Edge デバイスへのモジュールのデプロイの詳細について学習します。