在 Docker 容器中執行 AWS IoT Greengrass - AWS IoT Greengrass

若我們提供該指南英語版本的翻譯,在有任何牴觸的狀況下請以英文版本的指南為主。其透過機器翻譯提供翻譯。

在 Docker 容器中執行 AWS IoT Greengrass

AWS IoT Greengrass 可設定在 Docker 容器中執行。

您可以透過已安裝 AWS IoT Greengrass 核心軟體和相依性的 Amazon CloudFront 下載 Dockerfile。若要修改 Docker 映像檔以在不同平台架構上執行或減少 Docker 映像檔的大小,請參閱 Docker 套件下載中的 README 檔案。

為了協助您開始嘗試 AWS IoT Greengrass,AWS 也提供已安裝 AWS IoT Greengrass 核心軟體和相依性的預先建置 Docker 映像。您可以從 Docker HubAmazon Elastic Container Registry (Amazon ECR) 下載映像。這些預先建置映像使用 Amazon Linux 2 (x86_64) 和 Alpine Linux (x86_64、Armv7l 貨 AArch64) 的基本映像。

此主題說明如何從 Amazon ECR 下載 latestAWS IoT Greengrass 影像並在 Windows、macOS 或 Linux (x86_64) 平台上執行。本主題包含以下步驟:

當您在 Docker 容器中執行 AWS IoT Greengrass 時,不支援下列功能:

  • 連接器 創新 Greengrass容器 模式。若要在 Docker 容器中執行連接器,連接器必須以 No container (無容器) 模式執行。若要尋找支援 No container (無容器) 模式的連接器,請參閱 AWS 提供的 Greengrass 連接器。其中一些連接器具有隔離模式參數,您必須設定為 No container (無容器)

  • 本機裝置和磁碟區資源。在 Docker 容器中執行的使用者定義 Lambda 函數必須直接存取核心上的裝置和磁碟區。

Greengrass 群組的 Lambda 執行時間環境設定為 No container (無容器) 時不支援這些功能,而在 Docker 容器中執行 AWS IoT Greengrass 時需要此設定。

Prerequisites

開始本教程前,您必須進行以下操作。

  • 您必須根據 AWS Command Line Interface (AWS CLI)版本。

    AWS CLI version 2
    • Docker 版本 18.09 或更新版本。早期版本也可能有效,但我們推薦使用18.09或更高版本。

    • AWS CLI 版本2.0.0或更高版本。

      注意

      稍後升級到 AWS CLI Windows計算機上的版本2,您必須重複 MSI安裝 流程。

    AWS CLI version 1
    • Docker 版本 18.09 或更新版本。早期版本也可能有效,但我們推薦使用18.09或更高版本。

    • Python 版本 3.6 或更新版本。

    • pip 版本 18.1 或更新版本。

    • AWS CLI 版本1.17.10或更高版本

      • 要安裝 AWS CLI 版本1,參見 安裝 AWS CLI 版本1.

      • 要配置 AWS CLI,見 配置 AWS CLI.

      • 若要更新到最新版本的 AWS CLI,請執行以下命令:

        pip install awscli --upgrade --user
      注意

      如果您使用 MSI安裝 的 AWS CLI Windows版本1,請注意以下事項:

      • 如果 AWS CLI 版本1安裝失敗,請使用 Python和pip安裝.

      • 稍後升級到 AWS CLI 版本1,您必須重複MSI安裝過程。

  • 訪問 Amazon Elastic Container Registry (Amazon ECR)資源,您必須授予以下權限。

    • Amazon ECR 要求用戶授予 ecr:GetAuthorizationToken 通過 AWS Identity and Access Management (IAM)策略,之後才能對註冊表進行身份驗證,並從 Amazon ECR 存儲庫。更多信息,請參閱 Amazon ECR 存儲庫策略示例訪問One Amazon ECR 存儲庫Amazon Elastic Container Registry 使用者指南.

步驟 1:從 Amazon ECR 取得 AWS IoT Greengrass 容器映像

AWS 提供已安裝 AWS IoT Greengrass 核心軟體的 Docker 映像。有關如何拉動 latest 圖片來自 Amazon ECR, 選擇您的操作系統:

