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

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

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

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

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

先决条件

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

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

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

  • 一个 Amazon IoT Greengrass Docker 镜像。你可以从 Amazon IoT Greengrass Dockerfile 中构建镜像

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

    • 具有互联网连接的基于 Linux 的操作系统。

    • Docker 引擎版本 18.09 或更高版本。

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

配置 Amazon凭证

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

  1. 检索以下内容之一。

    • IAM 用户的长期证书。有关如何检索长期证书的信息,请参阅 IAM 用户指南中的管理 IAM 用户的访问密钥

    • (推荐)IAM 角色的临时证书。有关如何检索临时证书的信息,请参阅 IAM 用户指南Amazon CLI中的使用临时安全证书

  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 容器内的 Amazon IoT Greengrass Core 软件安装程序。您还可以在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环境变量来设置此值。

    • 地区。您创建资源Amazon Web Services 区域的地方。

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

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

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

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

    注意

    您可以将DEPLOY_DEV_TOOLS环境变量设置为true以部署 Greengrass CLI 组件,这使您能够在 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 运行

    • --rm。 在容器退出时清理容器。

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

      注意

      停止 Docker 容器时,需要使用该--init参数来关闭Amazon IoT Greengrass核心软件。

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

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

    • -v。 在 Docker 容器中装入一个卷,使配置文件和证书文件可以在容器内Amazon IoT Greengrass运行。

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

    • -p。 (可选)将 8883 容器端口发布到主机。如果您想通过 MQTT 进行连接和通信,则此参数是必需的,因为Amazon IoT Greengrass使用 8883 端口 MQTT 流量。要打开其他端口,请使用其他-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 容器内的 Amazon IoT Greengrass Core 软件安装程序的环境变量。仅当您创建了用于设置环境变量的环境文件时,才需要此参数。如果您没有创建环境文件,则可以使用环境参数直接在 Compose 文件中设置变量。

    注意

    要以更高的安全性运行 Docker 容器,您可以在 Compose 文件cap_add中使用cap_drop和有选择地为容器启用 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

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

注意

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

Amazon IoT Greengrass核心日志文件被调用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 文档

有关解决在 Docker 容器Amazon IoT Greengrass中运行的问题的信息,请参阅对 Docker 容器中的 Amazon IoT Greengrass 执行问题排查