Amazon IoT Greengrass 在具有自动资源配置功能的 Docker 容器中运行 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

Amazon IoT Greengrass 在具有自动资源配置功能的 Docker 容器中运行

本教程向您展示如何使用自动配置的 Amazon 资源和本地开发工具在 Docker 容器中安装和运行 C Amazon IoT Greengrass ore 软件。您可以使用此开发环境来探索 Docker 容器中的 Amazon IoT Greengrass 功能。该软件要求提供 Amazon 凭证来配置这些资源及部署本地开发工具。

如果您无法向容器提供 Amazon 凭证,则可以预配置核心设备运行所需的 Amazon 资源。您还可以将开发工具部署到核心设备上,用作开发设备。这使您能够在运行容器时向设备提供较少的权限。有关更多信息,请参阅通过手动资源预置在 Docker 容器中运行 Amazon IoT Greengrass

先决条件

要完成本教程,您需要以下要素。

  • 一个 Amazon Web Services 账户。如果没有,请参阅设置一个 Amazon Web Services 账户

  • 有权为 Greengrass 核心设备配置 Amazon IoT 和IAM资源的 Amazon IAM用户。C Amazon IoT Greengrass ore 软件安装程序使用您的 Amazon 凭据自动配置这些资源。有关自动配置资源的最低IAM策略的信息,请参阅安装程序配置资源的最低 IAM 策略

  • 一张 Amazon IoT Greengrass Docker 镜像。你可以从 Amazon IoT Greengrass Dockerfile 中生成镜像

  • 运行 Docker 容器的主机必须满足以下要求:

    • 支持互联网连接的基于 Linux 的操作系统。

    • Docker Engine 18.09 版本或更高版本。

    • (可选)Docker Compose 1.22 版本或更高版本。只有当你想使用 Docker Compose 来运行 Docker 镜像时,才需要 Docker Compose CLI。

配置 Amazon 凭证

在此步骤中,您将在主机上创建一个包含 Amazon 安全凭证的凭证文件。运行 Amazon IoT Greengrass Docker 镜像时,必须将包含此凭证文件的文件夹挂载到 Docker 容器/root/.aws/中。 Amazon IoT Greengrass 安装程序使用这些凭据在中配置资源 Amazon Web Services 账户。有关安装程序自动配置资源所需的最低IAM策略的信息,请参阅安装程序配置资源的最低 IAM 策略

  1. 检索以下其中一项。

  2. 创建一个用于存放凭证文件的文件夹。

    mkdir ./greengrass-v2-credentials
  3. 使用文本编辑器在 ./greengrass-v2-credentials 文件夹中创建名为 credentials 的配置文件。

    例如,你可以运行以下命令来使用 GNU nano 来创建credentials文件。

    nano ./greengrass-v2-credentials/credentials
  4. 按以下格式将您的 Amazon 凭证添加到credentials文件中。

    [default] aws_access_key_id = AKIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token = AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

    仅为临时凭证包含 aws_session_token

重要

启动 Amazon IoT Greengrass 容器后,将凭据文件从主机中删除。如果您不删除凭证文件,则您的 Amazon 凭证将保持挂载在容器中。有关更多信息,请参阅 在容器中运行 Amazon IoT Greengrass Core 软件

创建环境文件

