使用 Azure IoT 和 OSConfig 管理 OS 包管理器

项目
09/16/2023

重要

版本 1.0.3 (2022 年 6 月 28 日发布) 包括对可能影响现有用户的成员名称的重大更改。有关详细信息，请参阅：成员名称从 PascalCase 转换为 1.0.3 版中的 camelCase

受众和范围

本文旨在支持使用 Azure IoT 预配或管理设备 的人员。如果这听起来不像你，请考虑查看 OSConfig 的受众文档。

本文介绍如何获取 包管理器 状态和设置包管理器 所需的状态。例如：

功能	用例
确保包管理器从所需源拉取	• 你的操作策略是，设备包管理器应从具有已批准的库和组件的专用包存储库中提取 • 需要设备从特定供应商的存储库获取包
通知包管理器所需包	• 操作策略是设备应具有特定的包，例如“library-XYZ-v2” • 操作策略是设备应具有包的特定依赖项关系图
比较设备的包或源列表	• 你的操作策略是，已部署设备的已安装程序包列表应与已知良好的设备匹配

如果此处提供了参考信息，而不是交互式用例示例，则可以跳到参考部分。

重要

目前，包括 Debian 和 Ubuntu 在内的基于 apt 的发行版在范围内。若要开发对基于 RPM 的发行版的支持，请参阅扩展性文档。

例如，在没有 apt (的环境中，从源生成并在 Red Hat 系列发行版) 上运行，你可能会看到以下日志消息，指示 PackageManagerConfiguration 模块不适用。

在 osconfig_pmc.log 中，包含以下文本的行：
[ERROR] Cannot run on this platform, could not find required tool apt-get
在 osconfig_pnp_agent.log 中，包含以下文本的行：
[ERROR] PackageManagerConfiguration.state: MpiGet failed with 500

用例示例

这些示例可用作适应独特环境的起点。

在实时系统上尝试示例的先决条件

如果使用本文进行参考，则无需先决条件。可以查看示例、复制属性名称等。

如果要尝试实时系统上的示例 (建议) ，请执行以下步骤：

创建免费的 Azure 帐户或使用现有帐户
将至少一个已启用 OSConfig 的设备连接到IoT 中心

提示

若要轻松创建附加 (虚拟) 设备的IoT 中心，请参阅在 5 分钟内使用 Azure IoT) 实验室环境创建 OSConfig (
准备好按照示例中的Azure 门户说明或 Azure CLI 说明进行操作：

如果想要使用Azure 门户

登录到Azure 门户并访问IoT 中心的“概述”页

-OR - 如果想要使用 Azure CLI

建议：通过登录到 Azure 门户将 Azure Cloud Shell用作 bash 环境，然后在 bash 模式屏幕捕获中启动 Azure Cloud Shell，
替代方法：如果想要使用自己的 bash 环境，而不是Cloud Shell，请安装 Azure CLI 并登录
通过运行确保 Azure IoT 扩展准备就绪 az extension add --name azure-iot

示例 1。指定所需的包源

此示例演示 Azure IoT 工作流，以确保设备使用作为其包源之一的 Ubuntu 18.04 的 packages.microsoft.com prod 通道。可以调整此示例以使用任何包源。例如，不同的发行版/版本的公共存储库、特定供应商的存储库或你策划的专用存储库。

这些说明适用于门户、CLI、特定设备和大规模预配和管理。

在IoT 中心的门户页中，导航到要管理的设备的 OSConfig 孪生体，然后将以下内容properties.desired添加到该部分，然后用逗号将其与下一项properties.desired分开。

"PackageManagerConfiguration": {
   "desiredState": {
      "gpgKeys": {
         "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
      },
      "sources": {
         "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
      },
      "packages": [
      ]
   }
}

显示如何从 Azure 门户配置包管理器配置的屏幕截图

若要为设备群设置包管理器配置，需要创建一个IoT 中心配置 (也称为IoT 中心自动设备管理 [ADM]) 。

在Azure IoT 中心的门户页中，选择“设备管理”-“>配置”-“>添加模块配置”。

指定一个名称，并使用所需的包管理器配置设置 孪生设置 。将 模块孪生属性 设置为 properties.desired. PackageManagerConfiguration 模块 孪生属性，并将模块孪生属性内容 设置为以下内容：

{"desiredState": {
   "gpgKeys": {
      "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
   },
   "sources": {
      "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
   },
   "packages": [
   ]
}}

创建名称为 successfullyConfigured 的自定义指标和指标条件，如下所示。此指标查询将标识已达到所需状态的所有设备。
```
SELECT deviceId FROM devices.modules
where moduleId='osconfig'  
and properties.reported.PackageManagerConfiguration.state.executionState=2
```
对于 目标模块，请指定设备在范围内的条件。在此示例中，我们将通过指定 目标条件 来面向所有已启用 OSConfig 的设备 FROM devices.modules where moduleId='osconfig'

使用以下示例命令设置单个设备的 OSConfig 孪生体，替换 <设备 ID> 和/或 <中心名称> 以匹配环境。

az iot hub module-twin update -m osconfig --desired \
'{
  "PackageManagerConfiguration": {
    "desiredState": {
      "gpgKeys": {
        "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
      },
      "sources": {
        "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
      },
      "packages": [
      ]
    }
  }
}' -d <device id> --hub-name <hub name>

