AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 Docker 容器中运行 AWS IoT Greengrass

此功能适用于 AWS IoT Greengrass Core v1.7 及更高版本。

AWS IoT Greengrass 可以配置为在 Docker 容器中运行。

注意

无法在 Docker 容器中使用连接器、本地设备和卷资源以及本地机器学习模型资源。当 Greengrass 组的 Lambda 运行时环境设置为 No container (无容器) 时(此时需要在 Docker 容器中运行 AWS IoT Greengrass),这些功能不受支持。

您可以通过 Amazon CloudFront(安装了 AWS IoT Greengrass 核心软件和依赖项)下载 Dockerfile。要修改 Docker 镜像以便在不同平台架构上运行或减少 Docker 镜像的大小,请参阅 Docker 程序包下载中的 README 文件。

为了帮助您快速入门和体验 AWS IoT Greengrass,AWS 还提供了一个预构建的 Docker 镜像,它安装了 AWS IoT Greengrass 核心软件和依赖项。您可以从 Docker HubAmazon Elastic Container Registry (Amazon ECR) 下载预构建的映像并在 Windows、macOS 和 Linux (x86_64) 平台上运行它。本主题介绍如何从 Amazon ECR 下载映像。它包含以下步骤:

先决条件

要完成本教程,必须在您的主机上安装以下软件和版本。

  • Docker,版本 18.09 或更高版本。早期版本也可使用,但首选版本为 18.09 或更高版本。

  • Python,版本 3.6 或更高版本。

  • pip 版本 18.1 或更高版本。

  • AWS CLI 1.16 或更高版本。

    • 要安装和配置 CLI,请参阅 AWS Command Line Interface 用户指南 中的安装 AWS Command Line Interface配置 AWS CLI

    • 要升级到 AWS CLI 的最新版本,请运行以下命令:

      pip install awscli --upgrade --user

    注意

    如果您在 Windows 上使用 AWS CLI 的 MSI 安装,请注意以下事项:

    • 如果安装过程中未能安装 botocore,请尝试使用 Python 和 pip 安装

    • 要升级到更新的 CLI 版本,您必须重复 MSI 安装过程。

步骤 1:从 Amazon ECR 获取 AWS IoT Greengrass 容器镜像

AWS IoT Greengrass 提供已安装 AWS IoT Greengrass 核心软件的 Docker 镜像。有关演示如何从 Amazon ECR 拉取容器镜像的步骤,请选择您的操作系统:

拉取容器镜像 (Linux)

在计算机终端中运行以下命令。

  1. 获取所需的登录命令,其中包含用于 Amazon ECR 中的 AWS IoT Greengrass 注册表的授权令牌。

    aws ecr get-login --registry-ids 216483018798 --no-include-email --region us-west-2

    输出是您将在下一步中使用的 docker login 命令。

  2. 通过从 get-login 输出运行 docker login 命令,针对注册表中的 AWS IoT Greengrass 容器映像验证 Docker 客户端的身份。该命令应类似于以下示例。

    docker login -u AWS -p abCzYZ123... https://216483018798.dkr.ecr.us-west-2.amazonaws.com
  3. 检索 AWS IoT Greengrass 容器映像。

    docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    注意

    latest 标签对应于最新的 AWS IoT Greengrass 容器。您还可以从存储库中拉取其他版本。要列出 AWS IoT Greengrass 存储库中可用的所有映像,请使用 aws ecr list-images 命令。例如:

    aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
  4. 启用符号链接和硬链接保护。如果您尝试在容器中运行 AWS IoT Greengrass,则只能启用当前引导的设置。

    注意

    您可能需要使用 sudo 才能运行这些命令。

    • 要仅启用当前引导的设置,请执行以下操作:

      echo 1 > /proc/sys/fs/protected_hardlinks echo 1 > /proc/sys/fs/protected_symlinks
    • 要使设置在重新启动后保持不变,请执行以下操作:

      echo '# AWS Greengrass' >> /etc/sysctl.conf echo 'fs.protected_hardlinks = 1' >> /etc/sysctl.conf echo 'fs.protected_symlinks = 1' >> /etc/sysctl.conf sysctl -p
  5. 启用 IPv4 网络转发,这是 AWS IoT Greengrass 云部署和 MQTT 通信在 Linux 上运行所必需的。在 /etc/sysctl.conf 文件中,将 net.ipv4.ip_forward 设置为 1,然后重新加载 sysctls

    sudo nano /etc/sysctl.conf # set this net.ipv4.ip_forward = 1 sudo sysctl -p

    注意

    您可以使用您选择的编辑器而不是 nano。

