本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT Greengrass 在具有自動資源佈建的 Docker 容器中執行
本教學課程說明如何使用自動佈建 AWS 的資源和本機開發工具，在 Docker 容器中安裝和執行 AWS IoT Greengrass Core 軟體。您可以使用此開發環境來探索 Docker 容器中 AWS IoT Greengrass 的功能。軟體需要 AWS 登入資料才能佈建這些資源並部署本機開發工具。
如果您無法提供 AWS 登入資料給容器，您可以佈建 AWS 核心裝置操作所需的資源。您也可以將開發工具部署到核心裝置，以用作開發裝置。這可讓您在執行容器時為裝置提供較少的許可。如需詳細資訊，請參閱[AWS IoT Greengrass 在具有手動資源佈建的 Docker 容器中執行](run-greengrass-docker-manual-provisioning.md)。
## 先決條件
若要完成本教學課程，您需要下列項目。
+ AWS 帳戶。如果您沒有帳戶，請參閱 [設定 AWS 帳戶](setting-up.md#set-up-aws-account)。
+ 具有為 Greengrass AWS 核心裝置佈建 AWS IoT 和 IAM 資源許可的 IAM 使用者。Core AWS IoT Greengrass 軟體安裝程式使用您的 AWS 登入資料來自動佈建這些資源。如需自動佈建資源的最低 IAM 政策資訊，請參閱 [安裝程式佈建資源的最低 IAM 政策](provision-minimal-iam-policy.md)。
+ Docker AWS IoT Greengrass 映像。您可以從 [Dockerfile AWS IoT Greengrass 建置映像](build-greengrass-dockerfile.md)。
+ 您執行 Docker 容器的主機電腦必須符合下列要求：
+ 具有網際網路連線的 Linux 作業系統。
+ [Docker 引擎](https://docs.docker.com/engine/install/) 18.09 版或更新版本。
+ （選用） [Docker Compose](https://docs.docker.com/compose/install/) 1.22 版或更新版本。只有在您想要使用 Docker Compose CLI 執行 Docker 映像時，才需要 Docker Compose。
## 設定您的 AWS 登入資料
在此步驟中，您會在包含安全 AWS 登入資料的主機電腦上建立登入資料檔案。當您執行 AWS IoT Greengrass Docker 映像時，您必須在 Docker 容器中將包含此登入資料檔案的資料夾掛載至 `/root/.aws/` 。 AWS IoT Greengrass 安裝程式使用這些登入資料來佈建 中的資源 AWS 帳戶。如需安裝程式自動佈建資源所需的最低 IAM 政策的相關資訊，請參閱 [安裝程式佈建資源的最低 IAM 政策](provision-minimal-iam-policy.md)。
1. 擷取下列其中一項。
+ IAM 使用者的長期登入資料。如需如何擷取長期憑證的資訊，請參閱《[IAM 使用者指南》中的管理 IAM 使用者的存取金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)。 **
+ （建議） IAM 角色的暫時登入資料。如需如何擷取臨時登入資料的資訊，請參閱《*IAM 使用者指南*》中的[搭配 使用臨時安全登入 AWS CLI](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html#using-temp-creds-sdk-cli)資料。
1. 建立放置登入資料檔案的資料夾。
```
mkdir ./greengrass-v2-credentials
```
1. 使用文字編輯器在 `./greengrass-v2-credentials` 資料夾中建立名為 `credentials`的組態檔案。
例如，您可以執行下列命令，使用 GNU nano 建立 `credentials` 檔案。
```
nano ./greengrass-v2-credentials/credentials
```
1. 以下列格式將您的 AWS 登入資料新增至 `credentials` 檔案。
```
[default]
aws_access_key_id = {{AKIAIOSFODNN7EXAMPLE}}
aws_secret_access_key = {{wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY}}
aws_session_token = {{AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk}}
```
僅包含`aws_session_token`暫時登入資料。
**重要**
啟動 AWS IoT Greengrass 容器後，請從主機電腦移除登入資料檔案。如果您不移除登入資料檔案，您的 AWS 登入資料將保持掛載在容器內。如需詳細資訊，請參閱[在容器中執行 AWS IoT Greengrass 核心軟體](#run-greengrass-image-automatic-provisioning)。
## 建立環境檔案
本教學課程使用環境檔案來設定將傳遞至 Docker 容器內 AWS IoT Greengrass Core 軟體安裝程式的環境變數。您也可以在`docker run`命令中使用 [`-e`或 `--env`引數](https://docs.docker.com/engine/reference/commandline/run/#env)，在 Docker 容器中設定環境變數，也可以在 `docker-compose.yml` 檔案的 [`environment`區塊](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment)中設定變數。
1. 使用文字編輯器來建立名為 的環境檔案`.env`。
例如，在以 Linux 為基礎的系統上，您可以執行下列命令，使用 GNU nano `.env` 在目前的目錄中建立 。
```
nano .env
```
1. 將下列內容複製到 檔案。
```
GGC_ROOT_PATH={{/greengrass/v2}}
AWS_REGION={{region}}
PROVISION=true
THING_NAME={{MyGreengrassCore}}
THING_GROUP_NAME={{MyGreengrassCoreGroup}}
TES_ROLE_NAME={{GreengrassV2TokenExchangeRole}}
TES_ROLE_ALIAS_NAME={{GreengrassCoreTokenExchangeRoleAlias}}
COMPONENT_DEFAULT_USER=ggc_user:ggc_group
```
然後，取代下列值。
+ `{{/greengrass/v2}}`。 您要用於安裝的 Greengrass 根資料夾。您可以使用 `GGC_ROOT`環境變數來設定此值。
+ {{區域}}。您建立資源 AWS 區域 的 。
+ {{MyGreengrassCore}}。物件的名稱 AWS IoT 。如果物件不存在，安裝程式會建立它。安裝程式會下載憑證以驗證為 AWS IoT 實物。
+ {{MyGreengrassCoreGroup}}。 AWS IoT 物件群組的名稱。如果物件群組不存在，安裝程式會建立它，並將該物件新增至其中。如果物件群組存在且具有作用中部署，核心裝置會下載並執行部署指定的軟體。
+ {{GreengrassV2TokenExchangeRole}}。以允許 Greengrass 核心裝置取得臨時 AWS 登入資料的 IAM 字符交換角色名稱取代 。如果角色不存在，安裝程式會建立它，並建立和連接名為 {{GreengrassV2TokenExchangeRole}} Access 的政策。如需詳細資訊，請參閱[授權核心裝置與 AWS 服務互動](device-service-role.md)。
+ {{GreengrassCoreTokenExchangeRoleAlias}}。字符交換角色別名。如果角色別名不存在，安裝程式會建立它，並將其指向您指定的 IAM 字符交換角色。如需詳細資訊，請參閱
**注意**
您可以將`DEPLOY_DEV_TOOLS`環境變數設定為 `true`以部署 [Greengrass CLI 元件](greengrass-cli-component.md)，這可讓您在 Docker 容器內開發自訂元件。建議您僅在開發環境中使用此元件，而非生產環境中。此元件可讓您存取生產環境中通常不需要的資訊和操作。僅將此元件部署到您需要的核心裝置，以遵循最低權限原則。
## 在容器中執行 AWS IoT Greengrass 核心軟體
本教學課程說明如何啟動您在 Docker 容器中建置的 Docker 映像。您可以使用 Docker CLI 或 Docker Compose CLI 在 Docker 容器中執行 AWS IoT Greengrass 核心軟體映像。
------
#### [ Docker ]
1. 執行下列命令來啟動 Docker 容器。
```
docker run --rm --init -it --name {{docker-image}} \
-v {{path/to/}}greengrass-v2-credentials:/root/.aws/:ro \
--env-file .env \
-p 8883 \
{{your-container-image:version}}
```
此範例命令使用下列引數來執行 [docker：](https://docs.docker.com/engine/reference/commandline/run/)
+ [https://docs.docker.com/engine/reference/run/#clean-up---rm](https://docs.docker.com/engine/reference/run/#clean-up---rm)。 在容器結束時清除容器。
+ [https://docs.docker.com/engine/reference/run/#specify-an-init-process](https://docs.docker.com/engine/reference/run/#specify-an-init-process)。 在容器中使用初始化程序。
**注意**
當您停止 Docker 容器時，需要 `--init`引數來關閉 AWS IoT Greengrass Core 軟體。
+ [https://docs.docker.com/engine/reference/run/#foreground](https://docs.docker.com/engine/reference/run/#foreground)。 （選用） 在前景中以互動式程序執行 Docker 容器。您可以使用 `-d`引數取代此值，以分離模式執行 Docker 容器。如需詳細資訊，請參閱 Docker 文件中的[分離與前景](https://docs.docker.com/engine/reference/run/#detached-vs-foreground)。
+ [https://docs.docker.com/engine/reference/run/#name---name](https://docs.docker.com/engine/reference/run/#name---name)。 執行名為 的容器 `aws-iot-greengrass`
+ [https://docs.docker.com/storage/volumes/](https://docs.docker.com/storage/volumes/)。 將磁碟區掛載到 Docker 容器，讓組態檔案和憑證檔案可供容器內 AWS IoT Greengrass 執行。
+ [https://docs.docker.com/engine/reference/commandline/run/#env](https://docs.docker.com/engine/reference/commandline/run/#env)。 （選用） 指定環境檔案，以設定要傳遞至 Docker 容器內 AWS IoT Greengrass Core 軟體安裝程式的環境變數。只有在您建立[環境檔案](run-greengrass-docker-manual-provisioning.md#create-env-file-manual-provisioning)來設定環境變數時，才需要此引數。如果您未建立環境檔案，您可以使用`--env`引數直接在 Docker 執行命令中設定環境變數。
+ [https://docs.docker.com/engine/reference/commandline/run/#publish](https://docs.docker.com/engine/reference/commandline/run/#publish)。 （選用） 將 8883 容器連接埠發佈至主機。如果您想要透過 MQTT 連接和通訊，則需要此引數，因為 AWS IoT Greengrass 使用連接埠 8883 處理 MQTT 流量。若要開啟其他連接埠，請使用其他引`-p`數。
**注意**
若要以更高的安全性執行 Docker 容器，您可以使用 `--cap-drop`和 `--cap-add`引數來選擇性地為您的容器啟用 Linux 功能。如需詳細資訊，請參閱 Docker 文件中的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。
1. 在主機裝置`./greengrass-v2-credentials`上從 移除登入資料。
```
rm -rf ./greengrass-v2-credentials
```
**重要**
您正在移除這些登入資料，因為它們提供核心裝置只在設定期間需要的廣泛許可。如果您未移除這些登入資料，Greengrass 元件和容器中執行的其他程序可以存取這些登入資料。如果您需要提供 AWS 憑證給 Greengrass 元件，請使用字符交換服務。如需詳細資訊，請參閱[與 AWS 服務互動](interact-with-aws-services.md)。
------
#### [ Docker Compose ]
1. 使用文字編輯器來建立名為 的 Docker Compose 檔案`docker-compose.yml`。
例如，在以 Linux 為基礎的系統上，您可以執行下列命令，使用 GNU nano `docker-compose.yml` 在目前的目錄中建立 。
```
nano docker-compose.yml
```
**注意**
您也可以從 [GitHub](https://github.com/aws-greengrass/aws-greengrass-docker/releases/) 下載並使用 AWS最新版本的 Compose 檔案。
1. 將下列內容新增至 Compose 檔案。您的檔案看起來應該如下列範例：將 {{docker-image}} 取代為 Docker 映像的名稱。
```
version: '3.7'
services:
greengrass:
init: true
container_name: aws-iot-greengrass
image: {{docker-image}}
volumes:
- ./greengrass-v2-credentials:/root/.aws/:ro
env_file: .env
ports:
- "8883:8883"
```
此範例中的下列參數 Compose 檔案為選用：
+ `ports`—發佈 8883 容器連接埠至主機。如果您想要透過 MQTT 連接和通訊，則需要此參數，因為 AWS IoT Greengrass 使用連接埠 8883 處理 MQTT 流量。
+ `env_file`- 指定環境檔案，以設定將傳遞至 Docker 容器內 AWS IoT Greengrass Core 軟體安裝程式的環境變數。只有在您建立[環境檔案](run-greengrass-docker-manual-provisioning.md#create-env-file-manual-provisioning)來設定環境變數時，才需要此參數。如果您未建立環境檔案，您可以使用[環境](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment)參數直接在 Compose 檔案中設定變數。
**注意**
若要以更高的安全性執行 Docker 容器，您可以在 `cap_add` Compose 檔案中使用 `cap_drop`和 ，為您的容器選擇性地啟用 Linux 功能。如需詳細資訊，請參閱 Docker 文件中的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。
1. 執行下列命令來啟動 Docker 容器。
```
docker-compose -f docker-compose.yml up
```
1. 在主機裝置`./greengrass-v2-credentials`上從 移除登入資料。
```
rm -rf ./greengrass-v2-credentials
```
**重要**
您正在移除這些登入資料，因為它們提供核心裝置只在設定期間需要的廣泛許可。如果您未移除這些登入資料，Greengrass 元件和容器中執行的其他程序可以存取這些登入資料。如果您需要提供 AWS 憑證給 Greengrass 元件，請使用字符交換服務。如需詳細資訊，請參閱[與 AWS 服務互動](interact-with-aws-services.md)。
------
## 後續步驟
AWS IoT Greengrass 核心軟體現在正在 Docker 容器中執行。執行下列命令，以擷取目前執行中容器的容器 ID。
```
docker ps
```
然後，您可以執行下列命令來存取容器，並探索在容器內執行 AWS IoT Greengrass 的核心軟體。
```
docker exec -it {{container-id}} /bin/bash
```
如需建立簡單元件的詳細資訊，請參閱 [步驟 4：在您的裝置上開發和測試元件](create-first-component.md)中的 [教學課程：入門 AWS IoT Greengrass V2](getting-started.md)
**注意**
當您使用 在 Docker 容器內`docker exec`執行命令時，這些命令不會記錄在 Docker 日誌中。若要在 Docker 日誌中記錄命令，請將互動式 shell 連接到 Docker 容器。如需詳細資訊，請參閱[將互動式 shell 連接至 Docker 容器](docker-troubleshooting.md#debugging-docker-attach-shell)。
AWS IoT Greengrass 核心日誌檔案稱為 `greengrass.log`，位於 中`{{/greengrass/v2}}/logs`。元件日誌檔案也位於相同的目錄中。若要將 Greengrass 日誌複製到主機上的暫存目錄，請執行下列命令：
```
docker cp {{container-id}}:/greengrass/v2/logs {{/tmp/logs}}
```
如果您想要在容器結束或移除後保留日誌，建議您僅將`{{/greengrass/v2}}/logs`目錄繫結至主機上的暫存日誌目錄，而不是掛載整個 Greengrass 目錄。如需詳細資訊，請參閱[在 Docker 容器外保留 Greengrass 日誌](docker-troubleshooting.md#debugging-docker-persist-logs)。
若要停止執行中的 AWS IoT Greengrass Docker 容器，請執行 `docker stop`或 `docker-compose -f docker-compose.yml stop`。此動作會`SIGTERM`傳送至 Greengrass 程序，並關閉在容器中啟動的所有相關程序。Docker 容器會使用`docker-init`可執行檔初始化為程序 PID 1，這有助於移除任何剩餘的殭屍程序。如需詳細資訊，請參閱 Docker 文件中的[指定初始化程序](https://docs.docker.com/engine/reference/run/#specify-an-init-process)。
如需對 AWS IoT Greengrass 在 Docker 容器中執行 的問題進行故障診斷的資訊，請參閱 [在 Docker AWS IoT Greengrass 容器中進行故障診斷](docker-troubleshooting.md)。