在 Docker 容器中執行 AWS IoT Greengrass - AWS IoT Greengrass
先決條件從 Amazon ECR 提取AWS IoT Greengrass容器映像建立及設定 Greengrass 群組和核心在本機執行 AWS IoT Greengrass為群組的容器化設定「No container」(無容器)將 Lambda 函數部署到碼頭容器(選擇性) 在 Docker 容器中部署與 Greengrass 互動的用戶端裝置停用 AWS IoT Greengrass Docker 容器Docker 容器中 AWS IoT Greengrass 的疑難排解

AWS IoT Greengrass Version 1 於 2023 年 6 月 30 日進入延長使用壽命階段。如需詳細資訊，請參閱AWS IoT Greengrass V1 維護政策。在此日期之後， AWS IoT Greengrass V1 將不會發行提供功能、增強功能、錯誤修正或安全性修補程式的更新。在上運行的設備 AWS IoT Greengrass V1 不會中斷，並將繼續運行並連接到雲。我們強烈建議您移轉至 AWS IoT Greengrass Version 2，這會增加重要的新功能，並支援其他平台。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 Docker 容器中執行 AWS IoT Greengrass

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

您可以通過安裝了AWS IoT Greengrass核心軟件和依賴關係CloudFront的亞馬遜下載 Docker 文件。若要修改 Docker 映像檔以在不同平台架構上執行或減少 Docker 映像檔的大小，請參閱 Docker 套件下載中的 README 檔案。

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

重要

2022 年 6 月 30 日，AWS IoT Greengrass終止發佈至亞馬遜彈性容器登錄 (亞馬遜 ECR) 和碼頭集線器的AWS IoT Greengrass核心軟體 v1.x 碼頭映像的維護。您可以繼續從 Amazon ECR 和碼頭中心下載這些 Docker 映像檔，直到 2023 年 6 月 30 日為止，即維護結束後一年。不過，AWS IoT Greengrass核心軟體 v1.x Docker 映像檔在維護於 2022 年 6 月 30 日結束後，便不會再收到安全性修補程式或錯誤修正。如果您執行的生產工作負載取決於這些 Docker 映像檔，我們建議您使用AWS IoT Greengrass提供的 Docker 檔案來建置您自己的 Docker 映像檔。如需詳細資訊，請參閱AWS IoT Greengrass Docker 軟體。

本主題說明如何從亞馬遜 ECR 下載AWS IoT Greengrass泊塢視窗映像檔，並在視窗、macOS 或 Linux (x86_64) 平台上執行。本主題包含以下步驟：

  1. 從 Amazon ECR 提取AWS IoT Greengrass容器映像

  2. 建立及設定 Greengrass 群組和核心

  3. 在本機執行 AWS IoT Greengrass

  4. 為群組的容器化設定「No container」(無容器)

  5. 將 Lambda 函數部署到碼頭容器

  6. (選擇性) 在 Docker 容器中部署與 Greengrass 互動的用戶端裝置

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

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

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

當 Greengrass 群組的 Lambda 執行階段環境設定為「無容器」(需要在 Docker 容器AWS IoT Greengrass中執行) 時，就不支援這些功能。

先決條件

開始本教學課程前，您必須執行下列動作。

  • 您必須根據您選擇的AWS Command Line Interface (AWS CLI) 版本，在主機電腦上安裝下列軟體和版本。

    AWS CLI version 2

    • 碼頭工人版本 18.09 或更高版本。早期版本可能也有效，但我們建議 18.09 或更高版本。

    • AWS CLI2.0.0 版或更新版本。

      注意

      若要在 Windows 電腦上升級至更新的AWS CLI版本 2，您必須重複 MSI 安裝程序。

    AWS CLI version 1

    • 碼頭工人版本 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.

      • 若要升級至第 1 版的最新AWS CLI版本，請執行以下命令。

        pip install awscli --upgrade --user
      注意

      如果您在 Windows 上使用 MSI 安裝的AWS CLI版本 1，請注意下列事項：

      • 如果AWS CLI版本 1 安裝失敗，請嘗試使用 Python 和 pip 安裝。

      • 若要升級至更新的AWS CLI版本 1，您必須重複 MSI 安裝程序。

  • 若要存取 Amazon Elastic Container Registry (Amazon ECR) 資源，您必須授與下列許可。

步驟 1：從 Amazon ECR 提取AWS IoT Greengrass容器映像

AWS 提供已安裝 AWS IoT Greengrass 核心軟體的 Docker 映像。

警告

從AWS IoT Greengrass核心軟件的 1.11.6 版開始，Greengrass 碼頭圖像不再包含 Python 2.7，因為 Python 2.7nd-of-life 在 2020 年達到了 e，並且不再接收安全更新。如果您選擇更新為這些 Docker 映像檔，建議您在將更新部署到生產裝置之前，先驗證應用程式是否可以使用新的 Docker 映像檔。如果您的應用程序需要 Python 2.7 使用 Greengrass 碼頭圖像，則可以修改 Greengrass 碼頭文件以包含 Python 2.7 為您的應用程序。

如需顯示如何從 Amazon ECR 提取latest映像的步驟，請選擇您的作業系統：

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

  1. 在亞馬遜 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 上的「標籤」頁面或使用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 IoT 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. 在亞馬遜 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 上的「標籤」頁面或使用aws ecr list-images命令。例如：

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

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

  1. 在亞馬遜 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 上的「標籤」頁面或使用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

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

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

  1. 建立裝置安全性資源的資料夾，然後將憑證和金鑰移至該資料夾。執行下列命令。取代path-to-security-files為安全性資源的路徑，並以檔案名稱中的憑證 ID 取代憑證 ID。

    mkdir /tmp/certs