拉取容器镜像 (macOS)

在计算机终端中运行以下命令。

  1. 获取所需的登录命令,其中包含用于 Amazon ECR 中的 AWS IoT Greengrass 注册表的授权令牌。

    aws ecr get-login --registry-ids 216483018798 --no-include-email --region us-west-2

    输出是您将在下一步中使用的 docker login 命令。

  2. 通过从 get-login 输出运行 docker login 命令,针对注册表中的 AWS IoT Greengrass 容器映像验证 Docker 客户端的身份。该命令应类似于以下示例。

    docker login -u AWS -p abCzYZ123... https://216483018798.dkr.ecr.us-west-2.amazonaws.com
  3. 检索 AWS IoT Greengrass 容器映像。

    docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    注意

    latest 标签对应于最新的 AWS IoT Greengrass 容器。您还可以从存储库中拉取其他版本。要列出 AWS IoT Greengrass 存储库中可用的所有映像,请使用 aws ecr list-images 命令。例如:

    aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
拉取容器镜像 (Windows)

在命令提示符中运行以下命令。Docker 桌面必须先处于运行状态,然后您才能在 Windows 上使用 Docker 命令。

  1. 获取所需的登录命令,其中包含用于 Amazon ECR 中的 AWS IoT Greengrass 注册表的授权令牌。

    aws ecr get-login --registry-ids 216483018798 --no-include-email --region us-west-2

    输出是您将在下一步中使用的 docker login 命令。

  2. 通过从 get-login 输出运行 docker login 命令,针对注册表中的 AWS IoT Greengrass 容器映像验证 Docker 客户端的身份。该命令应类似于以下示例。

    docker login -u AWS -p abCzYZ123... https://216483018798.dkr.ecr.us-west-2.amazonaws.com
  3. 检索 AWS IoT Greengrass 容器映像。

    docker pull 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    注意

    latest 标签对应于最新的 AWS IoT Greengrass 容器。您还可以从存储库中拉取其他版本。要列出 AWS IoT Greengrass 存储库中可用的所有映像,请使用 aws ecr list-images 命令。例如:

    aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass

步骤 2:创建和配置 Greengrass 组和核心

虽然 Docker 镜像已安装 AWS IoT Greengrass 核心软件,但您必须创建 Greengrass 组和核心。这包括下载证书和核心配置文件。

步骤 3:本地运行 AWS IoT Greengrass

配置您的组后,便能配置和启动核心。有关演示如何执行此操作的步骤,请选择您的操作系统:

本地运行 Greengrass (Linux)

在计算机终端中运行以下命令。

  1. 将证书和配置文件(在创建 Greengrass 组时下载的)解压到一个已知位置,例如 /tmp。例如:

    tar xvzf hash-setup.tar.gz -C /tmp/
  2. 查看有关 AWS IoT 核心中的服务器身份验证的文档并选择合适的根 CA 证书。我们建议使用 Amazon Trust Services (ATS) 终端节点以及 ATS 根 CA 证书。

    运行以下命令可将根 CA 证书下载到已将证书和配置文件解压缩到的目录。证书使设备能够在 TLS 上连接至 AWS IoT。

    /tmp 替换为此目录的路径。

    重要

    您的根 CA 证书类型必须与终端匹配。使用具有 ATS 终端节点(首选)的 ATS 根 CA 证书或具有传统终端节点的 Verisign 根 CA 证书。有关更多信息,请参阅 终端节点必须与证书类型匹配

    • 对于 ATS 端点(首选),请下载恰当的 ATS 根 CA 证书。以下举例下载 AmazonRootCA1.pem

      cd /tmp/certs/ sudo wget -O root.ca.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
    • 对于遗留端点,请下载 Verisign 根 CA 证书。尽管对于本教程来说,遗留端点是可以接受的,但是我们建议您创建一个 ATS 端点并下载一个 ATS 根 CA 证书。

      cd /tmp/certs/ sudo wget -O root.ca.pem https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem

    注意

    wget -O 参数是大写字母 O。

  3. 启动 AWS IoT Greengrass 并将证书和配置文件绑定挂载到 Docker 容器中。

    /tmp 替换为您解压证书和配置文件的路径。

    docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    输出应类似于此示例:

    Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10
