先决条件配置您的 AWS 凭证创建环境文件运行 AWS IoT Greengrass Core 软件后续步骤

通过自动资源预置在 Docker 容器中运行 AWS IoT Greengrass

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

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

先决条件

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

AWS 账户。如果没有，请参阅设置一个 AWS 账户。
有权为 Greengrass 核心设备预置 AWS IoT 和 IAM 资源的 AWS IAM 用户。AWS IoT Greengrass Core 软件安装程序使用 AWS 凭证自动预置这些资源。有关自动预置资源的最低 IAM 策略的信息，请参阅安装程序配置资源的最低 IAM 策略。
AWS IoT Greengrass Docker 映像。您可以通过 AWS IoT Greengrass Dockerfile 构建映像。
运行 Docker 容器的主机必须满足以下要求：
- 支持互联网连接的基于 Linux 的操作系统。
- Docker Engine 18.09 版本或更高版本。
- （可选）Docker Compose 1.22 版本或更高版本。只有当您想使用 Docker Compose CLI 来运行 Docker 映像时，才需要 Docker Compose。

配置您的 AWS 凭证

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

检索以下其中一项。
- IAM 用户的长期凭证。有关如何检索长期凭证的信息，请参阅《IAM 用户指南》中的管理 IAM 用户的访问密钥。
- （推荐）IAM 角色的临时凭证。有关如何检索临时凭证的信息，请参阅《IAM 用户指南》中的将临时安全凭证用于 AWS CLI。
创建一个用于存放凭证文件的文件夹。
```
mkdir ./greengrass-v2-credentials
```
使用文本编辑器在 ./greengrass-v2-credentials 文件夹中创建名为 credentials 的配置文件。

例如，您可以运行以下命令来使用 GNU nano 创建 credentials 文件。
```
nano ./greengrass-v2-credentials/credentials
```

按以下格式将 AWS 凭证添加到 credentials 文件中。


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

仅为临时凭证包含 aws_session_token。

重要

启动 AWS IoT Greengrass 容器后，将凭证文件从主机中移除。如果不移除凭证文件，则 AWS 凭证仍将挂载在容器内。有关更多信息，请参阅在容器中运行 AWS IoT Greengrass Core 软件。

创建环境文件

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

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

例如，在基于 Linux 的系统上，您可以运行以下命令来使用 GNU nano 在当前目录中创建 .env。
```
nano .env
```
将以下内容复制到该文件中。
```
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。您创建资源时使用的 AWS 区域。
- MyGreengrassCore。AWS IoT 事物的名称。如果该事物不存在，安装程序会进行创建。安装程序会下载证书以作为 AWS IoT 事物进行身份验证。
- MyGreengrassCoreGroup。AWS IoT 事物组的名称。如果该事物组不存在，安装程序会进行创建并向其中添加事物。如果事物组存在且有活动的部署，则核心设备将下载并运行部署指定的软件。
- GreengrassV2TokenExchangeRole。替换为允许 Greengrass 核心设备获取临时 AWS 凭证的 IAM 令牌交换角色的名称。如果该角色不存在，安装程序会创建该角色，还会创建并附加名为 GreengrassV2TokenExchangeRoleAccess 的策略。有关更多信息，请参阅授权核心设备与 AWS 服务交互。
- GreengrassCoreTokenExchangeRoleAlias。令牌交换角色别名。如果该角色别名不存在，安装程序会进行创建，并将其指向您指定的 IAM 令牌交换角色。有关更多信息，请参阅
注意
您可以将 DEPLOY_DEV_TOOLS 环境变量设置为 true，以部署 Greengrass CLI 组件，进而在 Docker 容器内开发自定义组件。我们建议您仅在开发环境中使用此组件，不要在生产环境中使用。此组件允许访问您在生产环境中通常不需要的信息和操作。遵循最低权限原则，将此组件仅部署到有需求的核心设备。

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

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

Docker

运行以下命令来启动 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 参数才能关闭 AWS IoT Greengrass Core 软件。
- -it。（可选）作为交互式进程在前台运行 Docker 容器。您可以将此项替换为 -d 参数，以在分离模式下运行 Docker 容器。有关更多信息，请参阅 Docker 文档中的分离模式与前台模式。
- --name。运行名为 aws-iot-greengrass 的容器
- -v。将卷挂载到 Docker 容器中，使配置文件和证书文件可供容器内运行的 AWS IoT Greengrass 使用。
- --env-file。（可选）指定环境文件来设置环境变量，这些变量将传递给 Docker 容器内的 AWS IoT Greengrass Core 软件安装程序。只有在创建环境文件来设置环境变量时，才需要此参数。如果您没有创建环境文件，则可以直接在 Docker run 命令中使用 --env 参数设置环境变量。
- -p。（可选）将 8883 容器端口发布到主机。如果您想通过 MQTT 进行连接和通信，需要使用此参数，因为 AWS IoT Greengrass 将端口 8883 用于 MQTT 流量。要打开其它端口，请使用其它 -p 参数。
注意
要以更高的安全性运行 Docker 容器，您可以使用 --cap-drop 和 --cap-add 参数选择性地为容器启用 Linux 功能。有关更多信息，请参阅 Docker 文档中的运行时权限和 Linux 功能。
从主机设备上的 ./greengrass-v2-credentials 中移除凭证。
```
rm -rf ./greengrass-v2-credentials
```
重要
您之所以移除这些凭证，是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证，Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 AWS 凭证，请使用令牌交换服务。有关更多信息，请参阅与 AWS 服务交互。

Docker Compose

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

例如，在基于 Linux 的系统上，您可以运行以下命令来使用 GNU nano 在当前目录中创建 docker-compose.yml。
```
nano docker-compose.yml
```
注意
您还可以从 GitHub 下载和使用 AWS 提供的 Compose 文件的最新版本。
将以下内容添加到 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 进行连接和通信，则需要此参数，因为 AWS IoT Greengrass 将端口 8883 用于 MQTT 流量。
- env_file – 指定环境文件来设置环境变量，这些变量将传递给 Docker 容器内的 AWS IoT Greengrass Core 软件安装程序。只有在创建环境文件来设置环境变量时，才需要该参数。如果您没有创建环境文件，则可以使用环境参数直接在 Compose 文件中设置变量。
注意
要以更高的安全性运行 Docker 容器，您可以使用 Compose 文件中的 cap_drop 和 cap_add 选择性地为容器启用 Linux 功能。有关更多信息，请参阅 Docker 文档中的运行时权限和 Linux 功能。
运行以下命令来启动 Docker 容器。
```
docker-compose -f docker-compose.yml up
```
从主机设备上的 ./greengrass-v2-credentials 中移除凭证。
```
rm -rf ./greengrass-v2-credentials
```
重要
您之所以移除这些凭证，是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证，Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 AWS 凭证，请使用令牌交换服务。有关更多信息，请参阅与 AWS 服务交互。

后续步骤

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


docker ps

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


docker exec -it container-id /bin/bash

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

注意

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

AWS IoT Greengrass Core 日志文件名为 greengrass.log，位于 /greengrass/v2/logs 中。组件日志文件也位于同一目录中。要将 Greengrass 日志复制到主机上的临时目录，请运行以下命令：


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

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

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

有关对在 Docker 容器中运行 AWS IoT Greengrass 的问题进行排查的信息，请参阅对 Docker 容器中的 AWS IoT Greengrass 执行问题排查。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

通过 Dockerfile 构建 AWS IoT Greengrass 映像

使用手动 AWS IoT Greengrass 配置在 Docker 中运行