mv path-to-security-files/certificateId-certificate.pem.crt /tmp/certs
mv path-to-security-files/certificateId-public.pem.key /tmp/certs
mv path-to-security-files/certificateId-private.pem.key /tmp/certs
mv path-to-security-files/AmazonRootCA1.pem /tmp/certs

  2. 為設備的配置創建一個文件夾，然後將AWS IoT Greengrass Core 配置文件移動到該文件夾。執行下列命令。以組態檔案的路徑取path-to-config-file代。

    mkdir /tmp/config
mv path-to-config-file/config.json /tmp/config

  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. 建立裝置安全性資源的資料夾，然後將憑證和金鑰移至該資料夾。執行下列命令。取代path-to-security-files為安全性資源的路徑，並以檔案名稱中的憑證 ID 取代憑證 ID。

    mkdir /tmp/certs
mv path-to-security-files/certificateId-certificate.pem.crt /tmp/certs
mv path-to-security-files/certificateId-public.pem.key /tmp/certs
mv path-to-security-files/certificateId-private.pem.key /tmp/certs
mv path-to-security-files/AmazonRootCA1.pem /tmp/certs

  2. 為設備的配置創建一個文件夾，然後將AWS IoT Greengrass Core 配置文件移動到該文件夾。執行下列命令。以組態檔案的路徑取path-to-config-file代。

    mkdir /tmp/config
mv path-to-config-file/config.json /tmp/config

  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. 建立裝置安全性資源的資料夾，然後將憑證和金鑰移至該資料夾。在命令提示中執行下列命令：取代path-to-security-files為安全性資源的路徑，並以檔案名稱中的憑證 ID 取代憑證 ID。

    mkdir C:\Users\%USERNAME%\Downloads\certs
move path-to-security-files\certificateId-certificate.pem.crt C:\Users\%USERNAME%\Downloads\certs
move path-to-security-files\certificateId-public.pem.key C:\Users\%USERNAME%\Downloads\certs
move path-to-security-files\certificateId-private.pem.key C:\Users\%USERNAME%\Downloads\certs
move path-to-security-files\AmazonRootCA1.pem C:\Users\%USERNAME%\Downloads\certs

  2. 為設備的配置創建一個文件夾，然後將AWS IoT Greengrass Core 配置文件移動到該文件夾。在命令提示中執行下列命令：以組態檔案的路徑取path-to-config-file代。

    mkdir C:\Users\%USERNAME%\Downloads\config
move path-to-config-file\config.json C:\Users\%USERNAME%\Downloads\config

  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 群組的容器化設定「No container」(無容器)

當您在 Docker 容器AWS IoT Greengrass中執行時，所有 Lambda 函數都必須在沒有容器化的情況下執行。在本步驟中，您會將群組的預設容器化設為 No container (無容器)。第一次部署群組之前，必須先執行此動作。

  1. 在AWS IoT主控台瀏覽窗格的 [管理] 下，展開 [Greengrass 裝置]，然後選擇 [群組 (V1)]。

  2. 選擇您希望變更設定的群組。

  3. 選擇 Lambda 函數索引標籤。

  4. 在預設 Lambda 函數執行階段環境下，選擇編輯。

  5. 在編輯預設 Lambda 函數執行階段環境中的預設 Lambda 函數容器化下，變更容器化設定。

  6. 選擇 儲存 。

變更會在群組部署後生效。

如需詳細資訊，請參閱為群組中的 Lambda 函數設定預設容器化。

注意

根據預設，Lambda 函數會使用群組容器化設定。如果在 Docker 容器中執行時AWS IoT Greengrass覆寫任何 Lambda 函數的「無容器」設定，則部署會失敗。

步驟 5：將 Lambda 函數部署到AWS IoT Greengrass碼頭容器

您可以將長壽命的 Lambda 函數部署到 Greengrass 碼頭容器。

步驟 6：（可選）部署與 Docker 容器中運行的 Greengrass 進行交互的客戶端設備

您也可以部署在 Docker 容器中執行AWS IoT 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 版。建議您使用第 2AWS CLI 版。如需詳細資訊，請參閱《AWS Command Line Interface 使用者指南》中的安裝 AWS CLI。

錯誤：未知的選項：-no-include-email。

解決方案：執行 aws ecr get-login 命令時，可能會發生此錯誤。請確定您已安裝最新的 AWS CLI 版本 (例如，執行：pip install awscli --upgrade --user)。如果您使用 Windows 並已使用 MSI 安裝程式安裝 CLI，您必須重新啟動安裝程序。如需詳細資訊，請參閱AWS Command Line Interface使用者指南中的AWS Command Line Interface在微軟視窗上安裝。

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

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

錯誤：防火牆封鎖了 Windows 和容器之間的檔案共用。

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

錯誤：呼叫GetAuthorizationToken作業時發生錯誤 (AccessDeniedException)：User: arn: aw:iam::: user/ <account-id><user-name>未授權在GetAuthorizationToken資源上執行:ecr: *

如果您沒有足夠的許可以存取 Amazon ECR 儲存庫，則執行aws ecr get-login-password命令時可能會收到此錯誤。如需詳細資訊，請參閱 Amazon ECR 儲存庫政策範例和存取 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"

gg-container-id使用上一個命令的container_id結果取代。

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