显示 Azure 门户中的配置的屏幕截图

若要为设备群设置包管理器配置，需要创建一个IoT 中心配置 (也称为IoT 中心自动设备管理 [ADM]) 。

使用以下示例命令创建IoT 中心配置。此配置包括目标条件、所需配置和名为 successfullyConfigured 的自定义指标。请务必将中心名称>替换为<IoT 中心名称。

az iot hub configuration create --content "{
    \"moduleContent\": {
       \"properties.desired.PackageManagerConfiguration\": {
          \"desiredState\": {
          \"gpgKeys\": {
             \"pkgs-msft_key\": \"https://packages.microsoft.com/keys/microsoft.asc\"
          },
          \"sources\": {
             \"pkgs-msft_insiders-slow\": \"deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main\"
          },
          \"packages\": [
          ]
          }
       }
    }
}" \
--target-condition "from devices.modules where moduleId='osconfig'" --priority 10 \
--metrics "{
  \"metrics\": {
    \"queries\": {
      \"successfullyConfigured\": \"select deviceId from devices.modules where moduleId='osconfig' AND properties.reported.PackageManagerConfiguration.state.executionState='2'\"
    }
  }
}" --config-id my_pkg_mgr_config --hub-name <hub name>

显示如何通过 bash 为设备群创建包管理器配置的屏幕截图

示例 1 是关于定义新的包源。若要报告相同，请继续执行示例 2。

示例 2。报告包管理器状态和配置

在此示例中，我们将报告：

添加了哪些包源
任何设备是否遇到 PackageManagerConfiguration 错误

在上面的示例 1 中，我们向特定设备的 OSConfig 模块孪生添加了所需的 PackageManagerConfiguration 值。现在可以观察结果。

在上述示例中添加了所需的 PackageManagerConfiguration 后，等待 1 分钟 (网络通信、设备端活动等)
在同一设备的 OSConfig 模块孪生中，浏览到属性，然后报告，然后报告 PackageManagerConfiguration，然后状态。
这将显示包管理器配置的最新状态。
1. sourcesFileNames 应反映添加的两个通道
2. executionStatus 应为 2。有关可能的值，请参阅：扩展性文档

在上面的示例 1 中，我们创建了IoT 中心配置。现在，我们可以检查该配置的指标查询，以查看哪些设备已成功配置。

