使用 Azure CLI 大规模部署并监视 IoT Edge 模块Deploy and monitor IoT Edge modules at scale using the Azure CLI

使用 Azure 命令行接口创建 IoT Edge 自动部署,同时为多个设备管理正在进行的部署。Create an IoT Edge automatic deployment using the Azure command-line interface to manage ongoing deployments for many devices at once. IoT Edge 的自动部署是 IoT 中心自动设备管理功能的一部分。Automatic deployments for IoT Edge are part of the automatic device management feature of IoT Hub. 部署是允许将多个模块部署到多个设备、跟踪模块的状态和运行状况以及在必要时做出更改的动态过程。Deployments are dynamic processes that enable you to deploy multiple modules to multiple devices, track the status and health of the modules, and make changes when necessary.

有关详细信息,请参阅了解单设备 IoT Edge 自动部署或大规模 IoT Edge 自动部署For more information, see Understand IoT Edge automatic deployments for single devices or at scale.

在本文中,将安装 Azure CLI 和 IoT 扩展。In this article, you set up Azure CLI and the IoT extension. 然后,了解如何使用可用的 CLI 命令将模块部署到一组 IoT Edge 设备并监视进度。You then learn how to deploy modules to a set of IoT Edge devices and monitor the progress using the available CLI commands.

CLI 先决条件CLI Prerequisites

  • Azure 订阅中的 IoT 中心An IoT hub in your Azure subscription.
  • 已安装 IoT Edge 运行时的 IoT Edge 设备IoT Edge devices with the IoT Edge runtime installed.
  • 环境中的 Azure CLIAzure CLI in your environment. Azure CLI 版本必须至少是 2.0.70 或更高版本。At a minimum, your Azure CLI version must be 2.0.70 or above. 请使用 az --version 验证版本。Use az --version to validate. 此版本支持 az 扩展命令,并引入了 Knack 命令框架。This version supports az extension commands and introduces the Knack command framework.
  • 适用于 Azure CLI 的 IoT 扩展The IoT extension for Azure CLI.

配置部署清单Configure a deployment manifest

部署清单是一个 JSON 文档,其中描述了要部署的模块、数据在模块间的流动方式以及模块孪生的所需属性。A deployment manifest is a JSON document that describes which modules to deploy, how data flows between the modules, and desired properties of the module twins. 有关详细信息,请参阅了解如何在 IoT Edge 中部署模块和建立路由For more information, see Learn how to deploy modules and establish routes in IoT Edge.

若要使用 Azure CLI 来部署模块,请将部署清单在本地另存为 .txt 文件。To deploy modules using Azure CLI, save the deployment manifest locally as a .txt file. 在下一部分通过运行命令将配置应用到设备时,会用到这个文件路径。You use the file path in the next section when you run the command to apply the configuration to your device.

下面是一个基本的部署清单示例,其中有一个模块:Here's a basic deployment manifest with one module as an example:

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

分层部署Layered deployment

分层部署是一种自动部署类型,可以彼此重叠。Layered deployments are a type of automatic deployment that can be stacked on top of each other. 有关分层部署的详细信息,请参阅了解单设备或大规模 IoT Edge 自动部署For more information about layered deployments, see Understand IoT Edge automatic deployments for single devices or at scale.

使用 Azure CLI 创建和管理分层部署,就像任何自动部署一样(只有少量差异)。Layered deployments can be created and managed with the Azure CLI like any automatic deployment, with just a few differences. 创建分层部署后,与任何部署一样,相同 Azure CLI 适用于分层部署。Once a layered deployment is created, same Azure CLI work for layered deployments the same as any deployment. 若要创建分层部署,请将 --layered 标志添加到 create 命令。To create a layered deployment, add the --layered flag to the create command.

第二个区别在于部署清单的构造。The second difference is in the construction of the deployment manifest. 标准自动部署除了包含任何用户模块外,还必须包含系统运行时模块,而分层部署只能包含用户模块。While standard automatic deployment must contain the system runtime modules in addition to any user modules, layered deployments can only contain user modules. 相反,分层部署还需要在设备上进行标准自动部署,以便提供每个 IoT Edge 设备的必需组件(如系统运行时模块)。Instead, layered deployments need a standard automatic deployment be on a device as well, to supply the required components of every IoT Edge device, like the system runtime modules.

