Docker 应用程序部署连接器 - AWS IoT Greengrass
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Docker 应用程序部署连接器

Greengrass Docker 应用程序部署 连接器使得在 AWS IoT Greengrass Core 上运行 Docker 镜像更容易。连接器使用 Docker Compose 从 docker-compose.yml 文件启动多容器 Docker 应用程序。具体而言,连接器运行 docker-compose 命令来管理单个核心设备上的 Docker 容器。有关详细信息,请参阅 Docker 文档中的 Docker Compose 概述 。连接器可以访问存储在 Docker 容器镜像仓库中的 Docker 镜像,如 Amazon Elastic Container Registry (Amazon ECR)、Docker Hub 和私有 Docker 信任的镜像仓库。

部署Greengrass组后,连接器将提取最新的图像并启动Docker容器。它运行 docker-compose pulldocker-compose up 命令。然后,连接器将命令的状态发布到 输出MQTT主题. 它还记录有关运行 Docker 容器的状态信息。这使您可以监控 Amazon CloudWatch 中的应用程序日志。有关更多信息,请参阅利用 AWS IoT Greengrass 日志进行监控。连接器还会在每次 Greengrass 守护程序重新启动时启动 Docker 容器。可以在内核上运行的 Docker 容器数量取决于您的硬件。

Docker 容器在核心设备上的 Greengrass 域之外运行,因此它们无法访问核心的进程间通信 (IPC)。但是,您可以使用 Greengrass 组件配置某些通信通道,例如本地 Lambda 函数。有关更多信息,请参阅与 Docker 容器通信

您可以将连接器用于托管Web服务器或 MySQL 核心设备上的服务器。Docker 应用程序中的本地服务可以彼此、与本地环境中的其他进程以及云服务通信。例如,您可以在核心上运行 Web 服务器,将请求从 Lambda 函数发送到云中的 Web 服务。

此连接器在无容器隔离模式下运行,因此,您可以将其部署到在没有 Greengrass 容器化的情况下运行的 Greengrass 组。

此连接器具有以下版本。

版本

进行筛选

6

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/6

5

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/5

4

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/4

3

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/3

2

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/2

1

arn:aws:greengrass:区域::/connectors/DockerApplicationDeployment/versions/1

有关版本更改的信息,请参阅更改日志

要求

