本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 运行 Docker 容器
您可以将 AWS IoT Greengrass 组件配置为使用存储在以下位置的映像运行 [Docker](https://www.docker.com/) 容器：
+ Amazon Elastic Container Registry（Amazon ECR）中的公共和私有映像存储库
+ 公共 Docker Hub 存储库
+ 公共 Docker 可信注册表
+ S3 存储桶
在您的自定义组件中，将 Docker 映像 URI 作为构件包括在内，以检索映像并在核心设备上运行。对于 Amazon ECR 和 Docker Hub 映像，您可以使用 [Docker 应用程序管理器](docker-application-manager-component.md)组件下载映像并管理私有 Amazon ECR 存储库的凭证。
**Topics**
+ [要求](#run-docker-container-requirements)
+ [通过 Amazon ECR 或 Docker Hub 中的公共映像运行 Docker 容器](#run-docker-container-public-ecr-dockerhub)
+ [通过 Amazon ECR 中的私有映像运行 Docker 容器](#run-docker-container-private-ecr)
+ [通过 Amazon S3 中的映像运行 Docker 容器](#run-docker-container-s3)
+ [在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
+ [在 Docker 容器组件中使用 AWS 凭证 (Linux)](#docker-container-token-exchange-service)
+ [在 Docker 容器组件中使用流管理器（Linux）](#docker-container-stream-manager)
## 要求
要在组件中运行 Docker 容器，您需要：
+ Greengrass 核心设备。如果没有，请参阅[教程：AWS IoT Greengrass V2 入门](getting-started.md)。
+ Greengrass 核心设备上安装的 [Docker Engine](https://docs.docker.com/engine/) 1.9.1 或更高版本。版本 20.10 是经验证可与 AWS IoT Greengrass 核心软件配合使用的最新版本。在部署运行 Docker 容器的组件之前，必须直接在核心设备上安装 Docker。
**提示**
您还可以将核心设备配置为在组件安装时安装 Docker Engine。例如，以下安装脚本可在加载 Docker 映像之前安装 Docker Engine。此安装脚本适用于基于 Debian 的 Linux 发行版，例如 Ubuntu。如果您使用此命令将组件配置为安装 Docker Engine，则可能需要在生命周期脚本中将 `RequiresPrivilege` 设置为 `true` 才能运行安装和 `docker` 命令。有关更多信息，请参阅 [AWS IoT Greengrass 组件配方参考](component-recipe-reference.md)。
```
apt-get install docker-ce docker-ce-cli containerd.io && docker load -i {artifacts:path}/hello-world.tar
```
+ 运行 Docker 容器组件的系统用户必须具有根或管理员权限，或者您必须将 Docker 配置为以非根用户或非管理员用户身份运行。
+ 在 Linux 设备上，您可向 `docker` 组中添加一个用户以调用 `docker` 命令，无需 `sudo`。
+ 在 Windows 设备上，您可将用户添加到 `docker-users` 组中以调用 `docker` 命令，无需管理员权限。
------
#### [ Linux or Unix ]
要添加 `ggc_user` 或您用于运行 Docker 容器组件的非根用户至 `docker` 组中，请运行以下命令：
```
sudo usermod -aG docker ggc_user
```
有关更多信息，请参阅[以非根用户身份管理 Docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)。
------
#### [ Windows Command Prompt (CMD) ]
要添加 `ggc_user` 或您用于运行 Docker 容器组件的非根用户至 `docker-users` 组中，请以管理员身份运行以下命令：
```
net localgroup docker-users ggc_user /add
```
------
#### [ Windows PowerShell ]
要添加 `ggc_user` 或您用于运行 Docker 容器组件的非根用户至 `docker-users` 组中，请以管理员身份运行以下命令：
```
Add-LocalGroupMember -Group docker-users -Member ggc_user
```
------
+ [作为卷挂载](https://docs.docker.com/storage/volumes/)在 Docker 容器中的 Docker 容器组件访问的文件。
+ 如果您[将 AWS IoT Greengrass Core 软件配置为使用网络代理](configure-greengrass-core-v2.md#configure-alpn-network-proxy)，则必须[将 Docker 配置为使用相同的代理服务器](https://docs.docker.com/network/proxy/)。
除这些要求外，您还必须满足以下要求（如果其适用于您的环境）：
+ 要使用 [Docker Compose](https://docs.docker.com/compose/) 创建和启动 Docker 容器，请在 Greengrass 核心设备上安装 Docker Compose，然后将您的 Docker Compose 文件上传到 S3 桶。您必须将 Compose 文件存储在 AWS 账户 与 AWS 区域 组件相同的 S3 存储桶中。有关在自定义组件中使用 `docker-compose up` 命令的示例，请参阅[通过 Amazon ECR 或 Docker Hub 中的公共映像运行 Docker 容器](#run-docker-container-public-ecr-dockerhub)。
+ 如果您在网络代理 AWS IoT Greengrass 后面运行，请将 Docker 守护程序配置为使用[代理服务器](https://docs.docker.com/network/proxy/)。
+ 如果您的 Docker 映像存储在 Amazon ECR 或 Docker Hub 中，请将 [Docker 组件管理器](docker-application-manager-component.md)组件作为依赖关系包含在 Docker 容器组件中。在部署组件之前，必须在核心设备上启动 Docker 进程守护程序。
此外，还要将图像 URIs 作为组件工件包括在内。图片 URIs 必须采用以下示例所示的格式`docker:registry/image[:tag|@digest]`：
+ Amazon ECR 私有映像：`docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]`
+ Amazon ECR 公共映像：`docker:public.ecr.aws/repository/image[:tag|@digest]`
+ Docker Hub 公共映像：`docker:name[:tag|@digest]`
有关通过存储在公共存储库中的映像运行 Docker 容器的更多信息，请参阅[通过 Amazon ECR 或 Docker Hub 中的公共映像运行 Docker 容器](#run-docker-container-public-ecr-dockerhub)。
+ 如果您的 Docker 映像存储在 Amazon ECR 私有存储库中，则必须将令牌交换服务组件作为依赖关系包含在 Docker 容器组件中。此外，[Greengrass 设备角色](device-service-role.md)必须允许执行 `ecr:GetAuthorizationToken`、`ecr:BatchGetImage` 和 `ecr:GetDownloadUrlForLayer` 操作，如以下示例 IAM 策略中所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
```
------
有关通过存储在 Amazon ECR 私有存储库中的映像运行 Docker 容器的信息，请参阅[通过 Amazon ECR 中的私有映像运行 Docker 容器](#run-docker-container-private-ecr)。
+ 要使用存储在 Amazon ECR 私有存储库中的 Docker 映像，私有存储库必须与核心设备位于同一 AWS 区域 位置。
+ 如果您的 Docker 映像或 Compose 文件存储在 S3 桶中，则 [Greengrass 设备角色](device-service-role.md)必须允许 `s3:GetObject` 权限，以便让核心设备将映像下载为组件构件，如以下示例 IAM 策略所示。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Resource": [
"*"
],
"Effect": "Allow"
}
]
}
```
------
有关通过存储在 Amazon S3 中的映像运行 Docker 容器的信息，请参阅[通过 Amazon S3 中的映像运行 Docker 容器](#run-docker-container-s3)。
+ 要在 Docker 容器组件中使用进程间通信（IPC）、 AWS 凭证或流管理器，必须在运行 Docker 容器时指定其他选项。有关更多信息，请参阅下列内容：
+ [在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
+ [在 Docker 容器组件中使用 AWS 凭证 (Linux)](#docker-container-token-exchange-service)
+ [在 Docker 容器组件中使用流管理器（Linux）](#docker-container-stream-manager)
## 通过 Amazon ECR 或 Docker Hub 中的公共映像运行 Docker 容器
本节介绍如何创建自定义组件，使其使用 Docker Compose 通过存储在 Amazon ECR 和 Docker Hub 的 Docker 映像中运行 Docker 容器。
**使用 Docker Compose 运行 Docker 容器**
1. 创建 Docker Compose 文件并将其上传到 Amazon S3 桶。确保 [Greengrass 设备角色](device-service-role.md)允许 `s3:GetObject` 权限，使设备能够访问 Compose 文件。以下示例中显示的示例撰写文件包括来自亚马逊 ECR 的亚马逊 CloudWatch 代理镜像和来自 Docker Hub 的 MySQL 镜像。
```
version: "3"
services:
cloudwatchagent:
image: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
mysql:
image: "mysql:8.0"
```
1. [在 AWS IoT Greengrass 核心设备上创建自定义组件](create-components.md)。以下示例中的配方具有以下属性：
+ 作为依赖关系的 Docker 应用程序管理器组件。此组件允许 AWS IoT Greengrass 从公共 Amazon ECR 和 Docker Hub 存储库下载映像。
+ 指定公共 Amazon ECR 资源库中 Docker 映像的组件构件。
+ 指定公共 Docker Hub 资源库中 Docker 映像的组件构件。
+ 指定 Docker Compose 文件的组件构件，该文件包含要运行的 Docker 映像的容器。
+ 使用 [docker-compose up](https://docs.docker.com/compose/reference/up/) 通过指定的映像创建和启动容器的生命周期运行脚本。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyDockerComposeComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker-compose -f {artifacts:path}/docker-compose.yaml up"
},
"Artifacts": [
{
"URI": "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
},
{
"URI": "docker:mysql:8.0"
},
{
"URI": "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyDockerComposeComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker-compose -f {artifacts:path}/docker-compose.yaml up
Artifacts:
- URI: "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
- URI: "docker:mysql:8.0"
- URI: "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
```
------
**注意**
要在 Docker 容器组件中使用进程间通信（IPC）、 AWS 凭证或流管理器，必须在运行 Docker 容器时指定其他选项。有关更多信息，请参阅下列内容：
[在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
[在 Docker 容器组件中使用 AWS 凭证 (Linux)](#docker-container-token-exchange-service)
[在 Docker 容器组件中使用流管理器（Linux）](#docker-container-stream-manager)
1. [测试组件](test-components.md)，以验证其是否按预期运行。
**重要**
在部署组件之前，必须安装并启动 Docker 进程守护程序。
在本地部署组件后，您可以运行 [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令来验证您的容器是否运行。
```
docker container ls
```
1. 组件准备就绪后，将该组件上传 AWS IoT Greengrass 到以部署到其他核心设备。有关更多信息，请参阅 [发布组件以部署到您的核心设备](publish-components.md)。
## 通过 Amazon ECR 中的私有映像运行 Docker 容器
本节介绍如何创建自定义组件，使其通过存储在 Amazon ECR 私有存储库中的 Docker 映像运行 Docker 容器。
**运行 Docker 容器**
1. [在 AWS IoT Greengrass 核心设备上创建自定义组件](create-components.md)。使用以下配方示例，它具有以下属性：
+ 作为依赖关系的 Docker 应用程序管理器组件。此组件允许 AWS IoT Greengrass 管理从私有存储库下载映像的凭证。
+ 作为依赖关系的令牌交换服务组件。此组件允许检索 AWS 凭证 AWS IoT Greengrass 以与 Amazon ECR 进行交互。
+ 指定私有 Amazon ECR 存储库中 Docker 映像的组件构件。
+ 使用 [docker run](https://docs.docker.com/engine/reference/commandline/run/) 从映像创建和启动容器的生命周期运行脚本。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyPrivateDockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from a private Amazon ECR image.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.DockerApplicationManager": {
"VersionRequirement": "~2.0.0"
},
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "~2.0.0"
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"Run": "docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
},
"Artifacts": [
{
"URI": "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyPrivateDockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from a private Amazon ECR image.'
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.DockerApplicationManager:
VersionRequirement: ~2.0.0
aws.greengrass.TokenExchangeService:
VersionRequirement: ~2.0.0
Manifests:
- Platform:
os: all
Lifecycle:
Run: docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]
Artifacts:
- URI: "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
```
------
**注意**
要在 Docker 容器组件中使用进程间通信（IPC）、 AWS 凭证或流管理器，必须在运行 Docker 容器时指定其他选项。有关更多信息，请参阅下列内容：
[在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
[在 Docker 容器组件中使用 AWS 凭证 (Linux)](#docker-container-token-exchange-service)
[在 Docker 容器组件中使用流管理器（Linux）](#docker-container-stream-manager)
1. [测试组件](test-components.md)，以验证其是否按预期运行。
**重要**
在部署组件之前，必须安装并启动 Docker 进程守护程序。
在本地部署组件后，您可以运行 [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令来验证您的容器是否运行。
```
docker container ls
```
1. 将组件上传到 AWS IoT Greengrass 以部署到其他核心设备。有关更多信息，请参阅 [发布组件以部署到您的核心设备](publish-components.md)。
## 通过 Amazon S3 中的映像运行 Docker 容器
本节介绍如何通过存储在 Amazon S3 中的 Docker 映像在组件中运行 Docker 容器。
**通过 Amazon S3 中的映像在组件中运行 Docker 容器**
1. 运行 [docker save](https://docs.docker.com/engine/reference/commandline/save/) 命令以创建 Docker 容器的备份。您需要将此备份作为组件构件提供，以便在 AWS IoT Greengrass上运行容器。*hello-world*替换为图像的名称，然后*hello-world.tar*替换为要创建的存档文件的名称。
```
docker save hello-world > artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
```
1. [在 AWS IoT Greengrass 核心设备上创建自定义组件](create-components.md)。使用以下配方示例，它具有以下属性：
+ 使用 [docker load](https://docs.docker.com/engine/reference/commandline/load/) 从存档中加载 Docker 映像的生命周期安装脚本。
+ 使用 [docker run](https://docs.docker.com/engine/reference/commandline/run/) 从映像创建和启动容器的生命周期运行脚本。`--rm` 选项将在容器退出时对其进行清理。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
}
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
```
------
**注意**
要在 Docker 容器组件中使用进程间通信（IPC）、 AWS 凭证或流管理器，必须在运行 Docker 容器时指定其他选项。有关更多信息，请参阅下列内容：
[在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
[在 Docker 容器组件中使用 AWS 凭证 (Linux)](#docker-container-token-exchange-service)
[在 Docker 容器组件中使用流管理器（Linux）](#docker-container-stream-manager)
1. [测试组件](test-components.md)，以验证其是否按预期运行。
在本地部署组件后，您可以运行 [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) 命令来验证您的容器是否运行。
```
docker container ls
```
1. 组件准备就绪后，将 Docker 映像存档上传到 S3 桶，然后将其 URI 添加到组件配方中。然后，您可以将组件上传到 AWS IoT Greengrass 以部署到其他核心设备。有关更多信息，请参阅 [发布组件以部署到您的核心设备](publish-components.md)。
完成后，组件配方应类似于以下示例。
------
#### [ JSON ]
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.MyS3DockerComponent",
"ComponentVersion": "1.0.0",
"ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
"ComponentPublisher": "Amazon",
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": {
"Script": "docker load -i {artifacts:path}/hello-world.tar"
},
"Run": {
"Script": "docker run --rm hello-world"
}
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar"
}
]
}
]
}
```
------
#### [ YAML ]
```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.MyS3DockerComponent
ComponentVersion: '1.0.0'
ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
ComponentPublisher: Amazon
Manifests:
- Platform:
os: linux
Lifecycle:
install:
Script: docker load -i {artifacts:path}/hello-world.tar
Run:
Script: docker run --rm hello-world
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
```
------
## 在 Docker 容器组件中使用进程间通信
您可以使用中的 Greengrass 进程间通信 (IPC) 库与 Greengrass 核、 AWS IoT Device SDK 其他 Greengrass 组件以及进行通信。 AWS IoT Core有关更多信息，请参阅 [使用 AWS IoT Device SDK 与 Greengrass 原子核、其他组件进行通信，以及 AWS IoT Core与 Greengrass 核、其他组件进行通信 AWS IoT Core](interprocess-communication.md)。
要在 Docker 容器组件中使用 IPC，必须使用以下参数运行 Docker 容器：
+ 将 IPC 套接字挂载在容器中。Greengrass Nucleus在 `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` 环境变量中提供 IPC 套接字文件路径。
+ 将 `SVCUID` 和 `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` 环境变量设置为 Greengrass Nucleus为组件提供的值。您的组件使用这些环境变量来验证与 Greengrass Nucleus的连接。
**Example 示例配方：将 MQTT 消息发布到 AWS IoT Core (Python)**
以下配方定义了一个将 MQTT 消息发布到的 Docker 容器组件示例。 AWS IoT Core该配方具有以下属性：
+ 一种授权策略 (`accessControl`)，允许组件向其发布 AWS IoT Core 有关所有主题的 MQTT 消息。有关更多信息，请参阅 [授权组件执行 IPC 操作](interprocess-communication.md#ipc-authorization-policies) 和 [AWS IoT Core MQTT IPC 授权](ipc-iot-core-mqtt.md#ipc-iot-core-mqtt-authorization)。
+ 将 Docker 映像指定为 Amazon S3 中的 TAR 存档的组件构件。
+ 从 TAR 存档中加载 Docker 映像的生命周期安装脚本。
+ 通过映像运行 Docker 容器的生命周期运行脚本。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有以下参数：
+ `-v` 参数将 Greengrass IPC 套接字挂载在容器中。
+ 前两个 `-e` 参数在 Docker 容器中设置所需的环境变量。
+ 其他 `-e` 参数设置本示例使用的环境变量。
+ `--rm` 参数将在容器退出时对其进行清理。
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.PublishToIoTCore",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses interprocess communication to publish an MQTT message to IoT Core.",
"ComponentPublisher": "Amazon",
"ComponentConfiguration": {
"DefaultConfiguration": {
"topic": "test/topic/java",
"message": "Hello, World!",
"qos": "1",
"accessControl": {
"aws.greengrass.ipc.mqttproxy": {
"com.example.python.docker.PublishToIoTCore:pubsub:1": {
"policyDescription": "Allows access to publish to IoT Core on all topics.",
"operations": [
"aws.greengrass#PublishToIoTCore"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "all"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/publish-to-iot-core.tar",
"Run": "docker run -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e SVCUID -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e MQTT_TOPIC=\"{configuration:/topic}\" -e MQTT_MESSAGE=\"{configuration:/message}\" -e MQTT_QOS=\"{configuration:/qos}\" --rm publish-to-iot-core"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.PublishToIoTCore
ComponentVersion: 1.0.0
ComponentDescription: Uses interprocess communication to publish an MQTT message to IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
DefaultConfiguration:
topic: 'test/topic/java'
message: 'Hello, World!'
qos: '1'
accessControl:
aws.greengrass.ipc.mqttproxy:
'com.example.python.docker.PublishToIoTCore:pubsub:1':
policyDescription: Allows access to publish to IoT Core on all topics.
operations:
- 'aws.greengrass#PublishToIoTCore'
resources:
- '*'
Manifests:
- Platform:
os: all
Lifecycle:
install: 'docker load -i {artifacts:path}/publish-to-iot-core.tar'
Run: |
docker run \
-v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e SVCUID \
-e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
-e MQTT_TOPIC="{configuration:/topic}" \
-e MQTT_MESSAGE="{configuration:/message}" \
-e MQTT_QOS="{configuration:/qos}" \
--rm publish-to-iot-core
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar
```
## 在 Docker 容器组件中使用 AWS 凭证 (Linux)
您可以使用[令牌交换服务组件](token-exchange-service-component.md)与 Greengrass 组件中的 AWS 服务进行交互。此组件使用本地容器服务器提供来自核心设备的[令牌交换角色](device-service-role.md)的 AWS 凭证。有关更多信息，请参阅 [与 AWS 服务交互](interact-with-aws-services.md)。
**注意**
本节中的示例仅适用于 Linux 核心设备。
要在 Docker 容器组件中使用来自令牌交换服务的 AWS 凭证，必须使用以下参数运行 Docker 容器：
+ 使用 `--network=host` 参数提供对主机网络的访问权限。此选项使 Docker 容器能够连接到本地令牌交换服务以检索 AWS 凭据。此参数仅适用于 Linux 版 Docker。
**警告**
此选项允许容器访问主机上的所有本地网络接口，因此与不能访问主机网络的 Docker 容器相比，该选项的安全性较低。在开发和运行使用此选项的 Docker 容器组件时，请考虑这一点。有关更多信息，请参阅 *Docker 文档*中的[网络：主机](https://docs.docker.com/engine/reference/run/#network-host)。
+ 将`AWS_CONTAINER_CREDENTIALS_FULL_URI`和`AWS_CONTAINER_AUTHORIZATION_TOKEN`环境变量设置为 Greengrass 核为组件提供的值。 AWS SDKs 使用这些环境变量来检索 AWS 凭证。
**Example 示例配方：在 Docker 容器组件中列出 S3 桶（Python）**
以下配方定义了一个可以列出您 AWS 账户中 S3 桶的示例 Docker 容器组件。该配方具有以下属性：
+ 作为依赖关系的令牌交换服务组件。这种依赖关系使组件能够检索 AWS 凭证以与其他 AWS 服务进行交互。
+ 将 Docker 映像指定为 Amazon S3 中的 TAR 存档的组件构件。
+ 从 TAR 存档中加载 Docker 映像的生命周期安装脚本。
+ 通过映像运行 Docker 容器的生命周期运行脚本。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有以下参数：
+ `--network=host` 参数提供容器对主机网络的访问权限，以便容器可以连接到令牌交换服务。
+ `-e` 参数在 Docker 容器中设置所需的环境变量。
+ `--rm` 参数将在容器退出时对其进行清理。
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.ListS3Buckets",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Uses the token exchange service to lists your S3 buckets.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.TokenExchangeService": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/list-s3-buckets.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e AWS_CONTAINER_CREDENTIALS_FULL_URI --rm list-s3-buckets"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.ListS3Buckets
ComponentVersion: 1.0.0
ComponentDescription: Uses the token exchange service to lists your S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.TokenExchangeService:
VersionRequirement: ^2.0.0
DependencyType: HARD
Manifests:
- Platform:
os: linux
Lifecycle:
install: 'docker load -i {artifacts:path}/list-s3-buckets.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e AWS_CONTAINER_CREDENTIALS_FULL_URI \
--rm list-s3-buckets
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar
```
## 在 Docker 容器组件中使用流管理器（Linux）
您可以使用[流管理器组件](stream-manager-component.md)来管理 Greengrass 组件中的数据流。此组件使您能够处理数据流并将大量物联网数据传输到. AWS 云 AWS IoT Greengrass 提供了用于与流管理器组件交互的流管理器 SDK。有关更多信息，请参阅 [管理 Greengrass 核心设备上的数据流](manage-data-streams.md)。
**注意**
本节中的示例仅适用于 Linux 核心设备。
要在 Docker 容器组件中使用流管理器 SDK，必须使用以下参数运行 Docker 容器：
+ 使用 `--network=host` 参数提供对主机网络的访问权限。此选项使 Docker 容器能够通过本地 TLS 连接与流管理器组件进行交互。此参数仅适用于 Linux 版 Docker
**警告**
此选项允许容器访问主机上的所有本地网络接口，因此与不能访问主机网络的 Docker 容器相比，该选项的安全性较低。在开发和运行使用此选项的 Docker 容器组件时，请考虑这一点。有关更多信息，请参阅 *Docker 文档*中的[网络：主机](https://docs.docker.com/engine/reference/run/#network-host)。
+ 如果您将流管理器组件配置为需要身份验证（这是默认行为），请将 `AWS_CONTAINER_CREDENTIALS_FULL_URI` 环境变量设置为 Greengrass Nucleus为组件提供的值。有关更多信息，请参阅[流管理器配置](stream-manager-component.md#stream-manager-component-configuration)。
+ 如果将流管理器组件配置为使用非默认端口，请使用[进程间通信（IPC）](interprocess-communication.md)从流管理器组件配置中获取该端口。要使用 IPC，您必须使用其他选项运行 Docker 容器。有关更多信息，请参阅下列内容：
+ [在应用程序代码中连接至流管理器](use-stream-manager-in-custom-components.md#connect-to-stream-manager)
+ [在 Docker 容器组件中使用进程间通信](#docker-container-ipc)
**Example 示例配方：将文件流式传输到 Docker 容器组件中的 S3 桶（Python）**
以下配方定义了一个用于创建文件并将其流式传输到 S3 桶的示例 Docker 容器组件。该配方具有以下属性：
+ 作为依赖关系的流管理器组件。此依赖关系使组件能够使用流管理器 SDK 与流管理器组件进行交互。
+ 将 Docker 映像指定为 Amazon S3 中的 TAR 存档的组件构件。
+ 从 TAR 存档中加载 Docker 映像的生命周期安装脚本。
+ 通过映像运行 Docker 容器的生命周期运行脚本。[Docker run](https://docs.docker.com/engine/reference/run/) 命令具有以下参数：
+ `--network=host` 参数提供容器对主机网络的访问权限，以便容器可以连接到流管理器组件。
+ 第一个 `-e` 参数在 Docker 容器中设置所需的 `AWS_CONTAINER_AUTHORIZATION_TOKEN` 环境变量。
+ 其他 `-e` 参数设置本示例使用的环境变量。
+ `-v` 参数将组件的[工作文件夹](component-recipe-reference.md#component-recipe-work-path)挂载到容器中。此示例在工作文件夹中创建一个文件，以便使用流管理器将该文件上传到 Amazon S3。
+ `--rm` 参数将在容器退出时对其进行清理。
```
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.python.docker.StreamFileToS3",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Creates a text file and uses stream manager to stream the file to S3.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.StreamManager": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"ComponentConfiguration": {
"DefaultConfiguration": {
"bucketName": ""
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "docker load -i {artifacts:path}/stream-file-to-s3.tar",
"Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e BUCKET_NAME=\"{configuration:/bucketName}\" -e WORK_PATH=\"{work:path}\" -v {work:path}:{work:path} --rm stream-file-to-s3"
},
"Artifacts": [
{
"URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar"
}
]
}
]
}
```
```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.StreamFileToS3
ComponentVersion: 1.0.0
ComponentDescription: Creates a text file and uses stream manager to stream the file to S3.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.StreamManager:
VersionRequirement: ^2.0.0
DependencyType: HARD
ComponentConfiguration:
DefaultConfiguration:
bucketName: ''
Manifests:
- Platform:
os: linux
Lifecycle:
install: 'docker load -i {artifacts:path}/stream-file-to-s3.tar'
Run: |
docker run \
--network=host \
-e AWS_CONTAINER_AUTHORIZATION_TOKEN \
-e BUCKET_NAME="{configuration:/bucketName}" \
-e WORK_PATH="{work:path}" \
-v {work:path}:{work:path} \
--rm stream-file-to-s3
Artifacts:
- URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar
```