支援終止通知：2026 年 10 月 7 日 AWS 將停止 的支援 AWS IoT Greengrass Version 1。2026 年 10 月 7 日之後，您將無法再存取 AWS IoT Greengrass V1 資源。如需詳細資訊，請造訪[從 遷移 AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html)。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Docker 應用程式部署連接器 Greengrass Docker 應用程式部署連接器可讓您更輕鬆地在 AWS IoT Greengrass 核心上執行 Docker 映像。連接器使用 Docker Compose 從 `docker-compose.yml` 檔案啟動多容器 Docker 應用程式。具體而言，連接器會執行 `docker-compose` 命令來管理單一核心裝置上的 Docker 容器。如需詳細資訊，請參閱 Docker 文件中的 [Docker Compose 概觀](https://docs.docker.com/compose/)。連接器可以存取存放在 Docker 容器登錄檔中的 Docker 映像，例如 Amazon Elastic Container Registry (Amazon ECR)、Docker Hub 和私有 Docker 信任登錄檔。 部署 Greengrass 群組之後，連接器會提取最新的映像並啟動 Docker 容器。它會執行 `docker-compose pull`和 `docker-compose up`命令。然後，連接器會將命令的狀態發佈至[輸出 MQTT 主題](#docker-app-connector-data-output)。它也會記錄有關執行 Docker 容器的狀態資訊。這可讓您在 Amazon CloudWatch 中監控應用程式日誌。如需詳細資訊，請參閱[使用 AWS IoT Greengrass 日誌監控](greengrass-logs-overview.md)。每次 Greengrass 協助程式重新啟動時，連接器也會啟動 Docker 容器。可在核心上執行的 Docker 容器數量取決於您的硬體。 Docker 容器須在核心設備上的 Greengrass 網域外執行，因此無法存取核心的處理程序間通訊 (IPC)。不過，您可以使用 Greengrass 元件設定一些通訊通道，例如本機 Lambda 函數。如需詳細資訊，請參閱[與 Docker 容器通訊](#docker-app-connector-communicating)。 您可以使用連接器來處理在核心裝置上託管 Web 伺服器或 MySQL 伺服器等案例。Docker 應用程式中的本機服務可以互相通訊，也能和本機環境中的其他程序以及雲端服務通訊。例如，您可以在核心上執行 Web 伺服器，將請求從 Lambda 函數傳送至雲端中的 Web 服務。 此連接器會以[無容器](lambda-group-config.md#no-container-mode)隔離模式執行，因此您可以將其部署到在沒有 Greengrass 容器化的情況下執行的 Greengrass 群組。 此連接器具有下列版本。 | 版本 | ARN | | --- | --- | | 7 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/7` | | 6 | `arn:aws:greengrass:region::/connectors/DockerApplicationDeployment/versions/6` | | 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](#docker-app-connector-changelog)。 ## 要求 此連接器有下列要求： + AWS IoT Greengrass 核心軟體 v1.10 或更新版本。 **注意** OpenWrt 發行版本不支援此連接器。 + 安裝在核心裝置上並新增至 PATH 環境變數的 [Python](https://www.python.org/) 3.7 或 3.8 版。 **注意** 若要使用 Python 3.8，請執行下列命令，以建立從預設 Python 3.7 安裝資料夾到已安裝 Python 3.8 二進位檔的符號連結。 ``` sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7 ``` 這會設定您的裝置以符合 AWS IoT Greengrass的 Python 需求。 + Greengrass 核心上至少要有 36 MB RAM，以供連接器監控執行 Docker 容器。總記憶體需求取決於核心上執行的 Docker 容器數目。 + 安裝在 Greengrass 核心上的 [Docker Engine](https://docs.docker.com/install/) 1.9.1 或更新版本。19.0.3 版是經過驗證，可與連接器搭配使用的最新版本。 `docker` 可執行檔必須位於 `/usr/bin` 或 `/usr/local/bin` 目錄中。 **重要** 建議您安裝登入資料存放區，以保護 Docker 登入資料的本機複本。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 如需在 Amazon Linux 發行版本上安裝 Docker 的詳細資訊，請參閱《Amazon *Elastic Container Service *[開發人員指南》中的 Amazon ECS 的 Docker 基本概念](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html)。 + 安裝在 Greengrass 核心上的 [Docker Compose](https://docs.docker.com/compose/install/)。`docker-compose` 可執行檔必須位於 `/usr/bin` 或 `/usr/local/bin` 目錄中。 下列 Docker Compose 版本經過驗證，可與連接器搭配使用。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/docker-app-connector.html) + 存放在 Amazon Simple Storage Service (Amazon S3`docker-compose.yml`) 中的單一 Docker Compose 檔案 （例如 )。格式必須與安裝在核心上的 Docker Compose 版本相容。在您的核心上使用該文件前，請先測試該文件。如果您在部署 Greengrass 群組後才編輯檔案，則必須重新部署群組，以更新核心上的本機複本。 + 具有呼叫本機 Docker 協助程式之權限的 Linux 使用者，以及寫入儲存 Compose 檔案本機複本的目錄。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 + 已將 [Greengrass 群組角色](group-role.md)設定為允許在包含 Compose 檔案的 S3 儲存貯體上執行 `s3:GetObject` 動作。此許可會顯示在下列範例 IAM 政策中。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowAccessToComposeFileS3Bucket", "Action": [ "s3:GetObject", "s3:GetObjectVersion" ], "Effect": "Allow", "Resource": "arn:aws:s3:::bucket-name/*" } ] } ``` ------ **注意** 如果您的 S3 儲存貯體已啟用版本控制，則必須設定 角色以允許 `s3:GetObjectVersion`動作。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 + 如果您的 Docker Compose 檔案參考存放在 Amazon ECR 中的 Docker 映像，則 [Greengrass 群組角色](group-role.md)會設定為允許下列項目： + `ecr:GetDownloadUrlForLayer` Amazon ECR 儲存庫上包含 Docker 映像的 和 `ecr:BatchGetImage`動作。 + 您資源上的 `ecr:GetAuthorizationToken` 動作。 儲存庫必須與連接器位於相同的 AWS 帳戶 和 AWS 區域 。 **重要** 群組角色中的許可可由 Greengrass 群組中的所有 Lambda 函數和連接器擔任。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 這些權限會顯示在下列範例政策中。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowGetEcrRepositories", "Effect": "Allow", "Action": [ "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": [ "arn:aws:ecr:us-east-1:123456789012:repository/repository-name" ] }, { "Sid": "AllowGetEcrAuthToken", "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" } ] } ``` ------ 如需詳細資訊，請參閱《[Amazon ECR 使用者指南》中的 Amazon ECR 儲存庫政策範例](https://docs.aws.amazon.com/AmazonECR/latest/userguide/RepositoryPolicyExamples.html)。 ** 針對群組角色要求，您必須設定角色以授與必要的許可，並確認已將角色新增至群組。如需詳細資訊，請參閱 [管理 Greengrass 群組角色 (主控台)](group-role.md#manage-group-role-console) 或 [管理 Greengrass 群組角色 (CLI)](group-role.md#manage-group-role-cli) 。 + 如果您的 Docker Compose 檔案從 [AWS Marketplace](https://aws.amazon.com/marketplace) 中參考 Docker 影像，則連接器也會有下列需求： + 您必須訂閱 AWS Marketplace 容器產品。如需詳細資訊，請參閱《 *AWS Marketplace 訂閱者指南*》中的[尋找和訂閱容器產品](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-finding-and-subscribing-to-container-products.html)。 + AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。連接器只會使用此功能從 擷取您的秘密 AWS Secrets Manager，而不是存放秘密。 + 您必須在 Secrets Manager 中為儲存 Compose 檔案中參考之 Docker 映像的每個 AWS Marketplace 登錄檔建立秘密。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 + 如果您的 Docker Compose 檔案參考 Amazon ECR 以外的登錄檔中私有儲存庫的 Docker 映像，例如 Docker Hub，連接器也具有下列需求： + AWS IoT Greengrass 必須設定為支援本機秘密，如[秘密要求](secrets.md#secrets-reqs)中所述。連接器只會使用此功能從 擷取您的秘密 AWS Secrets Manager，而不是存放秘密。 + 您必須在 Secrets Manager 中為儲存 Compose 檔案中參考之 Docker 映像的每個私有儲存庫建立秘密。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 + 部署包含此連接器的 Greengrass 群組時，必須執行 Docker 協助程式。 ### 從私有儲存庫存取 Docker 影像 如果您使用登入資料來存取 Docker 影像，則必須允許連接器存取它們。此作法取決於 Docker 影像的位置。 對於存放 Amazon ECR 的 Docker 映像，您授予在 Greengrass 群組角色中取得授權字符的許可。如需詳細資訊，請參閱[要求](#docker-app-connector-req)。 對於存放在其他私有儲存庫或登錄檔中的 Docker 映像，您必須在 中建立秘密 AWS Secrets Manager ，以存放您的登入資訊。這包括您訂閱的 Docker 映像 AWS Marketplace。為每個儲存庫建立一個秘密。如果您在 Secrets Manager 中更新秘密，則變更會在您下次部署群組時傳播至核心。 **注意** Secrets Manager 是一項服務，可用來在 中安全地存放和管理登入資料、金鑰和其他秘密 AWS 雲端。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。 每個秘密都必須包含下列金鑰： | 金鑰 | 值 | | --- | --- | | `username` | 用來存取儲存庫或登錄檔的使用者名稱。 | | `password` | 用來存取儲存庫或登錄的密碼。 | | `registryUrl` | 登錄檔的端點。這必須符合 Compose 檔案中對應的登錄檔 URL。 | **注意** 若要允許 根據預設 AWS IoT Greengrass 存取秘密，秘密的名稱必須以 *greengrass-* 開頭。否則，您的 Greengrass 服務角色必須授與存取權。如需詳細資訊，請參閱[允許 AWS IoT Greengrass 取得秘密值](secrets.md#secrets-config-service-role)。 **從 AWS Marketplace取得 Docker 影像的登入資訊** 1. 使用 `aws ecr get-login-password`命令 AWS Marketplace 從 取得 Docker 映像的密碼。如需詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 [get-login-password](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login.html)。 ``` aws ecr get-login-password ``` 1. 擷取 Docker 映像的登錄 URL。開啟 AWS Marketplace 網站，並開啟容器產品啟動頁面。在**容器映像**下，選擇**檢視容器映像詳細資訊**以尋找使用者名稱和登錄 URL。 使用擷取的使用者名稱、密碼和登錄檔 URL，為儲存 Compose 檔案中參考之 Docker 映像的每個 AWS Marketplace 登錄檔建立秘密。 **建立秘密 (主控台)** 在 AWS Secrets Manager 主控台中，選擇**其他類型的秘密**。在 **Specify the key/value pairs to be stored for this secret (指定此秘密要儲存的索引鍵/值組)** 下，新增 `username`、`password` 和 `registryUrl` 的列。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 ![\[用使用者名稱、密碼和註冊庫 URL 金鑰建立一個秘密。\]](http://docs.aws.amazon.com/zh_tw/greengrass/v1/developerguide/images/connectors/secret-docker-trusted-registry.png) **建立秘密 (CLI)** 在 中 AWS CLI，使用 Secrets Manager `create-secret`命令，如下列範例所示。如需詳細資訊，請參閱《 *AWS CLI 命令參考*》中的 [create-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html)。 ``` aws secretsmanager create-secret --name greengrass-MySecret --secret-string [{"username":"Mary_Major"},{"password":"abc123xyz456"},{"registryUrl":"https://docker.io"}] ``` **重要** 您有責任保護儲存 Docker Compose 檔案的 `DockerComposeFileDestinationPath` 目錄以及私有儲存庫的 Docker 影像登入資料的安全。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 ## Parameters 此連接器提供下列參數： ------ #### [ Version 7 ] `DockerComposeFileS3Bucket` 包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案** 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`false` 類型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑** 必要：`true` 類型：`string` 有效模式 `\/.*\/?` 範例：`/home/username/myCompose` `DockerUserId` 連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID** 必要：`false` 類型：`string` 有效模式： `^[0-9]{1,5}$` `AWSSecretsArnList` 中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 在 AWS IoT 主控台中顯示名稱：**私有儲存庫的登入資料** 必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。 類型： `array` 的 `string` 有效模式： `[( ?,? ?"(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 主控台中的顯示名稱：**記錄頻率** 必要：`false` 類型：`string` 有效模式： `^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。 在 AWS IoT 主控台中顯示名稱：**強制部署** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `DockerPullBeforeUp` 指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。 在 AWS IoT 主控台中顯示名稱：**Docker Pull Before Up** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `StopContainersOnNewDeployment` 指出連接器在 GGC 停止時是否應停止 Docker Deployer 受管 Docker 容器 （在部署新群組或核心關閉時，GGC 會停止）。預設值為 `True`。 在 AWS IoT 主控台中顯示名稱：**Docker 在新部署時停止** 我們建議將此參數設定為預設值`True`。的 參數`False`會導致您的 Docker 容器在終止 AWS IoT Greengrass 核心或啟動新部署後繼續執行。如果您將此參數設定為 `False`，則必須確保在`docker-compose`服務名稱變更或新增時，視需要維護 Docker 容器。 如需詳細資訊，請參閱 `docker-compose` compose 檔案文件。 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `DockerOfflineMode` 指出在離線 AWS IoT Greengrass 啟動時是否使用現有的 Docker Compose 檔案。預設值為 `False`。 必要：`false` 類型：`string` 有效模式： `^(true|false)$` ------ #### [ Version 6 ] `DockerComposeFileS3Bucket` 包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案** 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`false` 類型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑** 必要：`true` 類型：`string` 有效模式 `\/.*\/?` 範例：`/home/username/myCompose` `DockerUserId` 連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID** 必要：`false` 類型：`string` 有效模式： `^[0-9]{1,5}$` `AWSSecretsArnList` 中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料** 必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。 類型： `array` 的 `string` 有效模式： `[( ?,? ?"(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 主控台中顯示名稱：**記錄頻率** 必要：`false` 類型：`string` 有效模式： `^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。 在 AWS IoT 主控台中顯示名稱：**強制部署** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `DockerPullBeforeUp` 指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。 AWS IoT 主控台中的顯示名稱：**Docker Pull Before Up** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `StopContainersOnNewDeployment` 指出連接器在 GGC 停止時 （建立新群組部署時，或核心關閉時），是否應停止 Docker Deployer 受管 Docker 容器。預設值為 `True`。 在 AWS IoT 主控台中顯示名稱：在**新部署時停止 Docker** 我們建議將此參數設定為預設值`True`。的 參數`False`會導致您的 Docker 容器在終止 AWS IoT Greengrass 核心或啟動新部署後繼續執行。如果您將此參數設定為 `False`，則必須確保在`docker-compose`服務名稱變更或新增時，視需要維護 Docker 容器。 如需詳細資訊，請參閱 `docker-compose` compose 檔案文件。 必要：`false` 類型：`string` 有效模式： `^(true|false)$` ------ #### [ Version 5 ] `DockerComposeFileS3Bucket` 包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案** 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`false` 類型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑** 必要：`true` 類型：`string` 有效模式 `\/.*\/?` 範例：`/home/username/myCompose` `DockerUserId` 連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID** 必要：`false` 類型：`string` 有效模式： `^[0-9]{1,5}$` `AWSSecretsArnList` 中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料** 必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。 類型： `array` 的 `string` 有效模式： `[( ?,? ?"(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 主控台中顯示名稱：**記錄頻率** 必要：`false` 類型：`string` 有效模式： `^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。 AWS IoT 主控台中的顯示名稱：**強制部署** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` `DockerPullBeforeUp` 指出部署器是否應在執行 `docker-compose pull` 之前執行 `docker-compose up`以進行下拉式行為。 pull-down-up 預設值為 `True`。 在 AWS IoT 主控台中顯示名稱：**Docker Pull Before Up** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` ------ #### [ Versions 2 - 4 ] `DockerComposeFileS3Bucket` 包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案** 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`false` 類型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑** 必要：`true` 類型：`string` 有效模式 `\/.*\/?` 範例：`/home/username/myCompose` `DockerUserId` 連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID** 必要：`false` 類型：`string` 有效模式： `^[0-9]{1,5}$` `AWSSecretsArnList` 中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料** 必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。 類型： `array` 的 `string` 有效模式： `[( ?,? ?"(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 主控台中的顯示名稱：**記錄頻率** 必要：`false` 類型：`string` 有效模式： `^[1-9]{1}[0-9]{0,3}$` `ForceDeploy` 指出是否因為上次部署的不當清除而使 Docker 部署失敗。預設值為 `False`。 AWS IoT 主控台中的顯示名稱：**強制部署** 必要：`false` 類型：`string` 有效模式： `^(true|false)$` ------ #### [ Version 1 ] `DockerComposeFileS3Bucket` 包含 Docker Compose 檔案的 S3 儲存貯體名稱。當您建立儲存貯體時，請務必遵循 *Amazon Simple Storage Service 使用者指南*中所述[的儲存貯體名稱規則](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)。 在 AWS IoT 主控台中顯示名稱：**S3 中的 Docker Compose 檔案** 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `[a-zA-Z0-9\\-\\.]{3,63}` `DockerComposeFileS3Key` Amazon S3 中 Docker Compose 檔案的物件金鑰。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[物件金鑰和中繼資料](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`true` 類型：`string` 有效模式 `.+` `DockerComposeFileS3Version` Amazon S3 中 Docker Compose 檔案的物件版本。如需詳細資訊，包括物件金鑰命名準則，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用版本控制](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html)。 在主控台中，**Docker Compose file in S3 (S3 中的 Docker Compose 檔案)** 屬性會結合 `DockerComposeFileS3Bucket`、`DockerComposeFileS3Key` 和 `DockerComposeFileS3Version` 參數。 必要：`false` 類型：`string` 有效模式 `.+` `DockerComposeFileDestinationPath` 用來儲存 Docker Compose 檔案複本的本機目錄絕對路徑。這必須是現有目錄。`DockerUserId` 的指定使用者必須具有在此目錄中建立檔案的權限。如需詳細資訊，請參閱[在 AWS IoT Greengrass 核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 儲存 Docker Compose 檔案的目錄以及私有儲存庫的 Docker 影像登入資料的安全。您有責任保護此目錄。如需詳細資訊，請參閱[安全注意事項](#docker-app-connector-security)。 在 AWS IoT 主控台中顯示名稱：**本機 Compose 檔案的目錄路徑** 必要：`true` 類型：`string` 有效模式 `\/.*\/?` 範例：`/home/username/myCompose` `DockerUserId` 連接器用於執行的 Linux 使用者 UID。此使用者必須屬於核心裝置上的 `docker` Linux 群組，並具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。如需詳細資訊，請參閱[在核心上設定 Docker 使用者](#docker-app-connector-linux-user)。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 在 AWS IoT 主控台中顯示名稱：**Docker 使用者 ID** 必要：`false` 類型：`string` 有效模式： `^[0-9]{1,5}$` `AWSSecretsArnList` 中秘密的 Amazon Resource Name (ARNs)， AWS Secrets Manager 其中包含用於存取私有儲存庫中 Docker 映像的登入資訊。如需詳細資訊，請參閱[從私有儲存庫存取 Docker 影像](#access-private-repositories)。 AWS IoT 主控台中的顯示名稱：**私有儲存庫的登入資料** 必要：`false`。此參數需要存取儲存在私有儲存庫中的 Docker 影像。 類型： `array` 的 `string` 有效模式： `[( ?,? ?"(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 主控台中顯示名稱：**記錄頻率** 必要：`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": "amzn-s3-demo-bucket", "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 函數具有[長期生命週期](lambda-functions.md#lambda-lifecycle)。 ## 輸入資料 此連接器不需要或接受輸入資料。 ## 輸出資料 此連接器將 `docker-compose up` 命令的狀態發佈為輸出資料。 **訂閱中的主題篩選條件** `dockerapplicationdeploymentconnector/message/status` **範例輸出：成功** ``` { "status":"success", "GreengrassDockerApplicationDeploymentStatus":"Successfully triggered docker-compose up", "S3Bucket":"amzn-s3-demo-bucket", "ComposeFileName":"production-docker-compose.yml", "ComposeFileVersion":"123" } ``` **範例輸出：失敗** ``` { "status":"fail", "error_message":"description of error", "error":"InvalidParameter" } ``` 錯誤類型可以是 `InvalidParameter` 或 `InternalError`。 ## 在 AWS IoT Greengrass 核心上設定 Docker 使用者 Greengrass Docker 應用程式部署連接器會以您為 `DockerUserId` 參數指定的使用者身分執行。如果您未指定值，連接器會以 `ggc_user` 為身分執行，這也是預設 Greengrass 存取身分。 若要允許連接器與 Docker 協助程式互動，Docker 使用者必須屬於核心上的 `docker` Linux 群組。Docker 使用者也必須具有 `DockerComposeFileDestinationPath` 目錄的寫入權限。這是連接器儲存本機 `docker-compose.yml` 檔案和 Docker 登入資料的位置。 **注意** 建議您建立 Linux 使用者，不要使用預設值 `ggc_user`。否則，Greengrass 群組中的任何 Lambda 函數都可以存取 Compose 檔案和 Docker 登入資料。 我們建議您除非必要，避免以 root 身分執行。如果您指定根使用者，則必須允許 Lambda 函數以根身分在 AWS IoT Greengrass 核心上執行。如需詳細資訊，請參閱[執行 Lambda 函數做為根](lambda-group-config.md#lambda-running-as-root)。 1. 建立使用者。您可以執行 `useradd` 命令，並包含選用的 `-u` 選項來指派 UID。例如： ``` sudo useradd -u 1234 user-name ``` 1. 將使用者新增至核心上的 `docker` 群組。例如： ``` sudo usermod -aG docker user-name ``` 如需詳細資訊 (包括如何建立 `docker` 群組)，請參閱 Docker 文件中 [Manage Docker as a non-root user](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) (以非根使用者身分管理 Docker)。 1. 授予使用者寫入 `DockerComposeFileDestinationPath` 參數指定目錄的權限。例如： 1. 將使用者設定為目錄的擁有者。這個範例會使用步驟 1 中的 UID。 ``` chown 1234 docker-compose-file-destination-path ``` 1. 將讀取和寫入權限提供給擁有者。 ``` chmod 700 docker-compose-file-destination-path ``` 如需詳細資訊，請參閱 Linux 基礎文件中的 [How To Manage File And Folder Permissions In Linux](https://www.linux.com/tutorials/how-manage-file-and-folder-permissions-linux/) (如何管理 Linux 中的檔案及資料夾權限)。 1. 如果您在建立使用者時未指派 UID，或者，您使用現有使用者，請執行 `id` 命令以查詢 UID。 ``` id -u user-name ``` 您可以使用 UID 來設定連接器的 `DockerUserId` 參數。 ## 用量資訊 當您使用 Greengrass Docker 應用程式部署連接器時，您應該注意下列實作特定的使用資訊。 + **已修正專案名稱的字首。**連接器會在它啟動的 Docker 容器名稱前加上 `greengrassdockerapplicationdeployment` 字首。連接器在其執行的 `docker-compose` 指令中使用此字首做為專案名稱。 + **記錄行為。**連接器會將狀態資訊和疑難排解資訊寫入日誌檔案。您可以設定 AWS IoT Greengrass 將日誌傳送至 CloudWatch Logs，並在本機寫入日誌。如需詳細資訊，請參閱[連接器的記錄](connectors.md#connectors-logging)。這是連接器本機記錄檔的路徑： ``` /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](https://docs.docker.com/engine/reference/commandline/rm/)。 + **執行 Docker 命令。**若要對問題進行疑難排解，可以在核心裝置的終端機視窗中執行 Docker 命令。例如，執行下列命令以查看連接器啟動的 Docker 容器： ``` docker ps --filter name="greengrassdockerapplicationdeployment" ``` + **預留資源 ID。**連接器會使用其在 Greengrass 群組中建立的 Greengrass 資源 `DOCKER_DEPLOYER_SECRET_RESOURCE_RESERVED_ID_index` ID。資源 ID 在群組中不得重複，因此請勿指派可能與此保留資源 ID 衝突的資源 ID。 + **離線模式。**當您將`DockerOfflineMode`組態參數設定為 時`True`，Docker 連接器可以*離線模式*操作。當 Greengrass 群組部署在核心裝置離線時重新啟動，且連接器無法建立與 Amazon S3 或 Amazon ECR 的連線以擷取 Docker Compose 檔案時，就會發生這種情況。 啟用離線模式時，連接器會嘗試下載 Compose 檔案，並像在正常重新啟動時一樣執行`docker login`命令。如果這些嘗試失敗，則連接器會在使用 `DockerComposeFileDestinationPath` 參數指定的資料夾中尋找本機儲存的 Compose 檔案。如果本機 Compose 檔案存在，則連接器會遵循正常的`docker-compose`命令順序，並從本機映像提取 。如果 Compose 檔案或本機映像不存在，則連接器會失敗。在離線模式下， `ForceDeploy`和 `StopContainersOnNewDeployment` 參數的行為保持不變。 ## 與 Docker 容器通訊 AWS IoT Greengrass 支援 Greengrass 元件和 Docker 容器之間的下列通訊管道： + Greengrass Lambda 函數可以使用 REST APIs 與 Docker 容器中的程序通訊。您可以在開啟連接埠的 Docker 容器中設定伺服器。Lambda 函數可以與此連接埠上的容器通訊。 + Docker 容器中的處理程序可以透過本機 Greengrass 訊息中介裝置交換 MQTT 訊息。您可以在 Greengrass 群組中將 Docker 容器設定為用戶端裝置，然後建立訂閱，以允許容器與群組中的 Greengrass Lambda 函數、用戶端裝置和其他連接器通訊，或與 AWS IoT 和本機影子服務通訊。如需詳細資訊，請參閱[設定與 Docker 容器的 MQTT 通訊](#docker-app-connector-mqtt-communication)。 + Greengrass Lambda 函數可以更新共用檔案，以將資訊傳遞至 Docker 容器。您可以使用 Compose 檔案綁定掛載 Docker 容器的共用檔案路徑。 ### 設定與 Docker 容器的 MQTT 通訊 您可以將 Docker 容器設定為用戶端裝置，並將其新增至 Greengrass 群組。然後，您可以建立訂閱，以允許 Docker 容器和 Greengrass 元件或 AWS IoT之間的 MQTT 通訊。在下列程序中，您會建立訂閱，允許 Docker 容器裝置接收來自本機陰影服務的陰影更新訊息。您可以遵循此模式來建立其他訂閱。 **注意** 此程序假設您已建立 Greengrass 群組和 Greengrass 核心 (v1.10 或更新版本）。如需建立 Greengrass 群組和核心的詳細資訊，請參閱 [入門 AWS IoT Greengrass](gg-gs.md)。 **將 Docker 容器設定為用戶端裝置，並將其新增至 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 ``` 1. 在 AWS IoT 主控台導覽窗格的**管理**下，展開 **Greengrass 裝置**，然後選擇**群組 (V1)**。 1. 選擇目標群組。 1. 在群組組態頁面上，選擇**用戶端裝置**，然後選擇**關聯**。 1. 在**將用戶端裝置與此群組模型建立關聯**中，選擇**建立新 AWS IoT 物件**。 **建立物件**頁面會在新標籤中開啟。 1. 在**建立物件**頁面上，選擇**建立單一物件**，然後選擇**下一步**。 1. 在**指定物件屬性**頁面上，輸入裝置的名稱，然後選擇**下一步**。 1. 在**設定裝置憑證**頁面上，選擇**下一步**。 1. 在**將政策連接至憑證**頁面上，執行下列其中一項操作： + 選取授予用戶端裝置所需許可的現有政策，然後選擇**建立物件**。 模態開啟，您可以在其中下載裝置用來連線至 和 核心的憑證 AWS 雲端 和金鑰。 + 建立並連接授予用戶端裝置許可的新政策。請執行下列操作： 1. 選擇**建立政策**。 **Create policy (建立政策)** 頁面隨即在新標籤中開啟。 1. 在 **Create policy (建立政策)** 頁面上，執行下列動作： 1. 針對**政策名稱**，輸入描述政策的名稱，例如 **GreengrassV1ClientDevicePolicy**。 1. 在**政策陳述**式索引標籤**的政策文件**下，選擇 **JSON**。 1. 輸入下列政策文件。此政策可讓用戶端裝置探索 Greengrass 核心，並在所有 MQTT 主題上進行通訊。如需如何限制此政策存取的資訊，請參閱 [的裝置身分驗證和授權 AWS IoT Greengrass](device-auth.md)。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Subscribe", "iot:Connect", "iot:Receive" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "greengrass:*" ], "Resource": [ "*" ] } ] } ``` ------ 1. 選擇 **Create (建立)** 以建立政策。 1. 返回瀏覽器索引標籤，開啟**附加政策至憑證**頁面。請執行下列操作： 1. 在**政策**清單中，選取您建立的政策，例如 **GreengrassV1ClientDevicePolicy**。 如果您沒有看到政策，請選擇重新整理按鈕。 1. 選擇 **Create thing** (建立物件)。 模態開啟，您可以在其中下載裝置用來連線至 和 核心的憑證 AWS 雲端 和金鑰。 1. 在**下載憑證和金鑰**模態中，下載裝置的憑證。 **重要** 選擇**完成**之前，請下載安全資源。 請執行下列操作： 1. 針對**裝置憑證**，選擇**下載**以下載裝置憑證。 1. 針對**公有金鑰檔案**，選擇**下載**以下載憑證的公有金鑰。 1. 針對**私有金鑰檔案**，選擇**下載**以下載憑證的私有金鑰檔案。 1. 檢閱《 *AWS IoT 開發人員指南*》中的[伺服器身分驗證](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html)，然後選擇適當的根 CA 憑證。我們建議您使用 Amazon Trust Services (ATS) 端點和 ATS 根 CA 憑證。在**根 CA 憑證**下，選擇根 CA 憑證的**下載**。 1. 選擇**完成**。 請記下裝置憑證和金鑰檔案名稱中常見的憑證 ID。供稍後使用。 1. 將憑證和金鑰複製到您在步驟 1 中建立的資料夾。 接下來，在群組中建立訂閱。在此範例中，您可以建立訂閱讓 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息。 **注意** 陰影文件的大小上限為 8 KB。如需詳細資訊，請參閱《 *AWS IoT 開發人員指南*》中的[AWS IoT 配額](https://docs.aws.amazon.com/iot/latest/developerguide/limits-iot.html)。 **建立訂閱，允許 Docker 容器裝置接收來自本機陰影服務的 MQTT 訊息** 1. 在群組組態頁面上，選擇**訂閱**索引標籤，然後選擇**新增訂閱**。 1. 在 **Select your source and target (選擇您的來源和目標)** 頁面設定來源和目標，如下所示： 1. 在 **Select a source (選取來源)** 中，選擇 **Services (服務)**，然後選擇 **Local Shadow Service (本機陰影服務)**。 1. 在 **Select a target (選取目標)**，選擇 **Devices (裝置)**，然後選擇您的裝置。 1. 選擇**下一步**。 1. 在**使用主題篩選資料**頁面上，針對**主題篩選**，選擇 **\$1aws/things/*MyDockerDevice*/shadow/update/accepted**，然後選擇**下一步**。將 *MyDockerDevice* 取代為您先前建立的裝置名稱。 1. 選擇**完成**。 在您在 Compose 檔案中參考的 Docker 影像中，加入下列程式碼片段。這是 Greengrass 裝置程式碼。另外，請在 Docker 容器中新增程式碼，以啟動容器內的 Greengrass 設備。它可以在影像中或獨立的執行緒中，以個別程序來執行。 ``` import os import sys import time import uuid from AWSIoTPythonSDK.core.greengrass.discovery.providers import DiscoveryInfoProvider from AWSIoTPythonSDK.exception.AWSIoTExceptions import DiscoveryInvalidRequestException from AWSIoTPythonSDK.MQTTLib import AWSIoTMQTTClient # Replace thingName with the name you registered for the Docker device. thingName = "MyDockerDevice" clientId = thingName # Replace host with the IoT endpoint for your &AWS-account;. host = "myPrefix.iot.region.amazonaws.com" # Replace topic with the topic where the Docker container subscribes. topic = "$aws/things/MyDockerDevice/shadow/update/accepted" # Replace these paths based on the download location of the certificates for the Docker container. rootCAPath = "/path-accessible-in-container/AmazonRootCA1.pem" certificatePath = "/path-accessible-in-container/certId-certificate.pem.crt" privateKeyPath = "/path-accessible-in-container/certId-private.pem.key" # Discover Greengrass cores. discoveryInfoProvider = DiscoveryInfoProvider() discoveryInfoProvider.configureEndpoint(host) discoveryInfoProvider.configureCredentials(rootCAPath, certificatePath, privateKeyPath) discoveryInfoProvider.configureTimeout(10) # 10 seconds. GROUP_CA_PATH = "./groupCA/" MQTT_QOS = 1 discovered = False groupCA = None coreInfo = None try: # Get discovery info from AWS IoT. discoveryInfo = discoveryInfoProvider.discover(thingName) caList = discoveryInfo.getAllCas() coreList = discoveryInfo.getAllCores() # Use first discovery result. groupId, ca = caList[0] coreInfo = coreList[0] # Save the group CA to a local file. groupCA = GROUP_CA_PATH + groupId + "_CA_" + str(uuid.uuid4()) + ".crt" if not os.path.exists(GROUP_CA_PATH): os.makedirs(GROUP_CA_PATH) groupCAFile = open(groupCA, "w") groupCAFile.write(ca) groupCAFile.close() discovered = True except DiscoveryInvalidRequestException as e: print("Invalid discovery request detected!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) print("Stopping...") except BaseException as e: print("Error in discovery!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) print("Stopping...") myAWSIoTMQTTClient = AWSIoTMQTTClient(clientId) myAWSIoTMQTTClient.configureCredentials(groupCA, privateKeyPath, certificatePath) # Try to connect to the Greengrass core. connected = False for connectivityInfo in coreInfo.connectivityInfoList: currentHost = connectivityInfo.host currentPort = connectivityInfo.port myAWSIoTMQTTClient.configureEndpoint(currentHost, currentPort) try: myAWSIoTMQTTClient.connect() connected = True except BaseException as e: print("Error in connect!") print("Type: %s" % str(type(e))) print("Error message: %s" % str(e)) if connected: break 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 an MQTT message") print(message) # Subscribe to the MQTT topic. myAWSIoTMQTTClient.subscribe(topic, MQTT_QOS, 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](https://docs.docker.com/engine/reference/commandline/login/#credentials-store)。 **從可信任來源安裝 Docker Engine** 您有責任從可信任來源安裝 Docker Engine。此連接器使用核心裝置上的 Docker 協助程式，存取您的 Docker 資產並管理 Docker 容器。 **Greengrass 群組角色權限的範圍** 您在 Greengrass 群組角色中新增的許可，可由 Greengrass 群組中的所有 Lambda 函數和連接器擔任。此連接器需要存取儲存 S3 儲存貯體中的 Docker Compose 檔案。如果您的 Docker 映像存放在 Amazon ECR 中的私有儲存庫中，它也需要存取您的 Amazon ECR 授權字符。 ## 授權 Greengrass Docker 應用程式部署連接器包含下列第三方軟體/授權： + [適用於 Python (Boto3) 的 AWS SDK](https://pypi.org/project/boto3/)/Apache License 2.0 + [botocore](https://pypi.org/project/botocore/)/Apache License 2.0 + [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License + [docutils](https://pypi.org/project/docutils/)/BSD 授權、GNU 一般公有授權 (GPL)、Python 軟體基金會授權、公有網域 + [jmespath](https://pypi.org/project/jmespath/)/MIT License + [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0 + [urllib3](https://pypi.org/project/urllib3/)/MIT License 此連接器根據 [Greengrass 核心軟體授權合約](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf)發行。 ## 變更記錄 下表說明每個版本連接器的變更。 | 版本 | 變更 | | --- | --- | | 7 | 新增`DockerOfflineMode`以在離線 AWS IoT Greengrass 啟動時使用現有的 Docker Compose 檔案。已實作`docker login`命令的重試。支援 32 位元 UIDs。 | | 6 | 新增`StopContainersOnNewDeployment`以在進行新部署或 GGC 停止時覆寫容器清除。更安全的關機和啟動機制。YAML 驗證錯誤修正。 | | 5 | 映像會在執行 之前提取`docker-compose down`。 | | 4 | 新增pull-before-up行為以更新 Docker 映像。 | | 3 | 修正了尋找環境變數的問題。 | | 2 | 新增 `ForceDeploy` 參數。 | | 1 | 初始版本。 | Greengrass 群組一次只能包含一個版本的連接器。若要取得有關升級連接器版本的資訊，請參閱[升級連接器版本](connectors.md#upgrade-connector-versions)。 ## 另請參閱 + [使用 Greengrass 連接器來整合服務和通訊協定](connectors.md) + [Greengrass 連接器入門 (主控台)](connectors-console.md) + [Greengrass 連接器入門 (CLI)](connectors-cli.md)