此连接器具有以下要求:

  • AWS IoT Greengrass Core 软件 v1.10 or later。

    注意

    此连接器在上不受支持 OpenWrt 分配。

  • Python 版本 3.7 已安装在核心设备上并且已添加到 PATH 环境变量。

  • Greengrass 内核上至少有 36 MB RAM,供连接器监控正在运行的 Docker 容器。总内存需求取决于在内核上运行的 Docker 容器的数量。

  • Greengrass 核心上安装的 Docker Engine 1.9.1 或更高版本。版本 19.0.3 是经验证可与连接器一起使用的最新版本。

    docker 可执行文件必须位于 /usr/bin/usr/local/bin 目录中。

    重要

    我们建议您安装凭证存储以保护 Docker 凭证的本地副本。有关更多信息,请参阅安全说明

    有关在AmazonLinux发行版上安装Docker的信息,请参阅 Docker基础知识 Amazon ECSAmazon Elastic Container Service Developer Guide.

  • Greengrass 核心上安装的 Docker Composedocker-compose 可执行文件必须位于 /usr/bin/usr/local/bin 目录中。

    以下 Docker Compose 版本经验证可与此连接器一起使用。

    连接器版本

    经验证的 Docker Compose 版本

    6

    1.25.4

    5

    1.25.4

    4

    1.25.4

    3

    1.25.4

    2

    1.25.1

    1

    1.24.1

  • 存储在 Amazon S3 中的单个 Docker 撰写文件(例如, docker-compose.yml)。格式必须与安装在核心上的 Docker Compose 版本兼容。在核心上使用文件之前,应先对其进行测试。如果在部署 Greengrass 组后编辑该文件,则必须重新部署该组以更新核心上的本地副本。

  • 有权调用本地 Docker 守护程序并写入存储 Compose 文件的本地副本的目录的 Linux 用户。有关更多信息,请参阅在 核心上设置 Docker 用户

  • Greengrass 组角色,配置为允许对包含 Compose 文件的 S3 存储桶执行 s3:GetObject 操作。此权限显示在以下示例 IAM 策略中。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToComposeFileS3Bucket", "Action": [ "s3:GetObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::bucket-name/*" } ] }

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

  • 如果您的 Docker Compose 文件引用 Amazon ECR 中存储的 Docker 映像,则为配置为允许执行以下操作的 Greengrass 组角色

    • 对包含 Docker 镜像的 Amazon ECR 存储库执行的 ecr:GetDownloadUrlForLayerecr:BatchGetImage 操作。

    • 对您的资源执行的 ecr:GetAuthorizationToken 操作。

    存储库必须与连接器位于同一 AWS 账户和 AWS 区域中。

    重要

    组角色中的权限可由 Greengrass 组中的所有 Lambda 函数和连接器代入。有关更多信息,请参阅安全说明

    以下示例策略中显示了这些权限。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowGetEcrRepositories", "Effect": "Allow", "Action": [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": [ "arn:aws:ecr:区域:account-id:repository/repository-name" ] }, { "Sid": "AllowGetEcrAuthToken", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" } ] }

    有关更多信息,请参阅 Amazon ECR 存储库策略示例Amazon ECR 用户指南.

    对于组角色要求,您必须将角色配置为授予所需权限,并确保角色已添加到组中。有关更多信息,请参阅管理 Greengrass 组角色(控制台)管理 Greengrass 组角色 (CLI)

  • 如果您的 Docker Compose 文件引用来自 AWS Marketplace 的 Docker 镜像,则连接器还具有以下要求:

    • 您必须订阅 AWS Marketplace 容器产品。有关更多信息,请参阅 查找和订阅集装箱产品AWS Marketplace 订阅用户指南.

    • AWS IoT Greengrass 必须配置为支持本地密钥,如密钥要求中所述。 连接器仅使用此功能从 AWS Secrets Manager 中检索您的密钥,而不存储它们。

    • 您必须在 Secrets Manager 中为用于存储在 Compose 文件中引用的 Docker 镜像的每个 AWS Marketplace 镜像仓库创建一个密钥。有关更多信息,请参阅从私有存储库访问 Docker 镜像

  • 如果您的 Docker Compose 文件从 Amazon ECR(如 Docker Hub)之外的镜像仓库中的私有存储库引用 Docker 镜像,则连接器还具有以下要求:

    • AWS IoT Greengrass 必须配置为支持本地密钥,如密钥要求中所述。 连接器仅使用此功能从 AWS Secrets Manager 中检索您的密钥,而不存储它们。

    • 您必须在 Secrets Manager 中为用于存储在 Compose 文件中引用的 Docker 镜像的每个私有存储库创建一个密钥。有关更多信息,请参阅从私有存储库访问 Docker 镜像

  • 当您部署包含此连接器的 Greengrass 组时,Docker 守护程序必须正在运行。

从私有存储库访问 Docker 镜像

如果您使用凭证问 Docker 镜像,则必须允许连接器访问它们。您执行此操作的方式取决于 Docker 镜像的位置。

对于 Amazon ECR 中存储的 Docker 镜像,您可以授予在 Greengrass 组角色中获取授权令牌的权限。有关更多信息,请参阅要求

对于存储在其他私有存储库或镜像仓库中的 Docker 镜像,您必须在 AWS Secrets Manager 中创建一个密钥来存储您的登录信息。这包括您在 AWS Marketplace 中订阅的 Docker 镜像。为每个存储库创建一个密钥。如果您在 Secrets Manager 中更新您的密钥,则更改会在下次部署组时传播到核心。

注意

Secrets Manager 是一项可用于在 AWS 云中安全存储和管理您的凭证、键和其他密钥的服务。有关更多信息,请参阅 中的什么是 ?。

每个密钥必须包含以下键:

Key

Value

username

用于访问存储库或镜像仓库的用户名。

password

用于访问存储库或镜像仓库的密码。

registryUrl

镜像仓库的终端节点。这必须与 Compose 文件中相应的镜像仓库 URL 匹配。

注意

要默认允许 AWS IoT Greengrass 访问密钥,密钥的名称必须以 greengrass- 开头。否则,您的 Greengrass 服务角色必须授予访问权限。有关更多信息,请参阅允许 AWS IoT Greengrass 获取密钥值

从获取Docker镜像的登录信息 AWS Marketplace

使用 aws ecr get-login 命令从 AWS Marketplace 中获取 Docker 镜像的用户名、密码和镜像仓库 URL。

aws ecr get-login --no-include-email --region 区域 --registry-ids registry-id
注意

您可以在 AWS Marketplace 网站上的容器产品启动页面上找到镜像仓库 ID。在 Container Images (容器镜像) 下,选择 View container image details (查看容器镜像详细信息)

输出包含用于创建密钥的登录信息。例如,在以下输出中,-u 值是用户名,-p 值是密码,镜像仓库 URL 是输出结尾处的 URL。

docker login -u AWS -p eyGuYXlsbGkxU0NveDNKaTY4ak...c0MzFyMTIxfQ== https://123456789012.dkr.ecr.区域.amazonaws.com

使用此登录信息为每个 AWS Marketplace 镜像仓库创建一个密钥,该镜像仓库存储您的 Compose 文件中引用的 Docker 镜像。有关更多信息,请参阅 登录AWS CLI Command Reference.

创建密钥(控制台)

在 AWS Secrets Manager 控制台中,选择其他密钥类型。低于 指定要为此密钥存储的键值对,添加行 username, password,和 registryUrl。有关更多信息,请参阅 创建基本密钥AWS Secrets Manager 用户指南.


                                使用用户名、密码和创建密钥 registryUrl 键。
创建密钥 (CLI)

在 AWS CLI 中,使用 Secrets Managercreate-secret 命令,如以下示例所示。有关更多信息,请参阅 创建-密钥AWS CLI Command Reference.

aws secretsmanager create-secret --name greengrass-MySecret --secret-string [{"username":"Mary_Major"},{"password":"abc123xyz456"},{"registryUrl":"https://docker.io"}]
重要

您有责任保护用于存储 Docker Compose 文件的DockerComposeFileDestinationPath目录以及来自私有存储库的 Docker 镜像的凭证。有关更多信息,请参阅安全说明

参数

该连接器提供以下参数:

Version 6
DockerComposeFileS3Bucket

包含您的 Docker Compose 文件的 S3 存储桶的名称。创建存储桶时,请确保遵循 https://docs.amazonaws.cn/AmazonS3/latest/dev/BucketRestrictions.html 中所述的Amazon Simple Storage Service 开发人员指南存储桶名称的规则

在 AWS IoT 控制台中显示名称: S3 中的 Docker Compose 文件

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/UsingMetadata.html 中的对象键和元数据Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 .+

DockerComposeFileS3Version

Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/Versioning.html 中的使用版本控制Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: false

类型: string

有效模式 .+

DockerComposeFileDestinationPath

用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 DockerUserId 指定的用户必须具有在此目录中创建文件的权限。有关更多信息,请参阅在 AWS IoT Greengrass 核心上设置 Docker 用户

重要

此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息,请参阅安全说明

在 AWS IoT 控制台中显示名称:本地 Compose 文件的目录路径

必需: true

类型: string

有效模式 \/.*\/?

示例:/home/username/myCompose

DockerUserId

连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 docker Linux 组,并且具有对 DockerComposeFileDestinationPath 目录的写入权限。有关更多信息,请参阅在 核心上设置 Docker 用户

注意

除非绝对有必要,否则建议避免以根用户身份运行。如果您确实指定了 root 用户,则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass Core 上运行。有关更多信息,请参阅以根用户身份运行 Lambda 函数

在 AWS IoT 控制台中显示名称:Docker 用户 ID

必需: false

类型: string

有效模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中的密钥的 Amazon 资源名称 (ARN),其中包含用于访问私有存储库中 Docker 映像的登录信息。有关更多信息,请参阅从私有存储库访问 Docker 镜像

在 AWS IoT 控制台中显示名称:私有存储库的凭证

必需:false。 此参数是访问存储在私有存储库中的 Docker 映像所必需的。

类型:arraystring

有效模式: [( ?,? ?"(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 控制台中显示名称:Force deployment (强制部署)

必需: false

类型: string

有效模式: ^(true|false)$

DockerPullBeforeUp

指示部署者是否应运行 docker-compose pull 再运行 docker-compose up 下拉行为。默认值为 True

在 AWS IoT 控制台中显示名称: Docker上行前拉取

必需: false

类型: string

有效模式: ^(true|false)$

StopContainersOnNewDeployment

指示连接器是否在GGC停止时停止Docker部署器管理的Docker容器(当进行新组部署或内核关闭时)。默认值为 True

在 AWS IoT 控制台中显示名称: 新建部署时Docker停止

注意

我们建议将此参数保留为默认值 True 值。将此参数设置为 False 将使您的Docker容器即使在终止 AWS IoT Greengrass Core 或启动新部署。如果将此参数设置为 False时,必须确保在发生 docker-compose 服务名称更改或添加。

有关更多信息,请参阅 docker-compose 编制文件文档。

必需: false

类型: string

有效模式: ^(true|false)$

Version 5
DockerComposeFileS3Bucket

包含您的 Docker Compose 文件的 S3 存储桶的名称。创建存储桶时,请确保遵循 https://docs.amazonaws.cn/AmazonS3/latest/dev/BucketRestrictions.html 中所述的Amazon Simple Storage Service 开发人员指南存储桶名称的规则

在 AWS IoT 控制台中显示名称: S3 中的 Docker Compose 文件

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/UsingMetadata.html 中的对象键和元数据Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 .+

DockerComposeFileS3Version

Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/Versioning.html 中的使用版本控制Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: false

类型: string

有效模式 .+

DockerComposeFileDestinationPath

用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 DockerUserId 指定的用户必须具有在此目录中创建文件的权限。有关更多信息,请参阅在 AWS IoT Greengrass 核心上设置 Docker 用户

重要

此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息,请参阅安全说明

在 AWS IoT 控制台中显示名称:本地 Compose 文件的目录路径

必需: true

类型: string

有效模式 \/.*\/?

示例:/home/username/myCompose

DockerUserId

连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 docker Linux 组,并且具有对 DockerComposeFileDestinationPath 目录的写入权限。有关更多信息,请参阅在 核心上设置 Docker 用户

注意

除非绝对有必要,否则建议避免以根用户身份运行。如果您确实指定了 root 用户,则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass Core 上运行。有关更多信息,请参阅以根用户身份运行 Lambda 函数

在 AWS IoT 控制台中显示名称:Docker 用户 ID

必需: false

类型: string

有效模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中的密钥的 Amazon 资源名称 (ARN),其中包含用于访问私有存储库中 Docker 映像的登录信息。有关更多信息,请参阅从私有存储库访问 Docker 镜像

在 AWS IoT 控制台中显示名称:私有存储库的凭证

必需:false。 此参数是访问存储在私有存储库中的 Docker 映像所必需的。

类型:arraystring

有效模式: [( ?,? ?"(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 控制台中显示名称:Force deployment (强制部署)

必需: false

类型: string

有效模式: ^(true|false)$

DockerPullBeforeUp

指示部署者是否应运行 docker-compose pull 再运行 docker-compose up 下拉行为。默认值为 True

在 AWS IoT 控制台中显示名称: Docker上行前拉取

必需: false

类型: string

有效模式: ^(true|false)$

Versions 2 - 4
DockerComposeFileS3Bucket

包含您的 Docker Compose 文件的 S3 存储桶的名称。创建存储桶时,请确保遵循 https://docs.amazonaws.cn/AmazonS3/latest/dev/BucketRestrictions.html 中所述的Amazon Simple Storage Service 开发人员指南存储桶名称的规则

在 AWS IoT 控制台中显示名称: S3 中的 Docker Compose 文件

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/UsingMetadata.html 中的对象键和元数据Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 .+

DockerComposeFileS3Version

Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/Versioning.html 中的使用版本控制Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: false

类型: string

有效模式 .+

DockerComposeFileDestinationPath

用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 DockerUserId 指定的用户必须具有在此目录中创建文件的权限。有关更多信息,请参阅在 AWS IoT Greengrass 核心上设置 Docker 用户

重要

此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息,请参阅安全说明

在 AWS IoT 控制台中显示名称:本地 Compose 文件的目录路径

必需: true

类型: string

有效模式 \/.*\/?

示例:/home/username/myCompose

DockerUserId

连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 docker Linux 组,并且具有对 DockerComposeFileDestinationPath 目录的写入权限。有关更多信息,请参阅在 核心上设置 Docker 用户

注意

除非绝对有必要,否则建议避免以根用户身份运行。如果您确实指定了 root 用户,则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass Core 上运行。有关更多信息,请参阅以根用户身份运行 Lambda 函数

在 AWS IoT 控制台中显示名称:Docker 用户 ID

必需: false

类型: string

有效模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中的密钥的 Amazon 资源名称 (ARN),其中包含用于访问私有存储库中 Docker 映像的登录信息。有关更多信息,请参阅从私有存储库访问 Docker 镜像

在 AWS IoT 控制台中显示名称:私有存储库的凭证

必需:false。 此参数是访问存储在私有存储库中的 Docker 映像所必需的。

类型:arraystring

有效模式: [( ?,? ?"(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 控制台中显示名称:Force deployment (强制部署)

必需: false

类型: string

有效模式: ^(true|false)$

Version 1
DockerComposeFileS3Bucket

包含您的 Docker Compose 文件的 S3 存储桶的名称。创建存储桶时,请确保遵循 https://docs.amazonaws.cn/AmazonS3/latest/dev/BucketRestrictions.html 中所述的Amazon Simple Storage Service 开发人员指南存储桶名称的规则

在 AWS IoT 控制台中显示名称: S3 中的 Docker Compose 文件

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中的 Docker Compose 文件的对象密钥。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/UsingMetadata.html 中的对象键和元数据Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: true

类型: string

有效模式 .+

DockerComposeFileS3Version

Amazon S3 中的 Docker Compose 文件的对象版本。有关更多信息(包括对象键命名准则),请参阅 https://docs.amazonaws.cn/AmazonS3/latest/dev/Versioning.html 中的使用版本控制Amazon Simple Storage Service 开发人员指南。

注意

在控制台中,Docker Compose file in S3 (S3 中的 Docker Compose 文件) 属性结合了 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 参数。

必需: false

类型: string

有效模式 .+

DockerComposeFileDestinationPath

用于存储 Docker Compose 文件副本的本地目录的绝对路径。这必须是现有目录。为 DockerUserId 指定的用户必须具有在此目录中创建文件的权限。有关更多信息,请参阅在 AWS IoT Greengrass 核心上设置 Docker 用户

重要

此目录存储 Docker Compose 文件以及来自私有存储库 的 Docker 映像的凭证。您有责任确保此目录安全。有关更多信息,请参阅安全说明

在 AWS IoT 控制台中显示名称:本地 Compose 文件的目录路径

必需: true

类型: string

有效模式 \/.*\/?

示例:/home/username/myCompose

DockerUserId

连接器以其身份运行的 Linux 用户的 UID。此用户必须属于核心设备上的 docker Linux 组,并且具有对 DockerComposeFileDestinationPath 目录的写入权限。有关更多信息,请参阅在 核心上设置 Docker 用户

注意

除非绝对有必要,否则建议避免以根用户身份运行。如果您确实指定了 root 用户,则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass Core 上运行。有关更多信息,请参阅以根用户身份运行 Lambda 函数

在 AWS IoT 控制台中显示名称:Docker 用户 ID

必需: false

类型: string

有效模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中的密钥的 Amazon 资源名称 (ARN),其中包含用于访问私有存储库中 Docker 映像的登录信息。有关更多信息,请参阅从私有存储库访问 Docker 镜像

在 AWS IoT 控制台中显示名称:私有存储库的凭证

必需:false。 此参数是访问存储在私有存储库中的 Docker 映像所必需的。

类型:arraystring

有效模式: [( ?,? ?"(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:区域::/connectors/DockerApplicationDeployment/versions/5", "Parameters": { "DockerComposeFileS3Bucket": "myS3Bucket", "DockerComposeFileS3Key": "production-docker-compose.yml", "DockerComposeFileS3Version": "123", "DockerComposeFileDestinationPath": "/home/username/myCompose", "DockerUserId": "1000", "AWSSecretsArnList": "[\"arn:aws:secretsmanager:区域:account-id:secret:greengrass-secret1-hash\",\"arn:aws:secretsmanager:区域:account-id:secret:greengrass-secret2-hash\"]", "DockerContainerStatusLogFrequency": "30", "ForceDeploy": "True", "DockerPullBeforeUp": "True" } } ] }'
注意

该连接器中的 Lambda 函数具有很长的生命周期。

输入数据

此连接器不需要或接受输入数据。

输出数据

此连接器将 docker-compose up 命令的状态发布为输出数据。

订阅中的主题筛选条件

dockerapplicationdeploymentconnector/message/status

输出示例: 成功
{ "status":"success", "GreengrassDockerApplicationDeploymentStatus":"Successfully triggered docker-compose up", "S3Bucket":"myS3Bucket", "ComposeFileName":"production-docker-compose.yml", "ComposeFileVersion":"123" }
输出示例: 失败
{ "status":"fail", "error_message":"description of error", "error":"InvalidParameter" }

错误类型可以是 InvalidParameterInternalError

在 AWS IoT Greengrass 核心上设置 Docker 用户

Greengrass Docker 应用程序部署 连接器以您为 DockerUserId 参数指定的用户的身份运行。如果不指定值,则连接器将以 ggc_user 身份运行,这是默认的 Greengrass 访问标识。

要允许连接器与 Docker 守护程序交互,Docker 用户必须属于核心上的 docker Linux 组。Docker 用户还必须具有对 DockerComposeFileDestinationPath 目录的写入权限。这是连接器存储本地 docker-compose.yml 文件和 Docker 凭证的位置。

注意
  • 我们建议您创建Linux用户,而不是使用默认 ggc_user。否则, Lambda 功能可以访问Compose文件和Docker凭证。

  • 除非绝对有必要,否则建议避免以根用户身份运行。如果您确实指定了 root 用户,则必须允许 Lambda 函数以 root 身份在 AWS IoT Greengrass Core 上运行。有关更多信息,请参阅以根用户身份运行 Lambda 函数

  1. 创建用户。您可以运行 useradd 命令并包含用于分配 UID 的可选 -u 选项。例如:

    sudo useradd -u 1234 user-name
  2. 将用户添加到核心上的 docker 组。例如:

    sudo usermod -aG docker user-name

    有关详细信息,包括如何创建 docker 组,请参阅 Docker 文档中的以非 root 用户身份管理 Docker

  3. 授予用户写入为 DockerComposeFileDestinationPath 参数指定的目录的权限。例如:

    1. 将用户设置为目录的所有者。此示例使用步骤 1 中的 UID。

      chown 1234 docker-compose-file-destination-path
    2. 为所有者授予读写权限。

      chmod 700 docker-compose-file-destination-path

      有关详细信息,请参阅 Linux Foundation 文档中的如何在 Linux 中管理文件和文件夹权限

    3. 如果您在创建用户时没有分配 UID,或者使用现有用户,请运行 id 命令查找 UID。

      id -u user-name

      您可以使用 UID 配置连接器的 DockerUserId 参数。

使用情况信息

当您使用 Greengrass Docker 应用程序部署 连接器时,您应该注意以下特定于实现的使用信息。

  • 项目名称的固定前缀。连接器将 greengrassdockerapplicationdeployment 前缀附加到其启动的 Docker 容器的名称前面。连接器在它所运行的 docker-compose 命令中使用此前缀作为项目名称。

  • 日志记录行为。连接器将状态信息和疑难解答信息写入日志文件。您可以配置 AWS IoT Greengrass 将日志发送到 CloudWatch Logs 以及在本地写入日志。有关更多信息,请参阅连接器的日志记录。这是连接器的本地日志的路径:

    /greengrass-root/ggc/var/log/user/区域/aws/DockerApplicationDeployment.log

    您必须具有 root 权限才能访问本地日志。

  • 更新 Docker 镜像。Docker 在核心设备上缓存镜像。如果您更新 Docker 镜像并希望将更改传播到核心设备,请确保更改 Compose 文件中镜像的标签。更改将在部署 Greengrass 组后生效。

  • 清理操作的 10 分钟超时。当 Greengrass 守护程序(在重新启动期间)停止时,将触发该 docker-compose down 命令。所有 Docker 容器在触发 docker-compose down 后最多具有 10 分钟以执行任何清理操作。如果清理在 10 分钟内未完成,则必须手动清理剩余的容器。有关更多信息,请参阅 Docker CLI 文档中的 docker rm

  • 运行 Docker 命令。要解决问题,您可以在核心设备上的终端窗口中运行 Docker 命令。例如,运行以下命令以查看由连接器启动的 Docker 容器:

    docker ps --filter name="greengrassdockerapplicationdeployment"
  • 保留资源 ID。连接器使用它在 Greengrass 组中创建的 Greengrass 资源的 DOCKER_DEPLOYER_SECRET_RESOURCE_RESERVED_ID_index ID。资源 IDs 在组中必须是唯一的,因此不要分配可能与此保留资源ID冲突的资源ID。

与 Docker 容器通信

AWS IoT Greengrass 支持 Greengrass 组件和 Docker 容器之间的以下通信通道:

  • Greengrass Lambda 函数可以使用REST APIs 与Docker容器中的进程通信。您可以在 Docker 容器中设置打开端口的服务器。 Lambda 函数可以在此端口上与容器进行通信。

  • Docker 容器中的进程可以通过本地 Greengrass 消息代理交换 MQTT 消息。您可以将 Docker 容器设置为 Greengrass 组中的 Greengrass 设备,然后创建订阅以允许容器与组中的 Greengrass Lambda 函数、设备和其他连接器或与 AWS IoT 本地影子服务进行通信。有关更多信息,请参阅配置 MQTT 与 Docker 容器的通信

  • Greengrass Lambda 函数可以更新共享文件以将信息传递给 Docker 容器。您可以使用 Compose 文件绑定装载 Docker 容器的共享文件路径。

配置 MQTT 与 Docker 容器的通信

您可以将 Docker 容器配置为 Greengrass 设备,并将其添加到 Greengrass 组中。然后,您可以创建允许在 Docker 容器和 Greengrass 组件或 AWS IoT 之间进行 MQTT 通信的订阅。在以下过程中,您将创建允许 Docker 容器设备从本地影子服务接收影子更新消息的订阅。您可以按照此模式创建其他订阅。

注意

在此过程中,我们假设您已经创建了 Greengrass 组和 Greengrass 核心 (v1.10 or later)。要了解如何创建 Greengrass 组和核心,请参阅 AWS IoT Greengrass 入门

将 Docker 容器配置为 Greengrass 设备并将其添加到 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
  2. 在 AWS IoT 控制台中,选择 Greengrass,然后选择 Groups (组)

  3. 选择目标组。

  4. 在组配置页面中,选择设备,然后选择添加设备

    
                            突出显示了“Add your first Device (添加第一个设备)”按钮的“Devices (设备)”页面的屏幕截图。
  5. 添加设备页面上,选择创建新设备

  6. Create a Registry entry for a device (为设备创建注册表项) 页面上,输入该设备的名称,然后选择 Next (下一步)

  7. 设置安全性页面上,对于 1-Click (一键式操作),选择 Use Defaults (使用默认值)。此选项生成一个具有附加 AWS IoT 策略以及公有密钥和私有密钥的设备证书。

  8. 下载安全凭证 ,将证书和密钥下载到您在步骤1中创建的目录,然后选择 Finish.

    
                            突出显示了“Download these resources as a tar.gz (将这些资源作为一个 tar.gz 下载)”按钮的“Download security credentials (下载安全凭证)”页面的屏幕截图。
  9. 解压缩 hash-setup.tar.gz 文件。例如,运行以下命令。这些区域有:hash 占位符是 tar.gz 您所下载的文件(例如, bcc5afd26d)。

    cd /path-to-device-certs tar -xzf hash-setup.tar.gz
  10. 查看 AWS IoT 开发人员指南 中的服务器身份验证并选择合适的根 CA 证书。我们建议使用 Amazon Trust Services (ATS) 终端节点以及 ATS 根 CA 证书。

    重要

    您的根 CA 证书类型必须与终端节点匹配。使用具有 ATS 终端节点的 ATS 根 CA 证书(首选)或具有旧终端节点的 VeriSign 根 CA 证书。只有部分 AWS 区域支持传统终端节点。有关更多信息,请参阅 服务终端节点必须与根 CA 证书类型匹配

    将相应的 ATS 根 CA 证书下载到核心设备。例如,您可以使用以下 wget 命令将 AmazonRootCA1.pem 下载到您的文件路径。

    cd /path-to-device-certs sudo wget -O root.ca.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem

接下来,在组中创建订阅。对于此示例,您创建一个订阅,以允许 Docker 容器设备从本地影子服务接收 MQTT 消息。

注意

影子文档的最大大小为 8 KB。有关更多信息,请参阅 AWS IoT 配额AWS IoT 开发人员指南.

创建允许 Docker 容器设备从本地影子服务接收 MQTT 消息的订阅。

  1. 在组配置页面上,选择 订阅,然后选择 Add Subscription.

    
                突出显示“Subscriptions (订阅)”和“Add Subscription (添加订阅)”的组页面。
  2. 选择您的源和目标页面,配置源和目标,如下所示:

    1. 对于选择源,选择服务,然后选择本地影子服务

    2. 对于 Select a target (选择目标),选择 Devices (设备),然后选择您的设备。

    3. 选择 Next.

    4. 使用主题筛选数据 页面,针对 主题过滤器,选择 $aws/things/TestCore/shadow/update/accepted,然后选择 Next.

    5. 选择 Finish.

在您的 Compose 文件中引用的 Docker 镜像中包含以下代码段。这是 Greengrass 设备代码。此外,在 Docker 容器中添加代码,以启动容器内的 Greengrass 设备。它可以作为一个单独的进程在镜像或单独的线程中运行。

from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider # Discover Greengrass cores. discoveryInfoProvider = DiscoveryInfoProvider() discoveryInfoProvider.configureEndpoint(host) # Configure these paths based on the download location of the certificates. discoveryInfoProvider.configureCredentials(rootCAPath, certificatePath, privateKeyPath) discoveryInfoProvider.configureTimeout(10) # 10 seconds. # Get discovery info from AWS IoT. # thingName is the name you registered for the device. discoveryInfo = discoveryInfoProvider.discover(thingName) caList = discoveryInfo.getAllCas() coreList = discoveryInfo.getAllCores() # Try to connect to the Greengrass core. for connectivityInfo in coreInfo.connectivityInfoList: currentHost = connectivityInfo.host currentPort = connectivityInfo.port myAWSIoTMQTTClient.configureEndpoint(currentHost, currentPort) try: myAWSIoTMQTTClient.connect() connected = True break except BaseException as e: print("Error in connect!") 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 a message on MQTT") print(message) # Subscribe to the MQTT topic. # The topic is the "$aws/things/TestCore/shadow/update/accepted". myAWSIoTMQTTClient.subscribe(topic, 1, 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

从可信来源安装 Docker Engine

您负责从可信来源安装 Docker Engine。此连接器使用核心设备上的 Docker 守护程序访问您的 Docker 资产并管理 Docker 容器。

Greengrass 组角色权限的范围

在 Greengrass 组角色中添加的权限可由 Greengrass 组中的所有 Lambda 函数和连接器代入。此连接器需要访问存储在 S3 存储桶中的 Docker Compose 文件。如果您的 Docker 镜像存储在 Amazon ECR 中的私有存储库中,它还需要访问您的 Amazon ECR 授权令牌。

许可证

Greengrass Docker 应用程序部署 连接器包含以下第三方软件/许可:

此连接器按照 Greengrass 核心软件许可协议发布。

Changelog

下表描述了连接器每个版本中所做的更改。

版本

更改

6

已添加 StopContainersOnNewDeployment 在进行新部署或GGC停止时覆盖容器清理。更安全的关机和启动机制。YAML验证Bug修复。

5

运行前已拉取图像 docker-compose down.

4

添加了上拉行为以更新Docker镜像。

3

修复了查找环境变量的问题。

2

添加了 ForceDeploy 参数。

1

首次发布。

Greengrass 组一次只能包含一个版本的连接器。有关升级连接器版本的信息,请参阅升级连接器版本

另请参阅