在您的電腦終端機上執行下列命令。

  1. 登入 Amazon ECR 中的 AWS IoT Greengrass 登錄。

    aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com

    如果成功,輸出會顯示 Login Succeeded

  2. 取得 AWS IoT Greengrass 容器映像。

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

    latest 映像包含安裝在 Amazon Linux 2 基本映像上的 AWS IoT Greengrass 核心軟體的最新穩定版本。您也可以從儲存庫提取其他映像。若要尋找所有可用的映像,請檢查 Docker Hub 上的 Tags (標籤) 頁面或使用 aws ecr list-images 命令。例如:

    aws ecr list-images --region us-west-2 --registry-id 216483018798 --repository-name aws-iot-greengrass
  3. 啟用 symlink 和 hardlink 保護。如果您正在實驗在容器內執行 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
  4. 啟用 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。

在您的電腦終端機上執行下列命令。

  1. 登入 Amazon ECR 中的 AWS IoT Greengrass 登錄。

    aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com

    如果成功,輸出會顯示 Login Succeeded

  2. 取得 AWS IoT Greengrass 容器映像。

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

    latest 映像包含安裝在 Amazon Linux 2 基本映像上的 AWS IoT Greengrass 核心軟體的最新穩定版本。您也可以從儲存庫提取其他映像。若要尋找所有可用的映像,請檢查 Docker Hub 上的 Tags (標籤) 頁面或使用 aws ecr list-images 命令。例如:

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

在命令提示中執行下列命令:要在 Windows 上使用 Docker 命令,必須先執行 Docker 桌面。

  1. 登入 Amazon ECR 中的 AWS IoT Greengrass 登錄。

    aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin https://216483018798.dkr.ecr.us-west-2.amazonaws.com

    如果成功,輸出會顯示 Login Succeeded

  2. 取得 AWS IoT Greengrass 容器映像。

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

    latest 映像包含安裝在 Amazon Linux 2 基本映像上的 AWS IoT Greengrass 核心軟體的最新穩定版本。您也可以從儲存庫提取其他映像。若要尋找所有可用的映像,請檢查 Docker Hub 上的 Tags (標籤) 頁面或使用 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 群組和核心。這包括下載憑證和核心的組態檔案。

  • 請遵循 在 AWS IoT 設定 AWS IoT Greengrass 中的步驟。略過下載 AWS IoT Greengrass 核心軟體的步驟。此軟體及其執行時間相依性已在 Docker 映像檔中設定。

步驟 3. 在本機執行 AWS IoT Greengrass

設定完群組之後,您便能設定及啟動核心。如需示範執行方式的步驟,請選擇您的作業系統:

在您的電腦終端機上執行下列命令。

  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 根 CA 憑證搭配 ATS 端點 (偏好),或使用 VeriSign 根 CA 憑證搭配舊式端點。只有一些 AWS 區域能支援舊式端點。如需更多詳細資訊,請參閱 服務端點必須匹配根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.websecurity.digicert.com/content/dam/websitesecurity/digitalassets/desktop/pdfs/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem
    注意

    wget -O 參數為大寫的 O。

  3. 在 Docker 容器中啟動 AWS IoT Greengrass 並綁定掛載憑證和組態檔案。

    以解壓縮憑證和組態檔案的路徑取代 /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

在您的電腦終端機上執行下列命令。

  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 根 CA 憑證搭配 ATS 端點 (偏好),或使用 VeriSign 根 CA 憑證搭配舊式端點。只有一些 AWS 區域能支援舊式端點。如需更多詳細資訊,請參閱 服務端點必須匹配根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.websecurity.digicert.com/content/dam/websitesecurity/digitalassets/desktop/pdfs/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem
    注意

    wget -O 參數為大寫的 O。

  3. 在 Docker 容器中啟動 AWS IoT Greengrass 並綁定掛載憑證和組態檔案。

    以解壓縮憑證和組態檔案的路徑取代 /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
  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 根 CA 憑證搭配 ATS 端點 (偏好),或使用 VeriSign 根 CA 憑證搭配舊式端點。只有一些 AWS 區域能支援舊式端點。如需更多詳細資訊,請參閱 服務端點必須匹配根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 憑證。將文件以 root.ca.pem 儲存至包含解壓縮憑證的 C:\Users\%USERNAME%\Downloads\certs 目錄中。

        注意

        視瀏覽器而定,從瀏覽器直接儲存檔案或將顯示的金鑰複製到剪貼簿,然後再用 Notepad 儲存。

    • 對於舊式端點,請下載 VeriSign 根 CA 憑證。雖然就此教學課程的目的,可接受舊式端點,但建議您使用 ATS 端點及 ATS CA 憑證。

      • 如果您已安裝 Curl,請在命令提示字元執行下列命令。

        cd C:\Users\%USERNAME%\Downloads\certs curl https://www.websecurity.digicert.com/content/dam/websitesecurity/digitalassets/desktop/pdfs/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem -o root.ca.pem
      • 否則,請在 Web 瀏覽器中開啟 VeriSign 類別 3 公開主要 G5 根 CA 憑證。將文件以 root.ca.pem 儲存至包含解壓縮憑證的 C:\Users\%USERNAME%\Downloads\certs 目錄中。

        注意

        視瀏覽器而定,從瀏覽器直接儲存檔案或將顯示的金鑰複製到剪貼簿,然後再用 Notepad 儲存。

  3. 在 Docker 容器中啟動 AWS IoT Greengrass 並綁定掛載憑證和組態檔案。在命令提示中執行下列命令。

    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 執行時間日誌來偵錯問題。如需更多詳細資訊,請參閱「將 Greengrass 執行時間日誌保留在 Docker 容器之外」。