本教程使用环境文件来设置环境变量,这些变量将传递给 Docker 容器内的 C Amazon IoT Greengrass ore 软件安装程序。您还可以在 docker run 命令中使用 -e--env 参数在 Docker 容器中设置环境变量,或在 docker-compose.yml 文件中的 environment中设置变量。

  1. 使用文本编辑器创建名为 .env 的环境文件。

    例如,在基于 Linux 的系统上,您可以运行以下命令以使用 GNU nano 在当前目录.env中创建。

    nano .env
  2. 将以下内容复制到该文件中。

    GGC_ROOT_PATH=/greengrass/v2 AWS_REGION=region PROVISION=true THING_NAME=MyGreengrassCore THING_GROUP_NAME=MyGreengrassCoreGroup TES_ROLE_NAME=GreengrassV2TokenExchangeRole TES_ROLE_ALIAS_NAME=GreengrassCoreTokenExchangeRoleAlias COMPONENT_DEFAULT_USER=ggc_user:ggc_group

    然后,替换以下值。

    • /greengrass/v2。要用于安装的 Greengrass 根文件夹。您可以使用 GGC_ROOT 环境变量来设置此值。

    • region。 您创建资源 Amazon Web Services 区域 的位置。

    • MyGreengrassCore。 Amazon IoT 事物的名字。如果该事物不存在,安装程序会进行创建。安装程序下载证书以进行身份 Amazon IoT 验证。

    • MyGreengrassCoreGroup。 Amazon IoT 事物组的名称。如果该事物组不存在,安装程序会进行创建并向其中添加事物。如果事物组存在且有活动的部署,则核心设备将下载并运行部署指定的软件。

    • GreengrassV2TokenExchangeRole。 替换为允许 Greengrass 核心设备获取临时证书的IAM令牌交换角色的名称。 Amazon 如果该角色不存在,则安装程序会创建该角色并创建并附加名为 A GreengrassV2TokenExchangeRole ccess 的策略。有关更多信息,请参阅 授权核心设备与 Amazon 服务交互

    • GreengrassCoreTokenExchangeRoleAlias。 代币交换角色别名。如果角色别名不存在,则安装程序会创建该别名并将其指向您指定的IAM令牌交换角色。有关更多信息,请参阅

    注意

    您可以将DEPLOY_DEV_TOOLS环境变量设置为true以部署 G CLI reengrass 组件,这样您就可以在 Docker 容器内开发自定义组件。我们建议您仅在开发环境中使用此组件,不要在生产环境中使用。此组件允许访问您在生产环境中通常不需要的信息和操作。遵循最低权限原则,将此组件仅部署到有需求的核心设备。

在容器中运行 Amazon IoT Greengrass Core 软件

本教程向您展示了如何启动在 Docker 容器中构建的 Docker 映像。你可以使用 Docker CLI 或 Docker Compose CLI 在 Docker 容器中运行 Amazon IoT Greengrass 核心软件镜像。

Docker
  1. 运行以下命令来启动 Docker 容器。

    docker run --rm --init -it --name docker-image \ -v path/to/greengrass-v2-credentials:/root/.aws/:ro \ --env-file .env \ -p 8883 \ your-container-image:version

    此示例命令为 docker run 使用以下参数:

    • --rm。当容器退出时,清理容器。

    • --init。在容器中使用 init 进程。

      注意

      当你停止 Docker 容器时,需要使用该--init参数才能关闭 C Amazon IoT Greengrass ore 软件。

    • -it。(可选)作为交互式进程在前台运行 Docker 容器。您可以将此项替换为 -d 参数,以在分离模式下运行 Docker 容器。有关更多信息,请参阅 Docker 文档中的分离模式与前台模式

    • --name。运行名为 aws-iot-greengrass 的容器

    • -v。 将卷挂载到 Docker 容器中,使配置文件和证书文件可供在容器内 Amazon IoT Greengrass 运行。

    • --env-file。 (可选)指定环境文件以设置将传递给 Docker 容器内的 C Amazon IoT Greengrass ore 软件安装程序的环境变量。只有在创建环境文件来设置环境变量时,才需要此参数。如果您没有创建环境文件,则可以直接在 Docker run 命令中使用 --env 参数设置环境变量。

    • -p。(可选)将 8883 容器端口发布到主机。如果要连接和通信,则必须使用此参数,MQTT因为MQTT流量 Amazon IoT Greengrass 使用端口 8883。要打开其它端口,请使用其它 -p 参数。

    注意

    要以更高的安全性运行 Docker 容器,您可以使用 --cap-drop--cap-add 参数选择性地为容器启用 Linux 功能。有关更多信息,请参阅 Docker 文档中的运行时权限和 Linux 功能

  2. 从主机设备上的 ./greengrass-v2-credentials 中移除凭证。

    rm -rf ./greengrass-v2-credentials
    重要

    您之所以移除这些凭证,是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证,Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 Amazon 凭证,请使用令牌交换服务。有关更多信息,请参阅 与 Amazon 服务互动