本地运行 Greengrass (macOS)

在计算机终端中运行以下命令。

  1. 将证书和配置文件(在创建 Greengrass 组时下载的)解压到一个已知位置,例如 /tmp。例如:

    tar xvzf hash-setup.tar.gz -C /tmp/
  2. 查看有关 AWS IoT 核心中的服务器身份验证的文档并选择合适的根 CA 证书。我们建议使用 Amazon Trust Services (ATS) 终端节点以及 ATS 根 CA 证书。

    运行以下命令可将根 CA 证书下载到已将证书和配置文件解压缩到的目录。证书使设备能够在 TLS 上连接至 AWS IoT。

    /tmp 替换为此目录的路径。

    重要

    您的根 CA 证书类型必须与终端匹配。使用具有 ATS 终端节点(首选)的 ATS 根 CA 证书或具有传统终端节点的 Verisign 根 CA 证书。有关更多信息,请参阅 终端节点必须与证书类型匹配

    • 对于 ATS 端点(首选),请下载恰当的 ATS 根 CA 证书。以下举例下载 AmazonRootCA1.pem

      cd /tmp/certs/ sudo wget -O root.ca.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
    • 对于遗留端点,请下载 Verisign 根 CA 证书。尽管对于本教程来说,遗留端点是可以接受的,但是我们建议您创建一个 ATS 端点并下载一个 ATS 根 CA 证书。

      cd /tmp/certs/ sudo wget -O root.ca.pem https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem

    注意

    wget -O 参数是大写字母 O。

  3. 启动 AWS IoT Greengrass 并将证书和配置文件绑定挂载到 Docker 容器中。

    /tmp 替换为您解压证书和配置文件的路径。

    docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    输出应类似于此示例:

    Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10