步驟 4. 爲Greengrass組配置“無容器”容器化

在 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交互的設備

您也可以部署與 Docker 容器上執行的 AWS IoT Greengrass 互動的 Greengrass 裝置。

停用 AWS IoT Greengrass Docker 容器

若要停用 AWS IoT Greengrass Docker 容器,請在終端機或命令提示字元下按 Ctrl+C。此動作會傳送 SIGTERM 至 Greengrass 協助程式處理程序,拆卸 Greengrass 協助程式處理程序及協助程式處理啟動的所有 Lambda 程序。Docker 容器是以 /dev/init 程序初始化為 PID 1,這有助於移除任何剩餘的 zombie 程序。如需詳細資訊,請參閱 Docker 執行參考

Docker 容器中 AWS IoT Greengrass 的疑難排解

請使用以下資訊針對 Docker 容器中執行 AWS IoT Greengrass 的問題進行疑難排解。

錯誤 無法從非TTY設備執行交互式登錄。

解決方案: 當您運行 aws ecr get-login-password 命令。確保您安裝了最新的 AWS CLI 版本2或版本1。我們建議您使用 AWS CLI 版本2。如需詳細資訊,請參閱 AWS CLI 中的安裝 AWS Command Line Interface 使用者指南

錯誤 未知選項:-無電子郵件。

解決方案: 當您運行 aws ecr get-login 命令。請確定您已安裝最新的 AWS CLI 版本 (例如,執行:pip install awscli --upgrade --user)。如果您使用 Windows 並已使用 MSI 安裝程式安裝 CLI,您必須重新啟動安裝程序。更多信息,請參閱 安裝 AWS Command Line Interface MicrosoftWindows上AWS Command Line Interface 使用者指南.

警告 已禁用IPv4。網路將無法運作。

解決方案: 運行時,您可能會收到此警告或類似消息 AWS IoT Greengrass 在Linux計算機上。請依此步驟所述啟用 IPv4 網路轉寄。AWS IoT Greengrass 雲端部署和 MQTT 通訊無法在未啟用 IPv4 轉寄時使用。如需詳細資訊,請參閱 Docker 文件中的在執行時間設定命名空間核心參數 (sysctls)

錯誤 防火牆正在阻止窗口和容器之間的文件共享。

解決方案: 您可能會收到這個錯誤或 Firewall Detected 消息。如果您登入虛擬私有網路 (VPN),而您的網路設定防止掛載共用磁碟機,也可能會發生這個錯誤。在這種情況下,請關閉 VPN 並重新執行 Docker 容器。

錯誤 調用GetAuthorisationToke操作時出現錯誤(訪問拒絕例外): 用戶:arn:aws:iam::<account-id>:user/<user-name>無權執行:ecr:GetAuthorization資源:*

在運行 aws ecr get-login-password 如果沒有足夠的權限訪問 Amazon ECR 存儲庫。更多信息,請參閱 Amazon ECR 存儲庫策略示例訪問One Amazon ECR 存儲庫Amazon ECR 用戶指南.

如需一般的 AWS IoT Greengrass 故障診斷協助,請參閱故障診斷 ​AWS IoT Greengrass

在 Docker 容器中對 AWS IoT Greengrass 進行偵錯

為了對 Docker 容器的問題進行偵錯,您可以保留 Greengrass 執行時間日誌或將互動式 shell 連接到 Docker 容器。

將 Greengrass 執行時間日誌保留在 Docker 容器之外

您可以在連結掛載 /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"

Replace (取代) gg-container-idcontainer_id 上一個命令的結果。

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