Docker Compose
  1. 使用文本编辑器创建名为 docker-compose.yml 的 Docker Compose 文件。

    例如,在基于 Linux 的系统上,您可以运行以下命令以使用 GNU nano 在当前目录docker-compose.yml中创建。

    nano docker-compose.yml
    注意

    您也可以从中下载和使用 Amazon提供的 Compose 文件的最新版本。GitHub

  2. 将以下内容添加到 Compose 文件。您的文件应类似于以下示例。docker-image替换为你的 Docker 镜像的名称。

    version: '3.7' services: greengrass: init: true container_name: aws-iot-greengrass image: docker-image volumes: - ./greengrass-v2-credentials:/root/.aws/:ro env_file: .env ports: - "8883:8883"

    此示例 Compose 文件中的以下参数是可选的:

    • ports – 将 8883 容器端口发布到主机。如果要通过此参数进行连接和通信,则必须使用此参数,MQTT因为MQTT流量 Amazon IoT Greengrass 使用端口 8883。

    • env_file— 指定环境文件以设置将传递给 Docker 容器内的 C Amazon IoT Greengrass ore 软件安装程序的环境变量。只有在创建环境文件来设置环境变量时,才需要该参数。如果您没有创建环境文件,则可以使用环境参数直接在 Compose 文件中设置变量。

    注意

    要以更高的安全性运行 Docker 容器,您可以使用 Compose 文件中的 cap_dropcap_add 选择性地为容器启用 Linux 功能。有关更多信息,请参阅 Docker 文档中的运行时权限和 Linux 功能

  3. 运行以下命令来启动 Docker 容器。

    docker-compose -f docker-compose.yml up
  4. 从主机设备上的 ./greengrass-v2-credentials 中移除凭证。

    rm -rf ./greengrass-v2-credentials
    重要

    您之所以移除这些凭证,是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证,Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 Amazon 凭证,请使用令牌交换服务。有关更多信息,请参阅 与 Amazon 服务互动

后续步骤

Amazon IoT Greengrass 核心软件现在在 Docker 容器中运行。运行以下命令以检索当前运行容器的容器 ID。

docker ps

然后,您可以运行以下命令来访问容器并浏览容器内运行的 Amazon IoT Greengrass Core 软件。

docker exec -it container-id /bin/bash

有关创建简单组件的信息,请参阅教程:入门 Amazon IoT Greengrass V2中的第 4 步:在设备上开发和测试组件

注意

当您使用 docker exec 在 Docker 容器内运行命令时,这些命令不会记录在 Docker 日志中。要将命令记录在 Docker 日志中,请将交互式 Shell 附加到 Docker 容器。有关更多信息,请参阅 将交互式 Shell 附加到 Docker 容器

C Amazon IoT Greengrass ore 日志文件被调用greengrass.log,位于中/greengrass/v2/logs。组件日志文件也位于同一目录中。要将 Greengrass 日志复制到主机上的临时目录,请运行以下命令:

docker cp container-id:/greengrass/v2/logs /tmp/logs

如果您想在容器退出或移除后保留日志,我们建议您仅将 /greengrass/v2/logs 目录绑定挂载到主机上的临时日志目录,而不是挂载整个 Greengrass 目录。有关更多信息,请参阅 在 Docker 容器之外保留 Greengrass 日志

要停止正在运行的 Amazon IoT Greengrass Docker 容器,请运行docker stopdocker-compose -f docker-compose.yml stop。此操作可将 SIGTERM 发送到 Greengrass 进程,并关闭容器中启动的所有关联进程。Docker 容器使用docker-init可执行文件作为进程 PID 1 进行初始化,这有助于删除所有剩余的僵尸进程。有关更多信息,请参阅 Docker 文档中的指定 init 进程

有关对在 Docker 容器中运行 Amazon IoT Greengrass 的问题进行排查的信息,请参阅在 Docker Amazon IoT Greengrass 容器中进行故障排除