终止支持通知：2026 年 10 月 7 日， AWS 将停止对的支持。 AWS IoT Greengrass Version 1 2026 年 10 月 7 日之后，您将无法再访问这些 AWS IoT Greengrass V1 资源。如需了解更多信息，请访问[迁移自 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Docker 应用程序部署连接器 Greengrass Docker 应用程序部署连接器可以更轻松地在核心上运行 Docker 镜像。 AWS IoT Greengrass 连接器使用 Docker Compose 从 `docker-compose.yml` 文件启动多容器 Docker 应用程序。具体而言，连接器运行 `docker-compose` 命令来管理单个核心设备上的 Docker 容器。有关详细信息，请参阅 Docker 文档中的 [Docker Compose 概述](https://docs.docker.com/compose/) 。连接器可以访问存储在 Docker 容器镜像仓库中的 Docker 映像，如 Amazon Elastic Container Registry (Amazon ECR)、Docker Hub 和私有 Docker 信任的镜像仓库。 在部署 Greengrass 组之后，连接器将提取最新的映像并启动 Docker 容器。它运行 `docker-compose pull` 和 `docker-compose up` 命令。然后，连接器将命令的状态发布到[输出 MQTT 主题](#docker-app-connector-data-output)。它还记录有关运行 Docker 容器的状态信息。这使您可以在 Amazon 中监控您的应用程序日志 CloudWatch。有关更多信息，请参阅 [使用 AWS IoT Greengrass 日志进行监控](greengrass-logs-overview.md)。连接器还会在每次 Greengrass 守护程序重新启动时启动 Docker 容器。可以在内核上运行的 Docker 容器数量取决于您的硬件。 Docker 容器在核心设备上的 Greengrass 域之外运行，因此它们无法访问核心的进程间通信 (IPC)。但是，您可以使用 Greengrass 组件配置某些通信通道，例如本地 Lambda 函数。有关更多信息，请参阅 [与 Docker 容器通信](#docker-app-connector-communicating)。 您可以将连接器用于在核心设备上托管 Web 服务器或 MySQL 服务器等此类方案。Docker 应用程序中的本地服务可以彼此、与本地环境中的其他进程以及云服务通信。例如，您可以在核心上运行 Web 服务器，将请求从 Lambda 函数发送到云中的 Web 服务。 此连接器在[无容器](lambda-group-config.md#no-container-mode)隔离模式下运行，因此，您可以将其部署到在没有 Greengrass 容器化的情况下运行的 Greengrass 组。 此连接器具有以下版本。 | 版本 | 进行筛选 | | --- | --- | | 7 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/7` | | 6 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/6` | | 5 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5` | | 4 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/4` | | 3 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/3` | | 2 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/2` | | 1 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/1` | 有关版本更改的信息，请参阅[更改日志](#docker-app-connector-changelog)。 ## 要求 此连接器具有以下要求： + AWS IoT Greengrass 核心软件 v1.10 或更高版本。 **注意** OpenWrt 发行版不支持此连接器。 + [Python](https://www.python.org/) 版本 3.7 或 3.8 已安装在核心设备上，并已添加到 PATH 环境变量中。 **注意** 要使用 Python 3.8，请运行以下命令来创建从默认 Python 3.7 安装文件夹到已安装的 Python 3.8 二进制文件的符号链接。 ``` sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7 ``` 这会将设备配置为满足 AWS IoT Greengrass的 Python 要求。 + Greengrass 内核上至少有 36 MB RAM，供连接器监控正在运行的 Docker 容器。总内存需求取决于在内核上运行的 Docker 容器的数量。 + Greengrass 核心上安装的 [Docker Engine](https://docs.docker.com/install/) 1.9.1 或更高版本。版本 19.0.3 是经验证可与连接器一起使用的最新版本。 `docker` 可执行文件必须位于 `/usr/bin` 或 `/usr/local/bin` 目录中。 **重要** 我们建议您安装凭证存储以保护 Docker 凭证的本地副本。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 有关在 Amazon Linux 发行版上安装 Docker 的信息，请参阅*《Amazon Elastic Container Service 开发人员指南》*中的 [Amazon ECS 的 Docker 基础知识](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html)。 + Greengrass 核心上安装的 [Docker Compose](https://docs.docker.com/compose/install/)。`docker-compose` 可执行文件必须位于 `/usr/bin` 或 `/usr/local/bin` 目录中。 以下 Docker Compose 版本经验证可与此连接器一起使用。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/docker-app-connector.html) + 一个 Docker Compose 文件（例如，`docker-compose.yml`），存储在 Amazon Simple Storage Service (Amazon S3) 中。格式必须与安装在核心上的 Docker Compose 版本兼容。在核心上使用文件之前，应先对其进行测试。如果在部署 Greengrass 组后编辑该文件，则必须重新部署该组以更新核心上的本地副本。 + 有权调用本地 Docker 守护程序并写入存储 Compose 文件的本地副本的目录的 Linux 用户。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 + [Greengrass 组角色](group-role.md)，配置为允许对包含 Compose 文件的 S3 存储桶执行 `s3:GetObject` 操作。此权限显示在以下示例 IAM policy 中。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowAccessToComposeFileS3Bucket", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Effect": "Allow", "Resource": "arn:aws:s3:::bucket-name/*" } ] } ``` ------ **注意** 如果您的 S3 桶已启用版本控制，则必须将角色配置为也允许执行 `s3:GetObjectVersion` 操作。有关更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 + 如果您的 Docker Compose 文件引用 Amazon ECR 中存储的 Docker 映像，则为配置为允许执行以下操作的 [Greengrass 组角色](group-role.md)： + 对包含 Docker 镜像的 Amazon ECR 存储库执行的 `ecr:GetDownloadUrlForLayer` 和 `ecr:BatchGetImage` 操作。 + 对您的资源执行的 `ecr:GetAuthorizationToken` 操作。 存储库必须与连接器 AWS 区域 相同 AWS 账户 。 **重要** 组角色中的权限可由 Greengrass 组中的所有 Lambda 函数和连接器代入。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 以下示例策略中显示了这些权限。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowGetEcrRepositories", "Effect": "Allow", "Action": [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": [ "arn:aws:ecr:us-east-1:123456789012:repository/repository-name" ] }, { "Sid": "AllowGetEcrAuthToken", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" } ] } ``` ------ 有关更多信息，请参阅 *Amazon ECR 用户指南*中的 [Amazon ECR 存储库策略示例](https://docs.aws.amazon.com/AmazonECR/latest/userguide/RepositoryPolicyExamples.html)。 对于组角色要求，您必须将角色配置为授予所需权限，并确保角色已添加到组中。有关更多信息，请参阅[管理 Greengrass 组角色（控制台）](group-role.md#manage-group-role-console)或[管理 Greengrass 组角色 (CLI)](group-role.md#manage-group-role-cli)。 + 如果您的 Docker Compose 文件引用来自 [AWS Marketplace](https://aws.amazon.com/marketplace) 的 Docker 镜像，则连接器还具有以下要求： + 您必须订阅 AWS Marketplace 容器产品。有关更多信息，请参阅*《AWS Marketplace 订阅者指南》*中的[查找和订阅容器产品](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-finding-and-subscribing-to-container-products.html)。 + AWS IoT Greengrass 必须配置为支持本地密钥，如[密钥要求](secrets.md#secrets-reqs)中所述。连接器仅使用此功能从中检索您的密钥 AWS Secrets Manager，而不是存储它们。 + 你必须在 Secrets Manager 中为每个存储你的 Compose 文件中引用的 Docker 镜像的 AWS Marketplace 注册表创建一个密钥。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 + 如果您的 Docker Compose 文件从 Amazon ECR（如 Docker Hub）之外的镜像仓库中的私有存储库引用 Docker 镜像，则连接器还具有以下要求： + AWS IoT Greengrass 必须配置为支持本地密钥，如[密钥要求](secrets.md#secrets-reqs)中所述。连接器仅使用此功能从中检索您的密钥 AWS Secrets Manager，而不是存储它们。 + 您必须在 Secrets Manager 中为用于存储在 Compose 文件中引用的 Docker 镜像的每个私有存储库创建一个密钥。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 + 当您部署包含此连接器的 Greengrass 组时，Docker 守护程序必须正在运行。 ### 从私有存储库访问 Docker 镜像 如果您使用凭证问 Docker 镜像，则必须允许连接器访问它们。您执行此操作的方式取决于 Docker 镜像的位置。 对于 Amazon ECR 中存储的 Docker 镜像，您可以授予在 Greengrass 组角色中获取授权令牌的权限。有关更多信息，请参阅 [要求](#docker-app-connector-req)。 对于存储在其他私有存储库或注册表中的 Docker 镜像，您必须在中创建密钥 AWS Secrets Manager 来存储您的登录信息。这包括您在中订阅的 Docker 镜像。 AWS Marketplace为每个存储库创建一个密钥。如果您在 Secrets Manager 中更新您的密钥，则更改会在下次部署组时传播到核心。 **注意** Secrets Manager 是一项可用于在 AWS Cloud中安全存储和管理您的凭证、键和其他密钥的服务。有关更多信息，请参阅[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 在《*AWS Secrets Manager 用户指南》*中。 每个密钥必须包含以下键： | 键 | 值 | | --- | --- | | `username` | 用于访问存储库或镜像仓库的用户名。 | | `password` | 用于访问存储库或镜像仓库的密码。 | | `registryUrl` | 镜像仓库的终端节点。这必须与 Compose 文件中相应的镜像仓库 URL 匹配。 | **注意** 要在默认情况下允许 AWS IoT Greengrass 访问密钥，该密钥的名称必须以 *greengr* ass-开头。否则，您的 Greengrass 服务角色必须授予访问权限。有关更多信息，请参阅 [允许 AWS IoT Greengrass 获取秘密值](secrets.md#secrets-config-service-role)。 **从 AWS Marketplace获取 Docker 镜像的登录信息** 1. 使用`aws ecr get-login-password`命令从中 AWS Marketplace 获取 Docker 镜像的密码。有关更多信息，请参阅《AWS CLI 命令参考》**中的 [get-login-password](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html)。 ``` aws ecr get-login-password ``` 1. 检索 Docker 映像的注册表 URL。打开 AWS Marketplace 网站，然后打开容器产品启动页面。在**容器映像**下，选择**查看容器映像详细信息**以找到用户名和注册表 URL。 使用检索到的用户名、密码和注册表 URL 为每个存储您的 Compose 文件中引用的 Docker 映像的 AWS Marketplace 注册表创建一个密钥。 **创建密钥（控制台）** 在 AWS Secrets Manager 控制台中，选择**其他类型的密钥**。在 **Specify the key-value pairs to be stored for this secret (指定要为此密钥存储的键值对)** 下，添加针对 `username`、`password` 和 `registryUrl` 的行。有关更多信息，请参阅 *AWS Secrets Manager 用户指南*中的[创建基本密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 ![\[使用用户名、密码和镜像仓库 URL 键创建密钥。\]](http://docs.aws.amazon.com/zh_cn/greengrass/v1/developerguide/images/connectors/secret-docker-trusted-registry.png) **创建密钥 (CLI)** 在中 AWS CLI，使用 Secrets Manager `create-secret` 命令，如以下示例所示。有关更多信息，请参阅 *AWS CLI 命令参考*中的 [create-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html)。 ``` aws secretsmanager create-secret --name greengrass-MySecret --secret-string [{"username":"Mary_Major"},{"password":"abc123xyz456"},{"registryUrl":"https://docker.io"}] ``` **重要** 您有责任保护用于存储 Docker Compose 文件的`DockerComposeFileDestinationPath`目录以及来自私有存储库的 Docker 镜像的凭证。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 ## 参数 该连接器提供以下参数： ------ #### [ Version 7 ] `DockerComposeFileS3Bucket` 包含您的 Docker Compose 文件的 S3 存储桶的名称。创建桶时，请务必遵守《*亚马逊简单存储服务用户指南*》中描述的[桶名称规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 控制台中显示名称：S3 中的 **Docker 撰写文件** 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`false` 类型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 `DockerUserId` 指定的用户必须具有在此目录中创建文件的权限。有关更多信息，请参阅 [在核心上设置 Docker 用户 AWS IoT Greengrass](#docker-app-connector-linux-user)。 此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 AWS IoT 控制台中的显示名称：本**地 Compose 文件的目录路径** 必需：`true` 类型：`string` 有效模式 `\/.*\/?` 示例：`/home/username/myCompose` `DockerUserId` 连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 `docker` Linux 组，并且具有对 `DockerComposeFileDestinationPath` 目录的写入权限。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 AWS IoT 控制台中的显示名称：**Docker 用户 ID** 必需：`false` 类型：`string` 有效模式：`^[0-9]{1,5}$` `AWSSecretsArnList` 中密钥的 Amazon 资源名称 (ARNs) AWS Secrets Manager ，其中包含用于访问私有存储库中的 Docker 镜像的登录信息。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 AWS IoT 控制台中的显示名称：**私有仓库的凭证** 必需：`false`。此参数是访问存储在私有存储库中的 Docker 映像所必需的。 类型：`string` 的 `array` 有效模式：`[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]` `DockerContainerStatusLogFrequency` 连接器记录有关在核心上运行的 Docker 容器的状态信息的频率（以秒为单位）。默认值为 300 秒（5 分钟）。 AWS IoT 控制台中的显示名称：**记录频率** 必需：`false` 类型：`string` 有效模式：`^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指示如果 Docker 部署由于上次部署的清理不当而失败，是否强制执行此 Docker 部署。默认值为 `False`。 AWS IoT 控制台中的显示名称：**强制部署** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `DockerPullBeforeUp` 表示部署程序是否应`docker-compose pull`在运行 pull-down-up行为之前运行`docker-compose up`。默认值为 `True`。 AWS IoT 控制台中的显示名称：**Docker Pull Before Up** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `StopContainersOnNewDeployment` 指示在 GGC 停止时（部署新组或内核关闭时 GGC 会停止），连接器是否应停止 Docker Deployer 托管的 Docker 容器。默认值为 `True`。 在 AWS IoT 控制台中显示名称：**Docker 在新部署时停止** 我们建议将此参数设置为其默认值 `True`。参数将`False`使您的 Docker 容器即使在终止 AWS IoT Greengrass 核心或开始新部署后仍能继续运行。如果将此参数设置为 `False`，则必须确保在 `docker-compose` 服务名称变化或增加时根据需要维护您的 Docker 容器。 有关更多信息，请参阅 `docker-compose` Compose 文件文档。 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `DockerOfflineMode` 指示当 AWS IoT Greengrass 离线启动时是否使用现有的 Docker Compose 文件。默认值为 `False`。 必需：`false` 类型：`string` 有效模式：`^(true|false)$` ------ #### [ Version 6 ] `DockerComposeFileS3Bucket` 包含您的 Docker Compose 文件的 S3 存储桶的名称。创建桶时，请务必遵守《*亚马逊简单存储服务用户指南*》中描述的[桶名称规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 控制台中显示名称：S3 中的 **Docker 撰写文件** 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`false` 类型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 `DockerUserId` 指定的用户必须具有在此目录中创建文件的权限。有关更多信息，请参阅 [在核心上设置 Docker 用户 AWS IoT Greengrass](#docker-app-connector-linux-user)。 此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 AWS IoT 控制台中的显示名称：本**地 Compose 文件的目录路径** 必需：`true` 类型：`string` 有效模式 `\/.*\/?` 示例：`/home/username/myCompose` `DockerUserId` 连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 `docker` Linux 组，并且具有对 `DockerComposeFileDestinationPath` 目录的写入权限。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 AWS IoT 控制台中的显示名称：**Docker 用户 ID** 必需：`false` 类型：`string` 有效模式：`^[0-9]{1,5}$` `AWSSecretsArnList` 中密钥的 Amazon 资源名称 (ARNs) AWS Secrets Manager ，其中包含用于访问私有存储库中的 Docker 镜像的登录信息。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 AWS IoT 控制台中的显示名称：**私有仓库的凭证** 必需：`false`。此参数是访问存储在私有存储库中的 Docker 映像所必需的。 类型：`string` 的 `array` 有效模式：`[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]` `DockerContainerStatusLogFrequency` 连接器记录有关在核心上运行的 Docker 容器的状态信息的频率（以秒为单位）。默认值为 300 秒（5 分钟）。 AWS IoT 控制台中的显示名称：**记录频率** 必需：`false` 类型：`string` 有效模式：`^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指示如果 Docker 部署由于上次部署的清理不当而失败，是否强制执行此 Docker 部署。默认值为 `False`。 AWS IoT 控制台中的显示名称：**强制部署** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `DockerPullBeforeUp` 表示部署程序是否应`docker-compose pull`在运行 pull-down-up行为之前运行`docker-compose up`。默认值为 `True`。 AWS IoT 控制台中的显示名称：**Docker Pull Before Up** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `StopContainersOnNewDeployment` 指示在 GGC 停止时（部署新的组或关闭内核时 GGC 会停止），连接器是否应停止 Docker Deployer 托管的 Docker 容器。默认值为 `True`。 在 AWS IoT 控制台中显示名称：**Docker 在新部署时停止** 我们建议将此参数设置为其默认值 `True`。参数将`False`使您的 Docker 容器即使在终止 AWS IoT Greengrass 核心或开始新部署后仍能继续运行。如果将此参数设置为 `False`，则必须确保在 `docker-compose` 服务名称变化或增加时根据需要维护您的 Docker 容器。 有关更多信息，请参阅 `docker-compose` Compose 文件文档。 必需：`false` 类型：`string` 有效模式：`^(true|false)$` ------ #### [ Version 5 ] `DockerComposeFileS3Bucket` 包含您的 Docker Compose 文件的 S3 存储桶的名称。创建桶时，请务必遵守《*亚马逊简单存储服务用户指南*》中描述的[桶名称规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 控制台中显示名称：S3 中的 **Docker 撰写文件** 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`false` 类型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 `DockerUserId` 指定的用户必须具有在此目录中创建文件的权限。有关更多信息，请参阅 [在核心上设置 Docker 用户 AWS IoT Greengrass](#docker-app-connector-linux-user)。 此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 AWS IoT 控制台中的显示名称：本**地 Compose 文件的目录路径** 必需：`true` 类型：`string` 有效模式 `\/.*\/?` 示例：`/home/username/myCompose` `DockerUserId` 连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 `docker` Linux 组，并且具有对 `DockerComposeFileDestinationPath` 目录的写入权限。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 AWS IoT 控制台中的显示名称：**Docker 用户 ID** 必需：`false` 类型：`string` 有效模式：`^[0-9]{1,5}$` `AWSSecretsArnList` 中密钥的 Amazon 资源名称 (ARNs) AWS Secrets Manager ，其中包含用于访问私有存储库中的 Docker 镜像的登录信息。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 AWS IoT 控制台中的显示名称：**私有仓库的凭证** 必需：`false`。此参数是访问存储在私有存储库中的 Docker 映像所必需的。 类型：`string` 的 `array` 有效模式：`[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]` `DockerContainerStatusLogFrequency` 连接器记录有关在核心上运行的 Docker 容器的状态信息的频率（以秒为单位）。默认值为 300 秒（5 分钟）。 AWS IoT 控制台中的显示名称：**记录频率** 必需：`false` 类型：`string` 有效模式：`^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指示如果 Docker 部署由于上次部署的清理不当而失败，是否强制执行此 Docker 部署。默认值为 `False`。 AWS IoT 控制台中的显示名称：**强制部署** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` `DockerPullBeforeUp` 表示部署程序是否应`docker-compose pull`在运行 pull-down-up行为之前运行`docker-compose up`。默认值为 `True`。 AWS IoT 控制台中的显示名称：**Docker Pull Before Up** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` ------ #### [ Versions 2 - 4 ] `DockerComposeFileS3Bucket` 包含您的 Docker Compose 文件的 S3 存储桶的名称。创建桶时，请务必遵守《*亚马逊简单存储服务用户指南*》中描述的[桶名称规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 控制台中显示名称：S3 中的 **Docker 撰写文件** 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`false` 类型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 `DockerUserId` 指定的用户必须具有在此目录中创建文件的权限。有关更多信息，请参阅 [在核心上设置 Docker 用户 AWS IoT Greengrass](#docker-app-connector-linux-user)。 此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 AWS IoT 控制台中的显示名称：本**地 Compose 文件的目录路径** 必需：`true` 类型：`string` 有效模式 `\/.*\/?` 示例：`/home/username/myCompose` `DockerUserId` 连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 `docker` Linux 组，并且具有对 `DockerComposeFileDestinationPath` 目录的写入权限。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 AWS IoT 控制台中的显示名称：**Docker 用户 ID** 必需：`false` 类型：`string` 有效模式：`^[0-9]{1,5}$` `AWSSecretsArnList` 中密钥的 Amazon 资源名称 (ARNs) AWS Secrets Manager ，其中包含用于访问私有存储库中的 Docker 镜像的登录信息。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 AWS IoT 控制台中的显示名称：**私有仓库的凭证** 必需：`false`。此参数是访问存储在私有存储库中的 Docker 映像所必需的。 类型：`string` 的 `array` 有效模式：`[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]` `DockerContainerStatusLogFrequency` 连接器记录有关在核心上运行的 Docker 容器的状态信息的频率（以秒为单位）。默认值为 300 秒（5 分钟）。 AWS IoT 控制台中的显示名称：**记录频率** 必需：`false` 类型：`string` 有效模式：`^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指示如果 Docker 部署由于上次部署的清理不当而失败，是否强制执行此 Docker 部署。默认值为 `False`。 AWS IoT 控制台中的显示名称：**强制部署** 必需：`false` 类型：`string` 有效模式：`^(true|false)$` ------ #### [ Version 1 ] `DockerComposeFileS3Bucket` 包含您的 Docker Compose 文件的 S3 存储桶的名称。创建桶时，请务必遵守《*亚马逊简单存储服务用户指南*》中描述的[桶名称规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 控制台中显示名称：S3 中的 **Docker 撰写文件** 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[对象键和元数据](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`true` 类型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息（包括对象键命名指南），请参阅 *Amazon Simple Storage Service 用户指南*中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在控制台中，**Docker Compose file in S3 (S3 中的 Docker Compose 文件)** 属性结合了 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 参数。 必需：`false` 类型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 `DockerUserId` 指定的用户必须具有在此目录中创建文件的权限。有关更多信息，请参阅 [在核心上设置 Docker 用户 AWS IoT Greengrass](#docker-app-connector-linux-user)。 此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息，请参阅 [安全说明](#docker-app-connector-security)。 AWS IoT 控制台中的显示名称：本**地 Compose 文件的目录路径** 必需：`true` 类型：`string` 有效模式 `\/.*\/?` 示例：`/home/username/myCompose` `DockerUserId` 连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 `docker` Linux 组，并且具有对 `DockerComposeFileDestinationPath` 目录的写入权限。有关更多信息，请参阅 [在核心上设置 Docker 用户](#docker-app-connector-linux-user)。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 AWS IoT 控制台中的显示名称：**Docker 用户 ID** 必需：`false` 类型：`string` 有效模式：`^[0-9]{1,5}$` `AWSSecretsArnList` 中密钥的 Amazon 资源名称 (ARNs) AWS Secrets Manager ，其中包含用于访问私有存储库中的 Docker 镜像的登录信息。有关更多信息，请参阅 [从私有存储库访问 Docker 镜像](#access-private-repositories)。 AWS IoT 控制台中的显示名称：**私有仓库的凭证** 必需：`false`。此参数是访问存储在私有存储库中的 Docker 映像所必需的。 类型：`string` 的 `array` 有效模式：`[( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]` `DockerContainerStatusLogFrequency` 连接器记录有关在核心上运行的 Docker 容器的状态信息的频率（以秒为单位）。默认值为 300 秒（5 分钟）。 AWS IoT 控制台中的显示名称：**记录频率** 必需：`false` 类型：`string` 有效模式：`^[1-9]{1}[0-9]{0,3}$` ------ ### 创建连接器示例 (AWS CLI) 以下 CLI 命令创建一个 `ConnectorDefinition`，其初始版本包含 Greengrass Docker 应用程序部署连接器。 ``` aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyDockerAppplicationDeploymentConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5", "Parameters": { "DockerComposeFileS3Bucket": "amzn-s3-demo-bucket", "DockerComposeFileS3Key": "production-docker-compose.yml", "DockerComposeFileS3Version": "123", "DockerComposeFileDestinationPath": "/home/username/myCompose", "DockerUserId": "1000", "AWSSecretsArnList": "[\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret1-hash\",\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret2-hash\"]", "DockerContainerStatusLogFrequency": "30", "ForceDeploy": "True", "DockerPullBeforeUp": "True" } } ] }' ``` **注意** 此连接器中的 Lambda 函数的生命周期[很长](lambda-functions.md#lambda-lifecycle)。 ## 输入数据 此连接器不需要或接受输入数据。 ## 输出数据 此连接器将 `docker-compose up` 命令的状态发布为输出数据。 **订阅中的主题筛选条件** `dockerapplicationdeploymentconnector/message/status` **示例输出：成功** ``` { "status":"success", "GreengrassDockerApplicationDeploymentStatus":"Successfully triggered docker-compose up", "S3Bucket":"amzn-s3-demo-bucket", "ComposeFileName":"production-docker-compose.yml", "ComposeFileVersion":"123" } ``` **示例输出：失败** ``` { "status":"fail", "error_message":"description of error", "error":"InvalidParameter" } ``` 错误类型可以是 `InvalidParameter` 或 `InternalError`。 ## 在核心上设置 Docker 用户 AWS IoT Greengrass Greengrass Docker 应用程序部署连接器以您为 `DockerUserId` 参数指定的用户的身份运行。如果不指定值，则连接器将以 `ggc_user` 身份运行，这是默认的 Greengrass 访问标识。 要允许连接器与 Docker 守护程序交互，Docker 用户必须属于核心上的 `docker` Linux 组。Docker 用户还必须具有对 `DockerComposeFileDestinationPath` 目录的写入权限。这是连接器存储本地 `docker-compose.yml` 文件和 Docker 凭证的位置。 **注意** 我们建议您创建 Linux 用户，而不是使用默认 `ggc_user`。否则，Greengrass 组中的任何 Lambda 函数都可以访问 Compose 文件和 Docker 凭证。 除非绝对有必要，否则建议避免以根用户身份运行。如果您确实指定了 根用户，则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass 核心上运行。有关更多信息，请参阅 [以根用户身份运行 Lambda 函数](lambda-group-config.md#lambda-running-as-root)。 1. 创建 用户。您可以运行 `useradd` 命令并包含用于分配 UID 的可选 `-u` 选项。例如： ``` sudo useradd -u 1234 user-name ``` 1. 将用户添加到核心上的 `docker` 组。例如： ``` sudo usermod -aG docker user-name ``` 有关详细信息，包括如何创建 `docker` 组，请参阅 Docker 文档中的[以非 root 用户身份管理 Docker](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user)。 1. 授予用户写入为 `DockerComposeFileDestinationPath` 参数指定的目录的权限。例如： 1. 将用户设置为目录的所有者。此示例使用步骤 1 中的 UID。 ``` chown 1234 docker-compose-file-destination-path ``` 1. 为所有者授予读写权限。 ``` chmod 700 docker-compose-file-destination-path ``` 有关详细信息，请参阅 Linux Foundation 文档中的[如何在 Linux 中管理文件和文件夹权限](https://www.linux.com/tutorials/how-manage-file-and-folder-permissions-linux/)。 1. 如果您在创建用户时没有分配 UID，或者使用现有用户，请运行 `id` 命令查找 UID。 ``` id -u user-name ``` 您可以使用 UID 配置连接器的 `DockerUserId` 参数。 ## 使用情况信息 当您使用 Greengrass Docker 应用程序部署连接器时，您应该注意以下特定于实现的使用信息。 + **项目名称的固定前缀。**连接器将 `greengrassdockerapplicationdeployment` 前缀附加到其启动的 Docker 容器的名称前面。连接器在它所运行的 `docker-compose` 命令中使用此前缀作为项目名称。 + **日志记录行为。**连接器将状态信息和疑难解答信息写入日志文件。您可以配置为将日志发送 AWS IoT Greengrass 到 CloudWatch 日志并在本地写入日志。有关更多信息，请参阅 [连接器的日志记录](connectors.md#connectors-logging)。这是连接器的本地日志的路径： ``` /greengrass-root/ggc/var/log/user/region/aws/DockerApplicationDeployment.log ``` 您必须具有 root 权限才能访问本地日志。 + **更新 Docker 映像。**Docker 在核心设备上缓存镜像。如果您更新 Docker 镜像并希望将更改传播到核心设备，请确保更改 Compose 文件中镜像的标签。更改将在部署 Greengrass 组后生效。 + **清理操作的 10 分钟超时。**当 Greengrass 守护程序（在重新启动期间）停止时，将启动该 `docker-compose down` 命令。所有 Docker 容器在启动 `docker-compose down` 后最多具有 10 分钟以执行任何清理操作。如果清理在 10 分钟内未完成，则必须手动清理剩余的容器。有关更多信息，请参阅 Docker CLI 文档中的 [docker rm](https://docs.docker.com/engine/reference/commandline/rm/)。 + **运行 Docker 命令。**要解决问题，您可以在核心设备上的终端窗口中运行 Docker 命令。例如，运行以下命令以查看由连接器启动的 Docker 容器： ``` docker ps --filter name="greengrassdockerapplicationdeployment" ``` + **保留资源 ID。**连接器使用它在 Greengrass 组中创建的 Greengrass 资源的 `DOCKER_DEPLOYER_SECRET_RESOURCE_RESERVED_ID_index` ID。资源在组中 IDs必须是唯一的，因此不要分配可能与该预留资源 ID 冲突的资源 ID。 + **离线模式。**将 `DockerOfflineMode` 配置参数设置为 `True` 时，Docker 连接器就可以在*离线模式*下运行。如果 Greengrass 组部署在核心设备离线时重新启动，并且连接器无法建立到 Amazon S3 或 Amazon ECR 的连接以检索 Docker 合成文件，此时可能会发生这种情况。 启用离线模式后，连接器将尝试下载合成文件，并像正常重新启动一样运行 `docker login` 命令。如果这些尝试失败，则连接器会在使用 `DockerComposeFileDestinationPath` 参数指定的文件夹中查找本地存储的 Compose 文件。如果存在本地 Compose 文件，则连接器会遵循正常的 `docker-compose` 命令顺序并从本地映像中提取。如果 Compose 文件或本地映像不存在，则连接器将失败。在离线模式下，`ForceDeploy` 和 `StopContainersOnNewDeployment` 参数的行为保持不变。 ## 与 Docker 容器通信 AWS IoT Greengrass 支持 Greengrass 组件和 Docker 容器之间的以下通信渠道： + Greengrass Lambda 函数可以使用 R APIs EST 与 Docker 容器中的进程进行通信。可以在打开端口的 Docker 容器中设置服务器。Lambda 函数可以使用该端口与容器通信。 + Docker 容器中的进程可以通过本地 Greengrass 消息代理交换 MQTT 消息。您可以在 Greengrass 组中将 Docker 容器设置为客户端设备，然后创建订阅以允许该容器与 Greengrass Lambda 函数、客户端设备和组中的其他连接器通信，或者与本地影子服务通信。 AWS IoT 有关更多信息，请参阅 [配置 MQTT 与 Docker 容器的通信](#docker-app-connector-mqtt-communication)。 + Greengrass Lambda 函数可以更新共享文件以将信息传递给 Docker 容器。您可以使用 Compose 文件绑定装载 Docker 容器的共享文件路径。 ### 配置 MQTT 与 Docker 容器的通信 您可以将 Docker 容器配置为客户端设备，并将其添加到 Greengrass 组中。然后，您可以创建允许在 Docker 容器和 Greengrass 组件或 AWS IoT之间进行 MQTT 通信的订阅。在以下过程中，您将创建允许 Docker 容器设备从本地影子服务接收影子更新消息的订阅。您可以按照此模式创建其他订阅。 **注意** 此过程假设您已经创建了 Greengrass 组和 Greengrass 核心 (v1.10 或更高版本)。有关创建 Greengrass 组和核心的信息，请参阅 [入门 AWS IoT Greengrass](gg-gs.md)。 **将 Docker 容器配置为客户端设备并将其添加到 Greengrass 组** 1. 在核心设备上创建一个文件夹，以存储用于对 Greengrass 设备进行身份验证的证书和密钥。 文件路径必须装载在要启动的 Docker 容器上。以下代码段显示如何在您的 Compose 文件中装载文件路径。在此示例中，*path-to-device-certs*表示您在此步骤中创建的文件夹。 ``` version: '3.3' services: myService: image: user-name/repo:image-tag volumes: - /path-to-device-certs/:/path-accessible-in-container ``` 1. **在 AWS IoT 控制台导航窗格的**管理**下，展开 **Greengrass** 设备，然后选择群组 (V1)。** 1. 选择目标组。 1. 在组配置页面中，选择**客户端设备**，然后选择**关联**。 1. 在 “将**客户端设备与此群组关联**” 模式中，选择 “**创建新 AWS IoT 事物**”。 此时将在新选项卡中打开**创建事物**页面。 1. 在 **创建事物**页面上，选择 **创建单个事物**，然后选择 **下一步**。 1. 在**指定事物属性**页面上，输入设备的名称，然后选择**下一步**。 1. 在**配置设备证书**页面上，选择**下一步**。 1. 在 **将策略附加到证书** 页面上，执行下列操作之一： + 选择授予客户端设备所需权限的现有策略，然后选择**创建事物**。 将打开一个模式，您可以在其中下载设备用于连接和核心的证书 AWS Cloud 和密钥。 + 创建并附加授予客户端设备权限的新策略。执行以下操作： 1. 选择**创建策略**。 此时将在新选项卡中打开**创建策略**页面。 1. 在**创建策略**页面上，执行以下操作： 1. 在**策略名称**中，输入一个名称来描述该策略，例如 **GreengrassV1ClientDevicePolicy**。 1. 在**策略语句**选项卡的**策略文档**下，选择 **JSON**。 1. 输入以下策略文档。此策略允许客户端设备发现 Greengrass 核心并就所有 MQTT 主题进行通信。有关如何限制此策略访问权限的信息，请参阅[设备身份验证和授权 AWS IoT Greengrass](device-auth.md)。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Subscribe", "iot:Connect", "iot:Receive" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "greengrass:*" ], "Resource": [ "*" ] } ] } ``` ------ 1. 选择 **Create**（创建）以创建策略。 1. 返回到打开了**将策略附加到证书**页面的浏览器标签页中。执行以下操作： 1. 在**策略**列表中，选择您创建的策略，例如 **GreengrassV1ClientDevicePolicy**。 如果没有看到策略，请选择刷新按钮。 1. 选择 **Create thing**（创建事物）。 将打开一个模式，您可以在其中下载设备用于连接和核心的证书 AWS Cloud 和密钥。 1. 在**下载证书和密钥**模态中，下载设备的证书。 **重要** 请先下载安全资源，然后再选择 **完成**。 执行以下操作： 1. 在**设备证书**中，选择**下载**以下载该设备证书。 1. 在**公钥文件**中，选择**下载**以下载该证书的公钥。 1. 在**私钥文件**中，选择**下载**以下载该证书的私钥文件。 1. 查看*AWS IoT 开发人员指南*中的[服务器身份验证](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html)，然后选择相应的根 CA 证书。我们建议您使用 Amazon Trust Services (ATS) 端点和 ATS 根 CA 证书。在**根 CA 证书**下，针对根 CA 证书选择**下载**。 1. 选择**完成**。 记下设备证书和密钥文件名中常见的证书 ID。稍后您将需要用到它。 1. 将证书和密钥复制到您在步骤 1 中创建的文件夹。 接下来，在组中创建订阅。对于此示例，您创建一个订阅，以允许 Docker 容器设备从本地影子服务接收 MQTT 消息。 **注意** 影子文档的最大大小为 8 KB。有关更多信息，请参阅《AWS IoT 开发人员指南》**中的 [AWS IoT 配额](https://docs.aws.amazon.com/iot/latest/developerguide/limits-iot.html)。 **创建允许 Docker 容器设备从本地影子服务接收 MQTT 消息的订阅。** 1. 在组配置页面中，选择**订阅**选项卡，然后选择**添加订阅**。 1. 在**选择您的源和目标**页面，配置源和目标，如下所示： 1. 对于**选择源**，选择**服务**，然后选择**本地影子服务**。 1. 对于 **Select a target (选择目标)**，选择 **Devices (设备)**，然后选择您的设备。 1. 选择**下一步**。 1. 在 **利用主题筛选您的数据** 页面上，对于 **主题筛选条件**，选择 **\$1aws/things/*MyDockerDevice*/shadow/update/accepted**，然后选择**下一步**。*MyDockerDevice*替换为您之前创建的设备的名称。 1. 选择**结束**。 在您的 Compose 文件中引用的 Docker 镜像中包含以下代码段。这是 Greengrass 设备代码。此外，在 Docker 容器中添加代码，以启动容器内的 Greengrass 设备。它可以作为一个单独的进程在镜像或单独的线程中运行。 ``` import os import sys import time import uuid from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider from AWSIoTPythonSDK.exception.AWSIoTExceptions import DiscoveryInvalidRequestException from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTClient # Replace thingName with the name you registered for the Docker device. thingName = "MyDockerDevice" clientId = thingName # Replace host with the IoT endpoint for your &AWS-account;. host = "myPrefix.iot.region.amazonaws.com" # Replace topic with the topic where the Docker container subscribes. topic = "$aws/things/MyDockerDevice/shadow/update/accepted" # Replace these paths based on the download location of the certificates for the Docker container. rootCAPath = "/path-accessible-in-container/AmazonRootCA1.pem" certificatePath = "/path-accessible-in-container/certId-certificate.pem.crt" privateKeyPath = "/path-accessible-in-container/certId-private.pem.key" # Discover Greengrass cores. discoveryInfoProvider = DiscoveryInfoProvider() discoveryInfoProvider.configureEndpoint(host) discoveryInfoProvider.configureCredentials(rootCAPath, certificatePath, privateKeyPath) discoveryInfoProvider.configureTimeout(10) # 10 seconds. GROUP_CA_PATH = "./groupCA/" MQTT_QOS = 1 discovered = False groupCA = None coreInfo = None try: # Get discovery info from AWS IoT. discoveryInfo = discoveryInfoProvider.discover(thingName) caList = discoveryInfo.getAllCas() coreList = discoveryInfo.getAllCores() # Use first discovery result. groupId, ca = caList[0] coreInfo = coreList[0] # Save the group CA to a local file. groupCA = GROUP_CA_PATH + groupId + "_CA_" + str(uuid.uuid4()) + ".crt" if not os.path.exists(GROUP_CA_PATH): os.makedirs(GROUP_CA_PATH) groupCAFile = open(groupCA, "w") groupCAFile.write(ca) groupCAFile.close() discovered = True except DiscoveryInvalidRequestException as e: print("Invalid discovery request detected!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) print("Stopping...") except BaseException as e: print("Error in discovery!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) print("Stopping...") myAWSIoTMQTTClient = AWSIoTMQTTClient(clientId) myAWSIoTMQTTClient.configureCredentials(groupCA, privateKeyPath, certificatePath) # Try to connect to the Greengrass core. connected = False for connectivityInfo in coreInfo.connectivityInfoList: currentHost = connectivityInfo.host currentPort = connectivityInfo.port myAWSIoTMQTTClient.configureEndpoint(currentHost, currentPort) try: myAWSIoTMQTTClient.connect() connected = True except BaseException as e: print("Error in connect!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) if connected: break if not connected: print("Cannot connect to core %s. Exiting..." % coreInfo.coreThingArn) sys.exit(-2) # Handle the MQTT message received from GGShadowService. def customCallback(client, userdata, message): print("Received an MQTT message") print(message) # Subscribe to the MQTT topic. myAWSIoTMQTTClient.subscribe(topic, MQTT_QOS, customCallback) # Keep the process alive to listen for messages. while True: time.sleep(1) ``` ## 安全说明 使用 Greengrass Docker 应用程序部署连接器时，请注意以下安全注意事项。 **Docker Compose 文件的本地存储** 连接器将 Compose 文件的副本存储在为 `DockerComposeFileDestinationPath` 参数指定的目录中。 您负责确保此目录安全。您应该使用文件系统权限来限制对目录的访问。 **Docker 凭证的本地存储** 如果 Docker 镜像存储在私有存储库中，则连接器将 Docker 凭证存储在为 `DockerComposeFileDestinationPath` 参数指定的目录中。 您负责保护这些证书。例如，在安装 Docker Engine 时，应在核心设备上使用 [credential-helper](https://docs.docker.com/engine/reference/commandline/login/#credentials-store)。 **从可信来源安装 Docker Engine** 您负责从可信来源安装 Docker Engine。此连接器使用核心设备上的 Docker 守护程序访问您的 Docker 资产并管理 Docker 容器。 **Greengrass 组角色权限的范围** 在 Greengrass 组角色中添加的权限可由 Greengrass 组中的所有 Lambda 函数和连接器代入。此连接器需要访问存储在 S3 存储桶中的 Docker Compose 文件。如果您的 Docker 镜像存储在 Amazon ECR 中的私有存储库中，它还需要访问您的 Amazon ECR 授权令牌。 ## 许可证 Greengrass Docker 应用程序部署连接器包含以下第三方软件/许可： + [适用于 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache 许可证 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache 许可证 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF 许可证 + [docutils](https://pypi.org/project/docutils/)/BSD 许可证，GNU 通用公共许可证 (GPL)，Python 软件基金会许可证，公共领域 + [jmespath](https://pypi.org/project/jmespath/)/MIT 许可证 + [s3transfer](https://pypi.org/project/s3transfer/)/Apache 许可证 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT 许可证 该连接器在 [Greengrass Core 软件许可协议](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)下发布。 ## 更改日志 下表介绍每个版本连接器的更改。 | 版本 | 更改 | | --- | --- | | 7 | 添加了`DockerOfflineMode`在离线 AWS IoT Greengrass 启动时使用现有的 Docker Compose 文件。为 `docker login` 命令实现了重试。Support 支持 32 位 UIDs。 | | 6 | 增加了 `StopContainersOnNewDeployment`，用于在进行新部署或 GGC 停止时覆盖容器清理。更安全的关机和启动机制。YAML 验证错误修复。 | | 5 | 在运行 `docker-compose down` 之前先提取映像。 | | 4 | 添加了更新 Docker 镜像的 pull-before-up行为。 | | 3 | 修复了查找环境变量的问题。 | | 2 | 添加了 `ForceDeploy` 参数。 | | 1 | 初始版本。 | Greengrass 组在一个时间上只能包含一个版本的连接器。有关升级连接器版本的信息，请参阅[升级连接器版本](connectors.md#upgrade-connector-versions)。 ## 另请参阅 + [使用 Greengrass 连接器与服务和协议集成](connectors.md) + [Greengrass 连接器入门（控制台）](connectors-console.md) + [Greengrass 连接器入门 (CLI)](connectors-cli.md)