Docker 應用程式部署連接器 - AWS IoT Greengrass

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

Docker 應用程式部署連接器

Greengrass Docker 應用程式部署 連接器可以更輕鬆地在 AWS IoT Greengrass 核心 上執行 Docker 影像。連接器使用 Docker Compose 從 docker-compose.yml 檔案啟動多容器 Docker 應用程式。具體而言,連接器會執行 docker-compose 命令來管理單一核心裝置上的 Docker 容器。如需詳細資訊,請參閱 Docker 文件中的 Docker Compose 概觀。連接器可以存取儲存在 Docker 容器登錄檔中的 Docker 影像,例如 Amazon Elastic Container Registry (Amazon ECR)、Docker Hub 和私有 Docker 可信任登錄檔。

部署Greengrass組後,該接頭會拉出最新的圖像並啓動Docker容器。它運行 docker-compose pulldocker-compose up 命令。然後,接頭將命令的狀態發佈到 輸出MQTT主題. 它也會記錄有關執行 Docker 容器的狀態資訊。這可讓您監控 Amazon CloudWatch 中的應用程式日誌。如需更多詳細資訊,請參閱「使用 AWS IoT Greengrass 日誌進行監控」。每次 Greengrass 協助程式重新啟動時,連接器也會啟動 Docker 容器。可在核心上執行的 Docker 容器數量取決於您的硬體。

Docker 容器須在核心設備上的 Greengrass 網域外執行,因此無法存取核心的處理程序間通訊 (IPC)。不過,您可以使用 Greengrass 元件 (例如本機的 Lambda 功能) 來設定部分通訊頻道。如需更多詳細資訊,請參閱「與 Docker 容器通訊」。

您可以使用連接器來處理在核心裝置上託管 Web 伺服器或 MySQL 伺服器等案例。Docker 應用程式中的本機服務可以互相通訊,也能和本機環境中的其他程序以及雲端服務通訊。例如,您可以在核心上執行 Web 伺服器,將要求從 Lambda 函數傳送至雲端的 Web 服務。

此連接器會以無容器隔離模式執行,因此您可以將其部署到在沒有 Greengrass 容器化的情況下執行的 Greengrass 群組。

這個連接器有下列版本。

版本

ARN:

5.

arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5

4.

arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/4

3

arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/3

2

arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/2

1.

arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/1

如需版本變更的詳細資訊,請參閱 Changelog

要求