本地运行 Greengrass (Windows)
  1. 使用实用工具(如 WinZip 或 7-Zip)解压缩您在创建 Greengrass 组时下载的证书和配置文件。有关更多信息,请参阅 WinZip 文档。

    在您的计算机上找到下载的 hash-setup.tar.gz 文件,然后将此文件解压缩到 C:\Users\%USERNAME%\Downloads\

  2. 查看有关 AWS IoT 核心中的服务器身份验证的文档并选择合适的根 CA 证书。我们建议使用 Amazon Trust Services (ATS) 终端节点以及 ATS 根 CA 证书。

    运行以下命令可将根 CA 证书下载到已将证书和配置文件解压缩到的目录。证书使设备能够在 TLS 上连接至 AWS IoT。

    重要

    您的根 CA 证书类型必须与终端匹配。使用具有 ATS 终端节点(首选)的 ATS 根 CA 证书或具有传统终端节点的 Verisign 根 CA 证书。有关更多信息,请参阅 终端节点必须与证书类型匹配

    • 对于 ATS 端点(首选),请下载恰当的 ATS 根 CA 证书。以下举例下载 AmazonRootCA1.pem

      • 如果您已安装 curl,请在命令提示符处运行以下命令。

        cd C:\Users\%USERNAME%\Downloads\certs curl https://www.amazontrust.com/repository/AmazonRootCA1.pem -o root.ca.pem
      • 否则,在 Web 浏览器中,打开 Amazon Root CA 1 证书。在 C:\Users\%USERNAME%\Downloads\certs 目录(包含解压缩的证书)中将文档另存为 root.ca.pem

        注意

        根据您的浏览器,直接通过浏览器保存文件,或者将显示的密钥复制到剪贴板,然后将其保存在记事本中。

    • 对于遗留端点,请下载 Verisign 根 CA 证书。尽管对于本教程来说,遗留端点是可以接受的,但是我们建议您创建一个 ATS 端点并下载一个 ATS 根 CA 证书。

      • 如果您已安装 curl,请在命令提示符处运行以下命令。

        cd C:\Users\%USERNAME%\Downloads\certs curl https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem -o root.ca.pem
      • 否则,在 Web 浏览器中,打开 Verisign Class 3 Public Primary G5 根 CA 证书。在 C:\Users\%USERNAME%\Downloads\certs 目录(包含解压缩的证书)中将文档另存为 root.ca.pem

        注意

        根据您的浏览器,直接通过浏览器保存文件,或者将显示的密钥复制到剪贴板,然后将其保存在记事本中。

  3. 启动 AWS IoT Greengrass 并将证书和配置文件绑定挂载到 Docker 容器中。在命令提示符处运行以下命令。

    docker run --rm --init -it --name aws-iot-greengrass --entrypoint /greengrass-entrypoint.sh -v c:/Users/%USERNAME%/Downloads/certs:/greengrass/certs -v c:/Users/%USERNAME%/Downloads/config:/greengrass/config -p 8883:8883 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

    当 Docker 提示您与 Docker 守护程序共享 C:\ 驱动器时,允许它在 Docker 容器内绑定挂载 C:\ 目录。有关更多信息,请参阅 Docker 文档中的共享驱动器

    输出应类似于此示例:

    Setting up greengrass daemon Validating hardlink/softlink protection Waiting for up to 30s for Daemon to start Greengrass successfully started with PID: 10

注意

如果容器不打开 shell 并立即退出,则可以在启动映像时通过绑定挂载 Greengrass 运行时日志来调试问题。有关更多信息,请参阅在 Docker 容器之外保留 Greengrass 运行时日志

步骤 4:为 Greengrass 组配置“No container (无容器)”容器化

在 Docker 容器中运行 AWS IoT Greengrass 时,所有 Lambda 函数都必须在不进行容器化的情况下运行。在此步骤中,将组的默认容器化设置为 No container (无容器)。在首次部署组之前,您必须执行此操作。

  1. 在 AWS IoT 控制台中,选择 Greengrass,然后选择 Groups (组)

  2. 选择要更改其设置的组。

  3. 选择 Settings

  4. Lambda runtime environment (Lambda 运行时环境) 下,选择 No container (无容器)

  5. 选择 Update default Lambda execution configuration (更新默认 Lambda 执行配置)。查看确认窗口中的消息,然后选择 Continue (继续)

有关更多信息,请参阅在组中设置 Lambda 函数的默认容器化

注意

默认情况下,Lambda 函数使用组容器化设置。如果您在 AWS IoT Greengrass 运行于 Docker 容器中时覆盖任何 Lambda 函数的 No container (无容器) 设置,则部署将失败。

步骤 5:将 Lambda 函数部署到 AWS IoT Greengrass Docker 容器

您可以将长期存在的 Lambda 函数部署到 Greengrass Docker 容器。

步骤 6:(可选)部署与 Docker 容器中运行的 Greengrass 交互的设备

您还可以部署 Greengrass 设备,此设备在 Docker 容器中运行时将与 AWS IoT Greengrass 交互。

停止 AWS IoT Greengrass Docker 容器

要停止 AWS IoT Greengrass Docker 容器,请在您的终端或命令提示符处按 Ctrl+C。此操作将向 Greengrass 守护程序进程发送 SIGTERM 以停用 Greengrass 守护程序进程及其启动的所有 Lambda 进程。Docker 容器通过 /dev/init 进程初始化为 PID 1,这有助于删除任何剩余的僵尸进程。有关更多信息,请参阅 Docker 运行参考

对 Docker 容器中的 AWS IoT Greengrass 执行问题排查

使用以下信息可帮助解决与在 Docker 容器中运行 AWS IoT Greengrass 相关的问题。

症状 解决方案