下面是具有一个模块的基本分层部署清单示例:Here's a basic layered deployment manifest with one module as an example:

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

前面的示例显示了模块的分层部署设置 properties.desiredThe previous example showed a layered deployment setting the properties.desired for a module. 如果此分层部署针对已应用相同模块的设备,则会覆盖任何现有的所需属性。If this layered deployment targeted a device where the same module was already applied, it would overwrite any existing desired properties. 若要更新,而不是覆盖所需的属性,可以定义新的子节。In order to update, instead of overwrite, desired properties, you can define a new subsection. 例如:For example:

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

有关在分层部署中配置模块孪生的详细信息,请参阅分层部署For more information about configuring module twins in layered deployments, see Layered deployment

使用标记标识设备Identify devices using tags

创建部署之前,必须能够指定想要影响的设备。Before you can create a deployment, you have to be able to specify which devices you want to affect. Azure IoT Edge 标识使用设备孪生中的标记标识设备。Azure IoT Edge identifies devices using tags in the device twin. 每个设备均可以拥有多个标记,你可以用适合解决方案的任何方式定义它们。Each device can have multiple tags that you define in any way that makes sense for your solution. 例如,如果管理有智能楼宇的校园,可将以下标记添加到设备:For example, if you manage a campus of smart buildings, you might add the following tags to a device:

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

有关设备孪生和标记的详细信息,请参阅了解和使用 IoT 中心的设备孪生For more information about device twins and tags, see Understand and use device twins in IoT Hub.

创建部署Create a deployment

请创建一个包含部署清单和其他参数的部署,以便将模块部署到目标设备。You deploy modules to your target devices by creating a deployment that consists of the deployment manifest as well as other parameters.

使用 az iot edge deployment create 命令创建部署:Use the az iot edge deployment create command to create a deployment:

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 标志相同的命令创建分层部署。Use the same command with the --layered flag to create a layered deployment.

deployment create 命令采用以下参数:The deployment create command takes the following parameters:

  • --layered - 用于将部署标识为分层部署的可选标志。--layered - An optional flag to identify the deployment as a layered deployment.
  • --deployment-id - 将在 IoT 中心创建的部署的名称。--deployment-id - The name of the deployment that will be created in the IoT hub. 为部署提供唯一名称(最多包含 128 个小写字母)。Give your deployment a unique name that is up to 128 lowercase letters. 避免空格和以下无效字符:& ^ [ ] { } \ | " < > /Avoid spaces and the following invalid characters: & ^ [ ] { } \ | " < > /. 必需参数。Required parameter.
  • --content - 部署清单 JSON 的文件路径。--content - Filepath to the deployment manifest JSON. 必需参数。Required parameter.
  • --hub-name - 将在其中创建部署的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment will be created. 此中心必须在当前订阅中。The hub must be in the current subscription. 通过 az account set -s [subscription name] 命令更改当前订阅。Change your current subscription with the az account set -s [subscription name] command.
  • --labels - 添加用于跟踪部署的标签。--labels - Add labels to help track your deployments. 标签是描述部署的“名称, 值”对。Labels are Name, Value pairs that describe your deployment. 标签对名称和值采用 JSON 格式设置。Labels take JSON formatting for the names and values. 例如: {"HostPlatform":"Linux", "Version:"3.0.1"}For example, {"HostPlatform":"Linux", "Version:"3.0.1"}
  • --target-condition - 输入一个目标条件,用于确定哪些设备会成为此部署的目标。--target-condition - Enter a target condition to determine which devices will be targeted with this deployment. 该条件基于设备孪生标记或设备孪生报告的属性,应与表达式格式相匹配。 The condition is based on device twin tags or device twin reported properties and should match the expression format. 例如,tags.environment='test' and properties.reported.devicemodel='4000x' For example, tags.environment='test' and properties.reported.devicemodel='4000x'.
  • --priority - 一个正整数。--priority - A positive integer. 如果同一设备上确定的部署目标至少有两个,则会应用优先级数值最高的部署。In the event that two or more deployments are targeted at the same device, the deployment with the highest numerical value for Priority will apply.
  • --metrics - 创建查询 edgeHub 报告的属性以跟踪部署状态的指标。--metrics - Create metrics that query the edgeHub reported properties to track the status of a deployment. 指标采用 JSON 输入或 filepath。Metrics take JSON input or a filepath. 例如,'{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'For example, '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