此連接器有下列要求:

  • AWS IoT Greengrass 核心軟體 1.10 or later 版。

    注意

    OpenWrt 發行版本不支援此連接器。

  • Python 3.7 版已安裝在核心裝置上並已新增至 PATH 環境變數。

  • Greengrass 核心上至少要有 36 MB RAM,以供連接器監控執行 Docker 容器。總記憶體需求取決於核心上執行的 Docker 容器數目。

  • 安裝在 Greengrass 核心上的 Docker Engine 1.9.1 或更新版本。19.0.3 版是經過驗證,可與連接器搭配使用的最新版本。

    docker 可執行檔必須位於 /usr/bin/usr/local/bin 目錄中。

    重要

    建議您安裝登入資料存放區,以保護 Docker 登入資料的本機複本。如需更多詳細資訊,請參閱「安全注意事項」。

    有關在alirocumabLinux分佈上安裝Docker的信息,請參閱 的Docker基本知識 Amazon ECSAmazon Elastic Container Service Developer Guide.

  • 安裝在 Greengrass 核心上的 Docker Composedocker-compose 可執行檔必須位於 /usr/bin/usr/local/bin 目錄中。

    下列 Docker Compose 版本經過驗證,可與連接器搭配使用。

    連接器版本

    經過驗證的 Docker Compose 版本

    5.

    1.25.4

    4.

    1.25.4

    3.

    1.25.4

    2.

    1.25.1

    1.

    1.24.1

  • 儲存在 Amazon S3 中的單一 Docker Compose 檔案 (例如 docker-compose.yml)。格式必須與安裝在核心上的 Docker Compose 版本相容。在您的核心上使用該文件前,請先測試該文件。如果您在部署 Greengrass 群組後才編輯檔案,則必須重新部署群組,以更新核心上的本機複本。

  • 具有呼叫本機 Docker 協助程式之權限的 Linux 使用者,以及寫入儲存 Compose 檔案本機複本的目錄。如需更多詳細資訊,請參閱「在 核心上設定 Docker 使用者」。

  • 已將 Greengrass 群組角色設定為允許在包含 Compose 檔案的 S3 儲存貯體上執行 s3:GetObject 動作。此權限顯示在下列範例 IAM 政策中。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessToComposeFileS3Bucket", "Action": [ "s3:GetObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::bucket-name/*" } ] }

    針對群組角色要求,您必須設定角色以授與必要的許可,並確認已將角色新增至群組。有關詳細信息,請參閱 管理 Greengrass 群組角色 (主控台)管理 Greengrass 群組角色 (CLI).

  • 如果您的 Docker Compose 檔案參考儲存在 Amazon ECR 中的 Docker 影像,則須已將 Greengrass 群組角色設定為允許執行下列動作:

    • Amazon ECR 儲存庫上的 ecr:GetDownloadUrlForLayerecr:BatchGetImage 動作,包含 Docker 影像。

    • 您資源上的 ecr:GetAuthorizationToken 動作。

    儲存庫必須位於與連接器相同的 AWS 帳戶和 AWS 區域。

    重要

    由 Greengrass 群組中的所有 Lambda 函數和連接器擔任群組角色中的權限。如需更多詳細資訊,請參閱「安全注意事項」。

    這些權限會顯示在下列範例政策中。

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowGetEcrRepositories", "Effect": "Allow", "Action": [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": [ "arn:aws:ecr:region:account-id:repository/repository-name" ] }, { "Sid": "AllowGetEcrAuthToken", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" } ] }

    更多信息,請參閱 Amazon ECR 存儲庫策略示例Amazon ECR 用戶指南.

    針對群組角色要求,您必須設定角色以授與必要的許可,並確認已將角色新增至群組。有關詳細信息,請參閱 管理 Greengrass 群組角色 (主控台)管理 Greengrass 群組角色 (CLI).

  • 如果您的 Docker Compose 檔案從 AWS Marketplace 中參考 Docker 影像,則連接器也會有下列需求:

    • 您必須訂閱 AWS Marketplace 容器產品。更多信息,請參閱 查找和訂閱容器產品AWS Marketplace 訂閱者指南.

    • 必須依照秘密需求中所述來設定 AWS IoT Greengrass 以支援本機秘密。 連接器只會使用此功能從 AWS Secrets Manager 擷取您的秘密,但不會將其儲存。

    • 您必須在 Secrets Manager 中為儲存在 Compose 檔案中參考的 Docker 影像的每個 AWS Marketplace 登錄檔建立秘密。如需更多詳細資訊,請參閱「從私有儲存庫存取 Docker 影像」。

  • 如果您的 Docker Compose 檔案從登陸檔私有儲存庫中,而不是從 Amazon ECR 中參考 Docker 影像,例如 Docker Hub,則連接器也會有下列需求:

    • 必須依照秘密需求中所述來設定 AWS IoT Greengrass 以支援本機秘密。 連接器只會使用此功能從 AWS Secrets Manager 擷取您的秘密,但不會將其儲存。

    • 您必須在 Secrets Manager 中為儲存在 Compose 檔案中參考的 Docker 影像的每個私有儲存庫建立秘密。如需更多詳細資訊,請參閱「從私有儲存庫存取 Docker 影像」。

  • 部署包含此連接器的 Greengrass 群組時,必須執行 Docker 協助程式。

從私有儲存庫存取 Docker 影像

如果您使用登入資料來存取 Docker 影像,則必須允許連接器存取它們。此作法取決於 Docker 影像的位置。

對於儲存在 Amazon ECR 中的 Docker 影像,您可以授權以取得 Greengrass 群組角色中的授權字符。如需更多詳細資訊,請參閱「要求」。

針對儲存在其他私有儲存庫或登錄檔中的 Docker 影像,您必須在 AWS Secrets Manager 中建立秘密來儲存您的登入資訊。這包括 AWS Marketplace 中您訂閱的 Docker 影像。為每個儲存庫建立一個秘密。如果您在 Secrets Manager 中更新秘密,則變更會在您下次部署群組時傳播至核心。

注意

Secrets Manager 是一項服務,您可以在 AWS 雲端中安全地儲存和管理您的登入資料、金鑰和其他秘密。如需詳細資訊,請參閱《AWS Secrets Manager 使用者指南》中的什麼是AWS Secrets Manager

每個秘密都必須包含下列金鑰:

Key

數值

username

用來存取儲存庫或登錄檔的使用者名稱。

password

用來存取儲存庫或登錄的密碼。

registryUrl

登錄檔的端點。這必須符合 Compose 檔案中對應的登錄檔 URL。

注意

為了允許 AWS IoT Greengrass 根據預設存取秘密,秘密名稱必須以 greengrass- 開頭。否則,您的 Greengrass 服務角色必須授與存取權。如需更多詳細資訊,請參閱「允許 AWS IoT Greengrass 取得秘密值」。

從以下位置獲取Docker圖像的登錄信息 AWS Marketplace

請使用 aws ecr get-login 命令從 AWS Marketplace 取得 Docker 影像的使用者名稱、密碼和登錄檔 URL。

aws ecr get-login --no-include-email --region region --registry-ids registry-id
注意

您可以在 AWS Marketplace 網站的容器產品啟動頁面找到登錄 ID。在 Container Images (容器影像) 下,選擇 View container image details (檢視容器影像詳細資訊)

輸出包含您用來建立秘密的登入資訊。例如,在下列輸出中,-u 值是使用者名稱,-p 值是密碼,而登錄 URL 是輸出端的 URL。

docker login -u AWS -p eyGuYXlsbGkxU0NveDNKaTY4ak...c0MzFyMTIxfQ== https://123456789012.dkr.ecr.region.amazonaws.com

使用此登入資訊,為儲存在 Compose 檔案中參考的 Docker 影像的每個 AWS Marketplace 登錄檔建立秘密。更多信息,請參閱 獲得登錄AWS CLI Command Reference.

建立秘密 (主控台)

在 AWS Secrets Manager 主控台,選擇 Other type of secrets (其他類型的秘密)。低於 指定爲此密鑰存儲的鍵值對,添加行 username, password、和 registryUrl。更多信息,請參閱 創建基本祕訣AWS Secrets Manager 使用者指南.


                                用使用者名稱、密碼和註冊庫 URL 金鑰建立一個秘密。
建立秘密 (CLI)

在 AWS CLI 中使用 Secrets Manager create-secret 命令,如下列範例所示。更多信息,請參閱 創建密鑰AWS CLI Command Reference.

aws secretsmanager create-secret --name greengrass-MySecret --secret-string [{"username":"Mary_Major"},{"password":"abc123xyz456"},{"registryUrl":"https://docker.io"}]
重要

您有責任保護儲存 Docker Compose 檔案的 DockerComposeFileDestinationPath 目錄以及私有儲存庫的 Docker 影像登入資料的安全。如需更多詳細資訊,請參閱「安全注意事項」。

Parameters

此連接器提供下列參數:

Version 5
DockerComposeFileS3Bucket

包含 Docker Compose 檔案的 S3 儲存貯體名稱。建立儲存貯體時,請務必遵循 Amazon Simple Storage Service 開發人員指南 中描述的儲存貯體名稱規則

AWS IoT 主控台中的顯示名稱:Docker Compose file in S3 (S3 中的 Docker Compose 檔案)

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中 Docker Compose 檔案的物件金鑰。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的 Object Key and Metadata (物件金鑰與中繼資料)。

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 .+

DockerComposeFileS3Version

Amazon S3 中 Docker Compose 檔案的物件版本。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的使用版本控制

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:false

類型:string

有效的模式 .+

DockerComposeFileDestinationPath

用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。DockerUserId 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊,請參閱 在 AWS IoT Greengrass 核心上設定 Docker 使用者

重要

儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需更多詳細資訊,請參閱 安全注意事項

AWS IoT 主控台中的顯示名稱:Directory path for local Compose file (本機 Compose 檔案的目錄路徑)

必要:true

類型:string

有效的模式 \/.*\/?

範例: /home/username/myCompose

DockerUserId

連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 docker Linux 群組,並具有 DockerComposeFileDestinationPath 目錄的寫入權限。如需詳細資訊,請參閱在 核心上設定 Docker 使用者

注意

我們建議您除非必要,避免以 root 身分執行。如果您指定了根用戶,則必須允許 Lambda 功能可以在 AWS IoT Greengrass 核心. 如需詳細資訊,請參閱以 Root 身分執行 Lambda 函數.

AWS IoT 主控台中的顯示名稱:Docker user ID (Docker 使用者 ID)

必要:false

類型:string

有效的模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中秘密的 Amazon Resource Names (ARN),包含用於存取私有儲存庫中 Docker 影像的登入資訊。如需詳細資訊,請參閱 從私有儲存庫存取 Docker 影像

AWS IoT 主控台中的顯示名稱:Credentials for private repositories (私有儲存庫的登入資料)

必要:false。此參數需要存取儲存在私有儲存庫中的 Docker 影像。

類型:stringarray

有效的模式: [( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]

DockerContainerStatusLogFrequency

連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。

AWS IoT 主控台中的顯示名稱:Logging frequency (記錄頻率)

必要:false

類型:string

有效的模式: ^[1-9]{1}[0-9]{0,3}$

ForceDeploy

指出如果 Docker 因為上次部署的不當清除而失敗,是否強制 Docker 部署。(預設為 False.)

AWS IoT 主控台中的顯示名稱:Force deployment (強制部署)

必要: false

類型: string

有效的模式: ^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$

DockerPullBeforeUp

指示部署人員是否應運行 docker-compose pull 然後再運行 docker-compose up 下拉行爲。(預設為 True.)

AWS IoT 主控台中的顯示名稱: 先拉後拉

必要: false

類型: string

有效的模式: ^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$

Versions 2 - 4
DockerComposeFileS3Bucket

包含 Docker Compose 檔案的 S3 儲存貯體名稱。建立儲存貯體時,請務必遵循 Amazon Simple Storage Service 開發人員指南 中描述的儲存貯體名稱規則

AWS IoT 主控台中的顯示名稱:Docker Compose file in S3 (S3 中的 Docker Compose 檔案)

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中 Docker Compose 檔案的物件金鑰。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的 Object Key and Metadata (物件金鑰與中繼資料)。

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 .+

DockerComposeFileS3Version

Amazon S3 中 Docker Compose 檔案的物件版本。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的使用版本控制

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:false

類型:string

有效的模式 .+

DockerComposeFileDestinationPath

用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。DockerUserId 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊,請參閱 在 AWS IoT Greengrass 核心上設定 Docker 使用者

重要

儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需更多詳細資訊,請參閱 安全注意事項

AWS IoT 主控台中的顯示名稱:Directory path for local Compose file (本機 Compose 檔案的目錄路徑)

必要:true

類型:string

有效的模式 \/.*\/?

範例: /home/username/myCompose

DockerUserId

連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 docker Linux 群組,並具有 DockerComposeFileDestinationPath 目錄的寫入權限。如需詳細資訊,請參閱在 核心上設定 Docker 使用者

注意

我們建議您除非必要,避免以 root 身分執行。如果您指定了根用戶,則必須允許 Lambda 功能可以在 AWS IoT Greengrass 核心. 如需詳細資訊,請參閱以 Root 身分執行 Lambda 函數.

AWS IoT 主控台中的顯示名稱:Docker user ID (Docker 使用者 ID)

必要:false

類型:string

有效的模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中秘密的 Amazon Resource Names (ARN),包含用於存取私有儲存庫中 Docker 影像的登入資訊。如需詳細資訊,請參閱 從私有儲存庫存取 Docker 影像

AWS IoT 主控台中的顯示名稱:Credentials for private repositories (私有儲存庫的登入資料)

必要:false。此參數需要存取儲存在私有儲存庫中的 Docker 影像。

類型:stringarray

有效的模式: [( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]

DockerContainerStatusLogFrequency

連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。

AWS IoT 主控台中的顯示名稱:Logging frequency (記錄頻率)

必要:false

類型:string

有效的模式: ^[1-9]{1}[0-9]{0,3}$

ForceDeploy

指出如果 Docker 因為上次部署的不當清除而失敗,是否強制 Docker 部署。(預設為 False.)

AWS IoT 主控台中的顯示名稱:Force deployment (強制部署)

必要: false

類型: string

有效的模式: ^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee])$

Version 1
DockerComposeFileS3Bucket

包含 Docker Compose 檔案的 S3 儲存貯體名稱。建立儲存貯體時,請務必遵循 Amazon Simple Storage Service 開發人員指南 中描述的儲存貯體名稱規則

AWS IoT 主控台中的顯示名稱:Docker Compose file in S3 (S3 中的 Docker Compose 檔案)

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 [a-zA-Z0-9\\-\\.]{3,63}

DockerComposeFileS3Key

Amazon S3 中 Docker Compose 檔案的物件金鑰。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的 Object Key and Metadata (物件金鑰與中繼資料)。

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:true

類型:string

有效的模式 .+

DockerComposeFileS3Version

Amazon S3 中 Docker Compose 檔案的物件版本。如需更多資訊,包括物件金鑰命名準則,請參閱 Amazon Simple Storage Service 開發人員指南 中的使用版本控制

注意

在主控台中,Docker Compose file in S3 (S3 中的 Docker Compose 檔案) 屬性會結合 DockerComposeFileS3BucketDockerComposeFileS3KeyDockerComposeFileS3Version 參數。

必要:false

類型:string

有效的模式 .+

DockerComposeFileDestinationPath

用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。DockerUserId 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊,請參閱 在 AWS IoT Greengrass 核心上設定 Docker 使用者

重要

儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需更多詳細資訊,請參閱 安全注意事項

AWS IoT 主控台中的顯示名稱:Directory path for local Compose file (本機 Compose 檔案的目錄路徑)

必要:true

類型:string

有效的模式 \/.*\/?

範例: /home/username/myCompose

DockerUserId

連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 docker Linux 群組,並具有 DockerComposeFileDestinationPath 目錄的寫入權限。如需詳細資訊,請參閱在 核心上設定 Docker 使用者

注意

我們建議您除非必要,避免以 root 身分執行。如果您指定了根用戶,則必須允許 Lambda 功能可以在 AWS IoT Greengrass 核心. 如需詳細資訊,請參閱以 Root 身分執行 Lambda 函數.

AWS IoT 主控台中的顯示名稱:Docker user ID (Docker 使用者 ID)

必要:false

類型:string

有效的模式: ^[0-9]{1,5}$

AWSSecretsArnList

AWS Secrets Manager 中秘密的 Amazon Resource Names (ARN),包含用於存取私有儲存庫中 Docker 影像的登入資訊。如需詳細資訊,請參閱 從私有儲存庫存取 Docker 影像

AWS IoT 主控台中的顯示名稱:Credentials for private repositories (私有儲存庫的登入資料)

必要:false。此參數需要存取儲存在私有儲存庫中的 Docker 影像。

類型:stringarray

有效的模式: [( ?,? ?"(arn:(aws(-[a-z]+)):secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:([a-zA-Z0-9\]+/)[a-zA-Z0-9/_+=,.@-]+-[a-zA-Z0-9]+)")]

DockerContainerStatusLogFrequency

連接器記錄有關核心上 Docker 容器執行狀態資訊的頻率 (秒)。預設值為 300 秒 (5 分鐘)。

AWS IoT 主控台中的顯示名稱:Logging frequency (記錄頻率)

必要:false

類型:string

有效的模式: ^[1-9]{1}[0-9]{0,3}$

建立範例連接器 (AWS CLI)

下列 CLI 命令會使用包含 ConnectorDefinition 連接器的初始版本建立 Greengrass Docker 應用程式部署。

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyDockerAppplicationDeploymentConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/5", "Parameters": { "DockerComposeFileS3Bucket": "myS3Bucket", "DockerComposeFileS3Key": "production-docker-compose.yml", "DockerComposeFileS3Version": "123", "DockerComposeFileDestinationPath": "/home/username/myCompose", "DockerUserId": "1000", "AWSSecretsArnList": "[\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret1-hash\",\"arn:aws:secretsmanager:region:account-id:secret:greengrass-secret2-hash\"]", "DockerContainerStatusLogFrequency": "30", "ForceDeploy": "True", "DockerPullBeforeUp": "True" } } ] }'
注意

這個連接器中的 Lambda 函數具有長時間的生命週期。

輸入資料

此連接器不需要或接受輸入資料。

輸出資料

此連接器將 docker-compose up 命令的狀態發佈為輸出資料。

訂閱中的主題篩選條件

dockerapplicationdeploymentconnector/message/status

範例輸出 Success
{ "status":"success", "GreengrassDockerApplicationDeploymentStatus":"Successfully triggered docker-compose up", "S3Bucket":"myS3Bucket", "ComposeFileName":"production-docker-compose.yml", "ComposeFileVersion":"123" }
範例輸出 失敗:
{ "status":"fail", "error_message":"description of error", "error":"InvalidParameter" }

錯誤類型可以是 InvalidParameterInternalError

在 AWS IoT Greengrass 核心上設定 Docker 使用者

Greengrass Docker 應用程式部署 連接器會以您為 DockerUserId 參數指定的使用者身分執行。如果您未指定值,連接器會以 ggc_user 為身分執行,這也是預設 Greengrass 存取身分。

若要允許連接器與 Docker 協助程式互動,Docker 使用者必須屬於核心上的 docker Linux 群組。Docker 使用者也必須具有 DockerComposeFileDestinationPath 目錄的寫入權限。這是連接器儲存本機 docker-compose.yml 檔案和 Docker 登入資料的位置。

注意
  • 我們建議您創建一個Linux用戶,而不是使用 ggc_user。否則, Lambda Greengrass組中的函數可以訪問Compose文件和Docker憑據。

  • 我們建議您除非必要,避免以 root 身分執行。如果您指定了根用戶,則必須允許 Lambda 功能可以在 AWS IoT Greengrass 核心. 如需詳細資訊,請參閱以 Root 身分執行 Lambda 函數.

  1. 建立使用者。您可以執行 useradd 命令,並包含選用的 -u 選項來指派 UID。例如: 。

    sudo useradd -u 1234 user-name
  2. 將使用者新增至核心上的 docker 群組。例如: 。

    sudo usermod -aG docker user-name

    如需詳細資訊 (包括如何建立 docker 群組),請參閱 Docker 文件中 Manage Docker as a non-root user (以非根使用者身分管理 Docker)。

  3. 授予使用者寫入 DockerComposeFileDestinationPath 參數指定目錄的權限。例如: 。

    1. 將使用者設定為目錄的擁有者。這個範例會使用步驟 1 中的 UID。

      chown 1234 docker-compose-file-destination-path
    2. 將讀取和寫入權限提供給擁有者。

      chmod 700 docker-compose-file-destination-path

      如需詳細資訊,請參閱 Linux 基礎文件中的 How To Manage File And Folder Permissions In Linux (如何管理 Linux 中的檔案及資料夾權限)。

    3. 如果您在建立使用者時未指派 UID,或者,您使用現有使用者,請執行 id 命令以查詢 UID。

      id -u user-name

      您可以使用 UID 來設定連接器的 DockerUserId 參數。

用量資訊

使用 Greengrass Docker 應用程式部署 連接器時,請注意下列實作專屬的用量資訊。

  • 專案名稱的固定字首。連接器會在它啟動的 Docker 容器名稱前加上 greengrassdockerapplicationdeployment 字首。連接器在其執行的 docker-compose 指令中使用此字首做為專案名稱。

  • 記錄行為。連接器會將狀態資訊和疑難排解資訊寫入日誌檔案。您可以設定 AWS IoT Greengrass 將日誌傳送至 CloudWatch Logs,並在本機寫入日誌。如需更多詳細資訊,請參閱「連接器的記錄」。這是連接器本機記錄檔的路徑:

    /greengrass-root/ggc/var/log/user/region/aws/DockerApplicationDeployment.log

    您必須具有 root 權限才能存取本機日誌。

  • 更新 Docker 影像。Docker 會快取核心裝置上的影像。如果您更新 Docker 影像,並想將變更傳播到核心裝置,請務必變更 Compose 檔案中的影像標籤。部署 Greengrass 群組之後,變更就會生效。

  • 清除操作的 10 分鐘逾時。當 Greengrass 協助程式停止 (在重新啟動期間) 時,會觸發 docker-compose down 指令。在觸發 docker-compose down 以執行任何清理操作後,所有 Docker 容器最多有 10 分鐘的時間。如果清除未在 10 分鐘內完成,就必須手動清理剩下的容器。如需詳細資訊,請參閱 Docker CLI 文件中的 docker rm

  • 正在執行 Docker 命令。若要對問題進行疑難排解,可以在核心裝置的終端機視窗中執行 Docker 命令。例如,執行下列命令以查看連接器啟動的 Docker 容器:

    docker ps --filter name="greengrassdockerapplicationdeployment"
  • 保留的資源 ID。連接器會使用其在 Greengrass 群組中建立的 Greengrass 資源 DOCKER_DEPLOYER_SECRET_RESOURCE_RESERVED_ID_index ID。資源 ID 在群組中不得重複,因此請勿指派可能與此保留資源 ID 衝突的資源 ID。

與 Docker 容器通訊

AWS IoT Greengrass 支援 Greengrass 元件和 Docker 容器之間的下列通訊頻道:

  • Greengrass Lambda 函數可以使用 REST API,與 Docker 容器中的處理程序通訊。您可以在開啟連接埠的 Docker 容器中設定伺服器。Lambda 函數可以與此連接埠上的容器通訊。

  • Docker 容器中的處理程序可以透過本機 Greengrass 訊息中介裝置交換 MQTT 訊息。您可以將 Docker 容器設定為 Greengrass 群組中的 Greengrass 裝置,然後建立訂閱以允許容器與群組中的 Greengrass Lambda 函數、裝置和其他連接器通訊,或與 AWS IoT 和本機陰影服務通訊。如需更多詳細資訊,請參閱「設定與 Docker 容器的 MQTT 通訊」。

  • Greengrass Lambda 函數可以更新共用檔案,將資訊傳遞給 Docker 容器。您可以使用 Compose 檔案綁定掛載 Docker 容器的共用檔案路徑。

設定與 Docker 容器的 MQTT 通訊

您可以將 Docker 容器設定為 Greengrass 裝置,並將其新增至 Greengrass 群組。然後,您可以建立訂閱,以允許 Docker 容器和 Greengrass 元件或 AWS IoT 之間的 MQTT 通訊。在下列程序中,您會建立訂閱,允許 Docker 容器裝置接收來自本機陰影服務的陰影更新訊息。您可以遵循此模式來建立其他訂閱。

注意

在此程序中,假設您已建立 Greengrass 群組和 Greengrass 核心 (v1.10 or later)。若要了解如何建立 Greengrass 群組或核心,請參閱 AWS IoT Greengrass 入門

將 Docker 容器設定為 Greengrass 裝置,並將其新增至 Greengrass 群組

  1. 請在核心裝置上建立目錄,以儲存用來驗證 Greengrass 裝置的憑證和金鑰。

    檔案路徑必須掛載在您要啟動的 Docker 容器上。下面的程式碼片段顯示了如何在您的 Compose 檔案中掛載文件路徑。在此範例中:path-to-device-certs 表示您在此步驟中創建的目錄。

    version: '3.3' services: myService: image: user-name/repo:image-tag volumes: - /path-to-device-certs/:/path-accessible-in-container
  2. 在 AWS IoT 主控台中,選擇 Greengrass,然後選擇 Groups (群組)

  3. 選擇目標群組。

  4. 在群組組態頁面上,選擇 Devices (裝置),然後選擇 Add Device (新增裝置)

    
                            [裝置] 頁面的螢幕擷取畫面反白顯示 [新增您的第一個裝置] 按鈕。
  5. Add a Device (新增裝置) 頁面上,選擇 Create New Device (建立新裝置)

  6. Create a Registry entry for a device (建立裝置的登錄項目) 頁面上,輸入裝置名稱,然後選擇 Next (下一步)

  7. Set up security (設定安全性) 頁面上,在 1-Click 選擇 Use Defaults (使用預設值)。此選項會產生裝置憑證,內含附加 AWS IoT 政策和公有與私有金鑰。

  8. 下載安全憑證 將證書和密鑰下載到步驟1中創建的目錄,然後選擇 Finish.

    
                            [Download security credential (下載安全性登入資料)] 頁面的螢幕擷取畫面反白顯示 [下載] 這些資源為 tar.gz 鈕。
  9. 解壓縮 hash-setup.tar.gz 檔案。例如,執行下列命令:所以此 hash 佔位符是 tar.gz 您下載的文件(例如, bcc5afd26d)。

    cd /path-to-device-certs tar -xzf hash-setup.tar.gz
  10. 檢閱 AWS IoT 開發人員指南 中的伺服器身份驗證,並選擇適當的根 CA 憑證。建議您使用 Amazon Trust Services (ATS) 端點和 ATS 根 CA 憑證。

    重要

    根 CA 憑證類型必須與您的端點相符。使用 ATS 根 CA 憑證搭配 ATS 端點 (偏好),或使用 VeriSign 根 CA 憑證搭配舊式端點。只有一些 AWS 區域能支援舊式端點。如需更多詳細資訊,請參閱 服務端點必須匹配根CA證書類型

    將適當的 ATS 根 CA 憑證下載至核心裝置。例如,您可以使用下列 wget 命令,將 AmazonRootCA1.pem 下載至您的檔案路徑。

    cd /path-to-device-certs sudo wget -O root.ca.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem

接下來,在群組中建立訂閱。在此範例中,您可以建立訂閱讓 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息。

注意

陰影文件的大小上限為 8 KB。更多信息,請參閱 AWS IoT 配額AWS IoT 開發人員指南.

建立訂閱,允許 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息

  1. 在群組組態頁面選擇 Subscriptions (訂閱),然後選擇 Add Subscription

    
                此群組頁面反白顯示 [訂閱] 和 [新增訂閱]。
  2. Select your source and target (選擇您的來源和目標) 頁面設定來源和目標,如下所示:

    1. Select a source (選取來源) 中,選擇 Services (服務),然後選擇 Local Shadow Service (本機陰影服務)

    2. Select a target (選取目標),選擇 Devices (裝置),然後選擇您的裝置。

    3. 選擇 。Next.

    4. 使用主題篩選數據 頁面,用於 主題過濾器,選擇 $aws/things/TestCore/shadow/update/accepted,然後選擇 Next.

    5. 選擇 。Finish.

在您在 Compose 檔案中參考的 Docker 影像中,加入下列程式碼片段。這是 Greengrass 裝置程式碼。另外,請在 Docker 容器中新增程式碼,以啟動容器內的 Greengrass 設備。它可以在影像中或獨立的執行緒中,以個別程序來執行。

from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider # Discover Greengrass cores. discoveryInfoProvider = DiscoveryInfoProvider() discoveryInfoProvider.configureEndpoint(host) # Configure these paths based on the download location of the certificates. discoveryInfoProvider.configureCredentials(rootCAPath, certificatePath, privateKeyPath) discoveryInfoProvider.configureTimeout(10) # 10 seconds. # Get discovery info from AWS IoT. # thingName is the name you registered for the device. discoveryInfo = discoveryInfoProvider.discover(thingName) caList = discoveryInfo.getAllCas() coreList = discoveryInfo.getAllCores() # Try to connect to the Greengrass core. for connectivityInfo in coreInfo.connectivityInfoList: currentHost = connectivityInfo.host currentPort = connectivityInfo.port myAWSIoTMQTTClient.configureEndpoint(currentHost, currentPort) try: myAWSIoTMQTTClient.connect() connected = True break except BaseException as e: print("Error in connect!") if not connected: print("Cannot connect to core %s. Exiting..." % coreInfo.coreThingArn) sys.exit(-2) # Handle the MQTT message received from GGShadowService. def customCallback(client, userdata, message): print("Received a message on MQTT") print(message) # Subscribe to the MQTT topic. # The topic is the "$aws/things/TestCore/shadow/update/accepted". myAWSIoTMQTTClient.subscribe(topic, 1, customCallback) # Keep the process alive to listen for messages. while True: time.sleep(1)

安全注意事項

使用 Greengrass Docker 應用程式部署 連接器時,請注意下列安全性考量事項。

Docker Compose 檔案的本機儲存區

連接器會將 Compose 檔案的複本儲存在為 DockerComposeFileDestinationPath 參數指定的目錄中。

您有責任保護此目錄。您應該使用檔案系統權限來限制目錄的存取。

Docker 登入資料的本機儲存區

如果您的 Docker 影像儲存在私有儲存庫中,連接器會將您的 Docker 登入資料儲存在為 DockerComposeFileDestinationPath 參數指定的目錄中。

您有責任保護這些登入資料。例如,安裝 Docker Engine 時,應在核心裝置上使用 credential-helper

從可信任來源安裝 Docker Engine

您有責任從可信任來源安裝 Docker Engine。此連接器使用核心裝置上的 Docker 協助程式,存取您的 Docker 資產並管理 Docker 容器。

Greengrass 群組角色權限的範圍

由 Greengrass 群組中的所有 Lambda 函數和連接器擔任您新增至 Greengrass 群組角色中的權限。此連接器需要存取儲存 S3 儲存貯體中的 Docker Compose 檔案。如果您的 Docker 影像儲存在 Amazon ECR 的私有儲存庫中,那還需要存取您的 Amazon ECR 授權字符。

授權

Greengrass Docker 應用程式部署 連接器包含以下第三方軟體/授權:

這個連接器的發行係遵守 Greengrass Core 軟體授權合約

Changelog

下表說明連接器各版本的變更。

版本

變更

5.

圖像在運行前被拉出 docker-compose down.

4.

添加了前拉行爲以更新Docker圖像。

3.

修正了尋找環境變數的問題。

2.

新增 ForceDeploy 參數。

1.

初始版本。

Greengrass 群組一次僅可包含一個連接器版本。若要取得有關升級連接器版本的資訊,請參閱升級連接器版本

另請參閱 。