导航到在示例 1 中创建的IoT 中心配置
观察应用指标;这显示了云) 中哪些设备的孪生 (已使用所需属性进行设置
1. 创建配置后可能需要长达 5 分钟的时间
观察 成功配置 指标;这反映了哪些设备已完成端到端配置

提示

应用指标默认存在于所有IoT 中心配置中。成功配置指标是在示例 1 中创建配置时显式定义的。

选：还可以观察使用IoT 中心查询成功应用包配置和指定包的设备列表。导航到设备管理 -->Query 并运行以下查询：
```
SELECT deviceId FROM devices.modules
 where moduleId='osconfig'  
 and properties.reported.PackageManagerConfiguration.state.executionState=2
```

使用以下示例命令显示单个设备的 OSConfig 孪生的 PackageManagerConfiguration.state 部分，替换 <设备 ID> 和/或 <中心名称> 以匹配环境。
```
az iot hub module-twin show -m osconfig --query properties.reported.PackageManagerConfiguration.state --output jsonc -d <device id> -n <hub name> 
```

在上面的示例 1 中，我们创建了IoT 中心配置。现在，我们可以检查该配置的指标查询，以查看哪些设备已成功配置。

观察 应用的 指标

这显示了云) 中哪些设备的孪生 (已使用所需属性进行设置。

创建配置后可能需要长达 5 分钟的时间。
```
az iot hub configuration show-metric --metric-id appliedCount -c my_pkg_mgr_config -n <hub name> --metric-type system
```

观察成功配置指标

这反映了哪些设备已完成配置端到端。

az iot hub configuration show-metric --metric-id successfullyConfigured -c my_pkg_mgr_config -n <hub name> --metric-type user

显示如何使用 bash 验证指标的屏幕截图

选：配置外部的报告

不必使用IoT 中心配置的指标功能来存储和使用报告/符合性查询。还可以直接使用 IoT 中心 Query 函数，例如：
```
az iot hub query -q \
"SELECT deviceId, properties.reported.PackageManagerConfiguration.state FROM devices.modules WHERE moduleId='osconfig'" \
--hub-name <hub name>
```

参考信息

对象模型说明

本部分介绍孪生属性和相应的行为。

了解 Azure IoT 中有两种用于描述孪生内容的心理模型或视角，这非常有用。

普通所需/报告透视

这是核心IoT 中心对象模型。它由 azure 门户和 IoT 资源管理器中的纯孪生视图IoT 中心查询服务、IoT 中心配置服务az iot hub module-twin、命令和纯孪生视图使用。
数字孪生定义语言 (DTDL) 增强视角

DTDL (具有相应的模式（包括 Azure IoT 即插即用 [PnP]) 使应用和服务能够预测、验证和更好地上下文化孪生内容。这由 IoT 资源管理器中的 PnP 视图、Azure 数字孪生服务以及与 IoT 中心交互时可能由云解决方案使用。

在大多数情况下，不需要区分。例如，“gpgKeys”在任一视图中称为“gpgKeys”。

在某些情况下，区别可能会有所帮助。例如，下面给出的路径值。在这些情况下，首先给出普通的所需/报告说明，然后是括号中的 DTDL 增强透视。

admin) 的 desiredState (输入

路径： properties.desired.PackageManagerConfiguration.desiredState (DTDL： PackageManagerConfiguration 组件 -->desiredState 可写属性)
说明：管理员输入;允许向设备添加包源和包

成员

名称	类型	说明
sources	`sourceName`映射：`sourceDescriptor` (字符串)	对于字典中的每个对： • `sourceName` 是管理员指定的标识符，例如： `my-source-foo` • `sourceDescriptor` 是包管理器使用的格式的源定义字符串;例如： `deb [arch=amd64,armhf,arm64 signed-by=my-repo-key] https://packages.microsoft.com/ubuntu/18.04/prod focal main` `sourceDescriptor`• 传入`signed-by=`的值应为以下) 所述的 (密钥`gpgKeys`的名称;例如：signed-by=my-source-foo-key • 添加或修改源时，如果源描述符) 存在，则 (覆盖现有文件的 sources.list.d 中的文件 • 若要指定设备不应使用特定源 (假设它以前在 sources.list.d 中定义，而不是系统) 的其他地方，请包括一对，例如`"my-source-bar": ""`：如果 sources.list.d 中存在名为 my-source-bar.list 的文件，则会删除该文件 • 如果不再需要不应使用指令 (例如，) 一段时间后， my-source-bar 不再相关，可以通过将值从 “my-source-bar”更改为“my-source-bar”： null，将其从所需的孪生中删除：
gpgKeys	`key-name`映射：`uri` (字符串)	用于通知包存储库公钥的管理器; 对于字典中的每个对： • `key-name` is an admin specified identifier; for example: my-repo-foo-key, which is referred to from `signed-by` in `sources` • `uri` 是存储库公钥的位置;例如： `https://packages.microsoft.com/keys/microsoft.asc` • 将密钥作为文件添加到 /usr/share/keyrings/;请注意，为了确保密钥的适用性限定范围，将使用此非特定于 apt 的路径;apt 只会将该密钥应用于显式关联到它的源， (`signed-by` • 若要从 /usr/share/keyring 中删除`key-name`密钥文件，以匹配文件名 (而不) 扩展名，并设置为`uri`“”
packages	包标识符数组 (字符串)	• 指示包管理器确保安装这些包 • 类似于在 Debian 上安装包名称>的 apt < • 性质上加法 (非破坏性) ;例如，空列表表示“不执行任何操作” (不 “卸载系统上的所有包”)

IoT 中心孪生体) 孪生properties.desired体部分中所示的示例有效负载 (

"PackageManagerConfiguration": {
    "desiredState": {
       "gpgKeys": {
          "pkgs-msft_key": "https://packages.microsoft.com/keys/microsoft.asc"
       },
       "sources": {
          "pkgs-msft_insiders-slow": "deb [arch=amd64,armhf,arm64 signed-by=pkgs-msft_key] https://packages.microsoft.com/ubuntu/18.04/prod insiders-slow main"
       },
       "packages": [
          "cowsay"
       ]
    }
}

state

路径： properties.reported.PackageManagerConfiguration.state (DTDL 透视： PackageManagerConfiguration 组件 ->state 只读属性)
说明：设备报告的 PackageManagerConfiguration 状态

成员

名称	类型	说明
packagesFingerprint	字符串	• 设备上所有已安装包列表的不透明指纹 (不限于) 中 `desiredState.packages` 引用的包 • 用于将大量设备与已知良好的设备进行比较
packages	包标识符数组 (字符串)	• 管理员指定的包的名称和状态 (版本或“失败”) `desiredState.packages` • 如果已成功安装包，则名称后跟已安装的版本号 • 如果无法安装包，则名称后跟“失败”
sourcesFingerprint	字符串	• 设备使用的包源不透明指纹 • 用于将大量设备与已知良好的设备进行比较
sourcesFilenames	(字符串) 的文件名数组	• (为文件名的包源列表，例如 my-repo.list) ，这些源已通过 /etc/apt/sources.list.d (添加到包管理器中，) • 包括存在的任何源，无论它们是否通过 `desiredState.sources`
executionState	int	• 总体成功/失败状态 • 名义值为 0 (初始状态，未指定 desiredState) 或 2 (成功) • 有关其他值，请参阅：扩展性文档
executionSubstate	int	• 有关可能的值，请参阅：扩展性文档
executionSubstateDetails	字符串	• 有关故障排除的其他信息

) 孪生properties.reported部分所示的示例有效负载 (

"PackageManagerConfiguration": {
    "state": {
       "packagesFingerprint": "9e7a85de3d067474e3621d7e1618f6ac0e2e8fc6cb9d60ee92af9927294114d3",
       "packages": [
          "cowsay=3.03+dfsg2-7"
       ],
       "executionState": 2,
       "executionSubstate": 0,
       "executionSubstateDetails": "",
       "sourcesFingerprint": "64b7de49c2be4ef2c180e4a978300fbb7b8a743a89e4038ba7ac6a91c31b625f",
       "sourcesFilenames": [
          "pkgs-msft_insiders-slow.list"
       ]
    }
}

desiredState (报告;从设备) 确认

路径： properties.reported.PackageManagerConfiguration.desiredState (DTDL 透视： PackageManagerConfiguration 组件 --> 可写属性的 desiredState ACK 部分)
说明：此附加报告元素是来自设备的确认;用于管理工具并报告它补充 state- 使管理工具链能够确定设备是否已收到在管理员可写/所需中捕获的管理员意向 desiredState

成员

名称	类型	说明
值	对象 (object)	• 应镜像 `properties.desired.PackageManagerConfiguration.desiredState`
ac	int	• 指示从管理员接收和处理 desiredState 的设备的成功 (值 200) 或失败 (值 400)

后续步骤

有关 OSConfig 方案和功能的概述，请参阅：

什么是适用于 IoT 的 OSconfig

有关特定实际示例，请参阅：

通过