若要使用 Azure CLI 监视部署,请参阅监视 IoT Edge 部署To monitor a deployment using Azure CLI, see monitor IoT Edge deployments.

修改部署Modify a deployment

修改部署时,更改会立即复制到所有目标设备。When you modify a deployment, the changes immediately replicate to all targeted devices.

如果更新目标条件,将发生以下更新:If you update the target condition, the following updates occur:

  • 如果设备虽然不满足旧的目标条件,但满足新的目标条件,且此部署是此设备的最高优先级,则此部署将应用到设备。If a device didn't meet the old target condition, but meets the new target condition and this deployment is the highest priority for that device, then this deployment is applied to the device.
  • 如果当前运行此部署的设备不再满足目标条件,则它将卸载此部署并采用下一个最高优先级部署。If a device currently running this deployment no longer meets the target condition, it uninstalls this deployment and takes on the next highest priority deployment.
  • 如果当前运行此部署的设备不再满足目标条件且不满足任何其他部署的目标条件,则此设备上不会发生任何更改。If a device currently running this deployment no longer meets the target condition and doesn't meet the target condition of any other deployments, then no change occurs on the device. 设备在当前状态下继续运行当前模块,但不再作为此部署的一部分被托管。The device continues running its current modules in their current state, but is not managed as part of this deployment anymore. 一旦它满足任何其他部署的目标条件,将卸载此部署并采用新的部署。Once it meets the target condition of any other deployment, it uninstalls this deployment and takes on the new one.

你无法更新部署的内容,其中包括在部署清单中定义的模块和路由。You cannot update the content of a deployment, which includes the modules and routes defined in the deployment manifest. 如果你想要更新部署的内容,则可以通过创建针对具有较高优先级的相同设备的新部署来实现此目的。If you want to update the content of a deployment, you do so by creating a new deployment that targets the same devices with a higher priority. 你可以修改现有模块的某些属性,包括目标条件、标签、指标和优先级。You can modify certain properties of an existing module, including the target condition, labels, metrics, and priority.

使用 az iot edge deployment update 命令更新部署:Use the az iot edge deployment update command to update a deployment:

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

deployment update 命令采用以下参数:The deployment update command takes the following parameters:

  • --deployment-id - IoT 中心存在的部署的名称。--deployment-id - The name of the deployment that exists in the IoT hub.
  • --hub-name - 部署所在的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment exists. 此中心必须在当前订阅中。The hub must be in the current subscription. 使用 az account set -s [subscription name] 命令切换到所需订阅Switch to the desired subscription with the command az account set -s [subscription name]
  • --set - 更新部署中的属性。--set - Update a property in the deployment. 可以更新以下属性:You can update the following properties:
    • targetCondition - 例如 targetCondition=tags.location.state='Oregon'targetCondition - for example targetCondition=tags.location.state='Oregon'
    • 标签labels
    • prioritypriority
  • --add - 向部署中添加新属性,包括目标条件或标签。--add - Add a new property to the deployment, including target conditions or labels.
  • --remove - 删除现有属性,包括目标条件或标签。--remove - Remove an existing property, including target conditions or labels.

删除部署Delete a deployment

删除部署时,任何设备都将采用下一个最高优先级部署。When you delete a deployment, any devices take on their next highest priority deployment. 如果设备不满足任何其他部署的目标条件,则删除该部署时不会删除模块。If your devices don't meet the target condition of any other deployment, then the modules are not removed when the deployment is deleted.

使用 az iot edge deployment delete 命令删除部署:Use the az iot edge deployment delete command to delete a deployment:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

deployment delete 命令采用以下参数:The deployment delete command takes the following parameters:

  • --deployment-id - IoT 中心存在的部署的名称。--deployment-id - The name of the deployment that exists in the IoT hub.
  • --hub-name - 部署所在的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment exists. 此中心必须在当前订阅中。The hub must be in the current subscription. 使用 az account set -s [subscription name] 命令切换到所需订阅Switch to the desired subscription with the command az account set -s [subscription name]

后续步骤Next steps

了解有关将模块部署到 IoT Edge 设备的详细信息。Learn more about Deploying modules to IoT Edge devices.