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

[アーティクル]
04/11/2024

適用対象: IoT Edge 1.5 IoT Edge 1.4

重要

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

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

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

前提条件

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
        }
      }
    }
  }
}

Note

このサンプルのデプロイマニフェストでは、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
        }
      }
    }
  }
}

Note

この多層配置マニフェストの形式は、標準的な配置マニフェストとは若干異なります。ランタイムモジュールの必要なプロパティは階層化されており、ドット表記を使用します。 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
}

Note

現在、どの多層デプロイも、有効と見なされるためには、edgeAgent オブジェクトが含まれている必要があります。多層デプロイで更新されるのがモジュールのプロパティだけだとしても、空のオブジェクトを追加してください。 (例: "$edgeAgent":{})。空の edgeAgent オブジェクトが含まれる多層デプロイは、edgeAgent モジュールツインでは、applied ではなく targeted と表示されます。

まとめると、多層デプロイを作成するには、次のようにします。

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 [int]

同じコマンドと --layered フラグを使用して、多層デプロイを作成します。

デプロイ用の 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。正の整数。複数のデプロイが同じデバイスをターゲットしている場合には、優先度の数値が最も大きいデプロイが適用されます。
--metrics。 edgeHub によって報告されたプロパティのクエリを実行し、デプロイの状態を追跡するメトリック。メトリックは JSON 入力またはファイルパスを受け取ります。 (例: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}')。

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

Note

新しい 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 デバイスへのモジュールのデプロイの詳細について学習します。

次の方法で共有

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

前提条件

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

多層デプロイ

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

デプロイの作成

デプロイの変更

デプロイの削除

次のステップ

フィードバック

その他のリソース