使用 Azure CLI 大规模部署并监视 IoT Edge 模块

项目
05/20/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 中心设备管理功能的一部分。部署是允许将多个模块部署到多个设备、跟踪模块的状态和运行状况以及在必要时做出更改的动态过程。

在本文中，你将安装 Azure CLI 和 IoT 扩展。然后，了解如何使用可用的 CLI 命令将模块部署到一组 IoT Edge 设备并监视进度。

先决条件

Azure 订阅中的 IoT 中心。
一个或多个 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 文件。在下一部分通过运行命令将配置应用到设备时，会用到这个文件路径。

下面是一个基本的部署清单示例，其中有一个模块：

{
  "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 一起发布。它启用了模块启动顺序和路由优先级等功能。

分层部署

分层部署是一种自动部署类型，可以彼此重叠。有关分层部署的详细信息，请参阅了解单设备或大规模 IoT Edge 自动部署。

使用 Azure CLI 创建和管理分层部署，就像任何自动部署一样（只有少量差异）。创建分层部署后，与对任何部署一样，Azure CLI 可对分层部署正常工作。若要创建分层部署，请将 --layered 标志添加到 create 命令。

第二个区别在于部署清单的构造。标准自动部署除了包含任何用户模块外，还必须包含系统运行时模块，而分层部署只能包含用户模块。分层部署还需要设备上的标准自动部署，以便提供每个 IoT Edge 设备的必需组件（如系统运行时模块）。

下面是具有一个模块的基本分层部署清单示例：

{
  "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 门户识别分层部署需要使用此格式设置。例如：

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 模块孪生中显示为“已设定目标”，而不是“已应用” 。

总之，若要创建分层部署：

将 --layered 标志添加到 Azure CLI create 命令。
请不要包含系统模块。
在 $edgeAgent 和 $edgeHub 下使用完整的点表示法。

有关在分层部署中配置模块孪生的详细信息，请参阅分层部署。

使用标记标识设备

创建部署之前，必须能够指定想要影响的设备。 Azure IoT Edge 标识使用设备孪生中的标记来标识设备。

每个设备都可以具有多个标记，你可以采用适合你的解决方案的任何方式定义这些标记。例如，如果管理有智能楼宇的校园，可将以下标记添加到设备：

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

有关设备孪生和标记的详细信息，请参阅了解和使用 IoT 中心的设备孪生。

创建部署

请创建一个包含部署清单和其他参数的部署，以便将模块部署到目标设备。

使用 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 部署。

注意

在创建新的 IoT Edge 部署时，IoT 中心处理新配置并将新的所需属性传播到目标设备可能最长会需要 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] 命令切换到所需订阅。

通过