在运行 aws ecr get-login 命令时,您将收到错误 Unknown options: -no-include-email

确保您已安装最新的 AWS CLI 版本(例如,运行:pip install awscli --upgrade --user)。如果您使用的是 Windows,并且您已使用 MSI 安装程序安装 CLI,则必须重复安装过程。有关更多信息,请参阅 AWS Command Line Interface 用户指南 中的在 Microsoft Windows 上安装 AWS Command Line Interface

您将在 Linux 计算机上收到错误,例如 WARNING: IPv4 is disabled. Networking will not work

按照此步骤中所述进行操作来启用 IPv4 网络转发。AWS IoT Greengrass 云部署和 MQTT 通信在未启用 IPv4 转发时将不运行。有关更多信息,请参阅 Docker 文档中的在运行时配置具有命名空间的内核参数 (sysctls)

在 Windows 计算机上运行 Docker 时,您将收到消息 Firewall Detected while Sharing Drives

请参阅错误:防火墙阻止 Windows 和容器之间的文件共享 Docker 支持问题。如果您登录虚拟私有网络 (VPN) 并且网络设置阻止挂载共享驱动器,也会出现此错误。在这种情况下,请关闭 VPN 并重新运行 Docker 容器。

对于一般 AWS IoT Greengrass 问题排查帮助,请参阅 AWS IoT Greengrass 问题排查

在 Docker 容器中调试 AWS IoT Greengrass

要调试 Docker 容器的问题,您可以保留 Greengrass 运行时日志或将交互式 shell 附加到 Docker 容器。

在 Docker 容器之外保留 Greengrass 运行时日志

绑定挂载 /greengrass/ggc/var/log 目录后,您可以运行 AWS IoT Greengrass Docker 容器。即使容器退出或被删除,日志仍然存在。

在 Linux 或 macOS 上

停止任何在主机上运行的 Greengrass Docker 容器,然后在终端中运行以下命令。这会绑定挂载 Greengrass log 目录并启动 Docker 镜像。

/tmp 替换为您解压证书和配置文件的路径。

docker run --rm --init -it --name aws-iot-greengrass \ --entrypoint /greengrass-entrypoint.sh \ -v /tmp/certs:/greengrass/certs \ -v /tmp/config:/greengrass/config \ -v /tmp/log:/greengrass/ggc/var/log \ -p 8883:8883 \ 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

然后,您可以在主机上的 /tmp/log 中检查日志,以查看 Greengrass 在 Docker 容器内运行时发生的情况。

在 Windows 上

停止任何在主机上运行的 Greengrass Docker 容器,然后在命令提示符中运行以下命令。这会绑定挂载 Greengrass log 目录并启动 Docker 镜像。

cd C:\Users\%USERNAME%\Downloads mkdir log docker run --rm --init -it --name aws-iot-greengrass --entrypoint /greengrass-entrypoint.sh -v c:/Users/%USERNAME%/Downloads/certs:/greengrass/certs -v c:/Users/%USERNAME%/Downloads/config:/greengrass/config -v c:/Users/%USERNAME%/Downloads/log:/greengrass/ggc/var/log -p 8883:8883 216483018798.dkr.ecr.us-west-2.amazonaws.com/aws-iot-greengrass:latest

然后,您可以在主机上的 C:/Users/%USERNAME%/Downloads/log 中检查日志,以查看 Greengrass 在 Docker 容器内运行时发生的情况。

将交互式 Shell 附加到 Docker 容器

您可以将交互式 shell 附加到正在运行的 AWS IoT Greengrass Docker 容器。这可以帮助您调查 Greengrass Docker 容器的状态。

在 Linux 或 macOS 上

当 Greengrass Docker 容器正在运行时,在单独的终端中运行以下命令。

docker exec -it $(docker ps -a -q -f "name=aws-iot-greengrass") /bin/bash
在 Windows 上

当 Greengrass Docker 容器正在运行时,在单独的命令提示符中运行以下命令。

docker ps -a -q -f "name=aws-iot-greengrass"

gg-container-id 替换为上一个命令的 container_id 结果。

docker exec -it gg-container-id /bin/bash