本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon IoT Greengrass 在具有自动资源配置功能的 Docker 容器中运行
本教程向您展示如何使用自动配置的 Amazon 资源和本地开发工具在 Docker 容器中安装和运行 C Amazon IoT Greengrass ore 软件。您可以使用此开发环境来探索 Docker 容器中的 Amazon IoT Greengrass 功能。该软件要求提供 Amazon 凭证来配置这些资源及部署本地开发工具。
如果您无法向容器提供 Amazon 凭证，则可以预配置核心设备运行所需的 Amazon 资源。您还可以将开发工具部署到核心设备上，用作开发设备。这使您能够在运行容器时向设备提供较少的权限。有关更多信息，请参阅[Amazon IoT Greengrass 在 Docker 容器中运行，手动配置资源](run-greengrass-docker-manual-provisioning.md)。
## 先决条件
要完成本教程，您需要以下要素。
+ 一个 Amazon Web Services 账户。如果没有，请参阅[设置一个 Amazon Web Services 账户](setting-up.md#set-up-aws-account)。
+ 有权为 Amazon Greengrass 核心设备配置 Amazon IoT 和 IAM 资源的 IAM 用户。C Amazon IoT Greengrass ore 软件安装程序使用您的 Amazon 凭据自动配置这些资源。有关自动预置资源的最低 IAM 策略的信息，请参阅[安装程序配置资源的最低 IAM 策略](provision-minimal-iam-policy.md)。
+ 一张 Amazon IoT Greengrass Docker 镜像。你可以[从 Amazon IoT Greengrass Dockerfile 中生成镜像](build-greengrass-dockerfile.md)。
+ 运行 Docker 容器的主机必须满足以下要求：
+ 支持互联网连接的基于 Linux 的操作系统。
+ [Docker Engine](https://docs.docker.com/engine/install/) 18.09 版本或更高版本。
+ （可选）[Docker Compose](https://docs.docker.com/compose/install/) 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 策略](provision-minimal-iam-policy.md)。
1. 检索以下其中一项。
+ IAM 用户的长期凭证。有关如何检索长期凭证的信息，请参阅《IAM 用户指南》**中的[管理 IAM 用户的访问密钥](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_access-keys.html)。
+ （推荐）IAM 角色的临时凭证。有关如何检索临时凭证的信息，请参阅《IAM 用户指南》**中的[将临时安全凭证用于 Amazon CLI](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_temp_use-resources.html#using-temp-creds-sdk-cli)。
1. 创建一个用于存放凭证文件的文件夹。
```
mkdir ./greengrass-v2-credentials
```
1. 使用文本编辑器在 `./greengrass-v2-credentials` 文件夹中创建名为 `credentials` 的配置文件。
例如，您可以运行以下命令来使用 GNU nano 创建 `credentials` 文件。
```
nano ./greengrass-v2-credentials/credentials
```
1. 按以下格式将您的 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 软件](#run-greengrass-image-automatic-provisioning)。
## 创建环境文件
本教程使用环境文件来设置环境变量，这些变量将传递给 Docker 容器内的 C Amazon IoT Greengrass ore 软件安装程序。您还可以在 `docker run` 命令中使用 [`-e` 或 `--env` 参数](https://docs.docker.com/engine/reference/commandline/run/#env)在 Docker 容器中设置环境变量，或在 `docker-compose.yml` 文件中的 [`environment` 块](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment)中设置变量。
1. 使用文本编辑器创建名为 `.env` 的环境文件。
例如，在基于 Linux 的系统上，您可以运行以下命令来使用 GNU nano 在当前目录中创建 `.env`。
```
nano .env
```
1. 将以下内容复制到该文件中。
```
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 服务交互](device-service-role.md)。
+ *GreengrassCoreTokenExchangeRoleAlias*。 代币交换角色别名。如果该角色别名不存在，安装程序会进行创建，并将其指向您指定的 IAM 令牌交换角色。有关更多信息，请参阅
**注意**
您可以将 `DEPLOY_DEV_TOOLS` 环境变量设置为 `true`，以部署 [Greengrass CLI 组件](greengrass-cli-component.md)，进而在 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](https://docs.docker.com/engine/reference/commandline/run/) 使用以下参数：
+ [https://docs.docker.com/engine/reference/run/#clean-up---rm](https://docs.docker.com/engine/reference/run/#clean-up---rm)。当容器退出时，清理容器。
+ [https://docs.docker.com/engine/reference/run/#specify-an-init-process](https://docs.docker.com/engine/reference/run/#specify-an-init-process)。在容器中使用 init 进程。
**注意**
当你停止 Docker 容器时，需要使用该`--init`参数才能关闭 C Amazon IoT Greengrass ore 软件。
+ [https://docs.docker.com/engine/reference/run/#foreground](https://docs.docker.com/engine/reference/run/#foreground)。（可选）作为交互式进程在前台运行 Docker 容器。您可以将此项替换为 `-d` 参数，以在分离模式下运行 Docker 容器。有关更多信息，请参阅 Docker 文档中的[分离模式与前台模式](https://docs.docker.com/engine/reference/run/#detached-vs-foreground)。
+ [https://docs.docker.com/engine/reference/run/#name---name](https://docs.docker.com/engine/reference/run/#name---name)。运行名为 `aws-iot-greengrass` 的容器
+ [https://docs.docker.com/storage/volumes/](https://docs.docker.com/storage/volumes/)。 将卷挂载到 Docker 容器中，使配置文件和证书文件可供在容器内 Amazon IoT Greengrass 运行。
+ [https://docs.docker.com/engine/reference/commandline/run/#env](https://docs.docker.com/engine/reference/commandline/run/#env)。 （可选）指定环境文件以设置将传递给 Docker 容器内的 C Amazon IoT Greengrass ore 软件安装程序的环境变量。只有在创建[环境文件](run-greengrass-docker-manual-provisioning.md#create-env-file-manual-provisioning)来设置环境变量时，才需要此参数。如果您没有创建环境文件，则可以直接在 Docker run 命令中使用 `--env` 参数设置环境变量。
+ [https://docs.docker.com/engine/reference/commandline/run/#publish](https://docs.docker.com/engine/reference/commandline/run/#publish)。（可选）将 8883 容器端口发布到主机。如果您想通过 MQTT 进行连接和通信，需要使用此参数，因为 Amazon IoT Greengrass 将端口 8883 用于 MQTT 流量。要打开其它端口，请使用其它 `-p` 参数。
**注意**
要以更高的安全性运行 Docker 容器，您可以使用 `--cap-drop` 和 `--cap-add` 参数选择性地为容器启用 Linux 功能。有关更多信息，请参阅 Docker 文档中的[运行时权限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。
1. 从主机设备上的 `./greengrass-v2-credentials` 中移除凭证。
```
rm -rf ./greengrass-v2-credentials
```
**重要**
您之所以移除这些凭证，是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证，Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 Amazon 凭证，请使用令牌交换服务。有关更多信息，请参阅 [与 Amazon 服务交互](interact-with-aws-services.md)。
------
#### [ Docker Compose ]
1. 使用文本编辑器创建名为 `docker-compose.yml` 的 Docker Compose 文件。
例如，在基于 Linux 的系统上，您可以运行以下命令来使用 GNU nano 在当前目录中创建 `docker-compose.yml`。
```
nano docker-compose.yml
```
**注意**
您也可以从中下载和使用 Amazon提供的 Compose 文件的最新版本。[GitHub](https://github.com/aws-greengrass/aws-greengrass-docker/releases/)
1. 将以下内容添加到 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 软件安装程序的环境变量。只有在创建[环境文件](run-greengrass-docker-manual-provisioning.md#create-env-file-manual-provisioning)来设置环境变量时，才需要该参数。如果您没有创建环境文件，则可以使用[环境](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment)参数直接在 Compose 文件中设置变量。
**注意**
要以更高的安全性运行 Docker 容器，您可以使用 Compose 文件中的 `cap_drop` 和 `cap_add` 选择性地为容器启用 Linux 功能。有关更多信息，请参阅 Docker 文档中的[运行时权限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。
1. 运行以下命令来启动 Docker 容器。
```
docker-compose -f docker-compose.yml up
```
1. 从主机设备上的 `./greengrass-v2-credentials` 中移除凭证。
```
rm -rf ./greengrass-v2-credentials
```
**重要**
您之所以移除这些凭证，是因为它们提供了核心设备仅在设置期间才需要的广泛权限。如果您不移除这些凭证，Greengrass 组件以及容器中运行的其它进程可以访问这些凭证。如果您需要向 Greengrass 组件提供 Amazon 凭证，请使用令牌交换服务。有关更多信息，请参阅 [与 Amazon 服务交互](interact-with-aws-services.md)。
------
## 后续步骤
Amazon IoT Greengrass 核心软件现在在 Docker 容器中运行。运行以下命令以检索当前运行容器的容器 ID。
```
docker ps
```
然后，您可以运行以下命令来访问容器并浏览容器内运行的 Amazon IoT Greengrass Core 软件。
```
docker exec -it container-id /bin/bash
```
有关创建简单组件的信息，请参阅[教程：Amazon IoT Greengrass V2 入门](getting-started.md)中的[第 4 步：在设备上开发和测试组件](create-first-component.md)。
**注意**
当您使用 `docker exec` 在 Docker 容器内运行命令时，这些命令不会记录在 Docker 日志中。要将命令记录在 Docker 日志中，请将交互式 Shell 附加到 Docker 容器。有关更多信息，请参阅 [将交互式 Shell 附加到 Docker 容器](docker-troubleshooting.md#debugging-docker-attach-shell)。
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 日志](docker-troubleshooting.md#debugging-docker-persist-logs)。
要停止正在运行的 Amazon IoT Greengrass Docker 容器，请运行`docker stop`或`docker-compose -f docker-compose.yml stop`。此操作可将 `SIGTERM` 发送到 Greengrass 进程，并关闭容器中启动的所有关联进程。Docker 容器通过 `docker-init` 可执行文件初始化为进程 PID 1，这有助于移除任何剩余的僵尸进程。有关更多信息，请参阅 Docker 文档中的[指定 init 进程](https://docs.docker.com/engine/reference/run/#specify-an-init-process)。
有关对在 Docker 容器中运行 Amazon IoT Greengrass 的问题进行排查的信息，请参阅[在 Docker Amazon IoT Greengrass 容器中进行故障排除](docker-troubleshooting.md)。