本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 手動設定以使用 開發自訂元件 AWS TOE
AWS 任務協調器和執行器 (AWS TOE) 應用程式是一種獨立的應用程式，可在元件定義架構中建立、驗證和執行命令。 AWS 服務可以使用 AWS TOE 來協調工作流程、安裝軟體、修改系統組態和測試映像組建。
請依照下列步驟手動安裝 AWS TOE 應用程式，並將其用作獨立應用程式來開發自訂元件。如果您使用 Image Builder 主控台或 AWS CLI 命令來建立自訂元件，Image Builder 會為您處理這些步驟。如需詳細資訊，請參閱[使用映像建置器建立自訂元件](create-component.md)。
# 驗證 AWS TOE 安裝下載的簽章
本節說明在 Linux、macOS 和 Windows 作業系統 AWS TOE 上驗證 的安裝下載有效性的建議程序。
**Topics**
+ [驗證 Linux 或 macOS 上 AWS TOE 安裝下載的簽章](#awstoe-verify-sig-linux)
+ [驗證 Windows 上 AWS TOE 安裝下載的簽章](#awstoe-verify-sig-win)
## 驗證 Linux 或 macOS 上 AWS TOE 安裝下載的簽章
本主題說明在 Linux 作業系統或 macOS 作業系統 AWS TOE 上驗證安裝下載有效性的建議程序。
每當您從網際網路下載應用程式時，我們建議您驗證軟體發佈者的身分。此外，請檢查應用程式自發佈以來是否遭到更改或損毀。如此可保護您，避免安裝到包含病毒或其他惡意程式碼的應用程式版本。
如果在執行本主題中的步驟後，您判斷 AWS TOE 應用程式的軟體已更改或損毀，請勿執行安裝檔案。反之，請聯絡 支援 如需支援選項的詳細資訊，請參閱 [支援](https://aws.amazon.com/premiumsupport/)。
AWS TOE Linux 型和 macOS 作業系統的檔案使用 進行簽署`GnuPG`，這是 Pretty Good Privacy (OpenPGP) 標準用於安全數位簽章的開放原始碼實作。 `GnuPG`（也稱為 `GPG`) 透過數位簽章提供身分驗證和完整性檢查。Amazon EC2 會發佈公有金鑰和簽章，您可以用來驗證下載的 Amazon EC2 CLI 工具。如需 `PGP` 和 `GnuPG` (`GPG`) 的詳細資訊，請參閱 [http://www.gnupg.org](https://www.gnupg.org/)。
第一步是與軟體發佈者建立信任。下載軟體發佈者的公開金鑰，檢查公開金鑰的擁有者是否為聲稱的擁有者，然後將公開金鑰新增至您的 *keyring*。您的 keyring 是一組已知的公開金鑰。在您建立公開金鑰的真實性之後，即可用它來驗證應用程式的簽章。
**Topics**
+ [安裝 GPG 工具](#awstoe-verify-signature-of-binary-download-install-tools)
+ [驗證和匯入公開金鑰](#awstoe-verify-signature-of-binary-download-authenticate-import-public-key)
+ [驗證套件的簽章](#awstoe-verify-signature-of-binary-package)
### 安裝 GPG 工具
如果您的作業系統是 Linux、Unix 或 macOS，則可能已安裝 GPG 工具。若要測試工具是否已安裝在您的系統，請在命令提示字元中輸入 **gpg**。如果 GPG 工具已安裝，您會看到 GPG 命令提示字元。如果未安裝 GPG 工具，您會看到錯誤訊息，指出找不到命令。您可以從儲存庫安裝 GnuPG 套件。
若要安裝 GPG 工具，請選取符合您執行個體的作業系統。
------
#### [ Debian-based Linux ]
從終端機執行下列命令：
```
apt-get install gnupg
```
------
#### [ Red Hat–based Linux ]
從終端機執行下列命令：
```
yum install gnupg
```
------
#### [ macOS ]
從終端機執行下列命令：
```
brew install gnupg
```
------
### 驗證和匯入公開金鑰
程序的下一個步驟是驗證 AWS TOE 公有金鑰，並將其新增為 `GPG` keyring 中的信任金鑰。
**驗證和匯入 AWS TOE 公有金鑰**
1. 執行以下其中一項以取得我們的公有 `GPG` 建置金鑰的副本：
+ 從 下載金鑰
https：//awstoe-****.s3.****.amazonaws.com/assets/awstoe.gpg。例如 [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg)。
+ 從以下文字複製金鑰，然後貼到名為 `awstoe.gpg` 的檔案中。務必包含以下所有項目：
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2
mQENBF8UqwsBCACdiRF2bkZYaFSDPFC+LIkWLwFvtUCRwAHtD8KIwTJ6LVn3fHAU
GhuK0ZH9mRrqRT2bq/xJjGsnF9VqTj2AJqndGJdDjz75YCZYM+ocZ+r5HSJaeW9i
S5dykHj7Txti2zHe0G5+W0v7v5bPi2sPHsN7XWQ7+G2AMEPTz8PjxY//I0DvMQns
Sle3l9hz6wCClz1l9LbBzTyHfSm5ucTXvNe88XX5Gmt37OCDM7vfli0Ctv8WFoLN
6jbxuA/sV71yIkPm9IYp3+GvaKeT870+sn8/JOOKE/U4sJV1ppbqmuUzDfhrZUaw
8eW8IN9A1FTIuWiZED/5L83UZuQs1S7s2PjlABEBAAG0GkFXU1RPRSA8YXdzdG9l
QGFtYXpvbi5jb20+iQE5BBMBCAAjBQJfFKsLAhsDBwsJCAcDAgEGFQgCCQoLBBYC
AwECHgECF4AACgkQ3r3BVvWuvFJGiwf9EVmrBR77+Qe/DUeXZJYoaFr7If/fVDZl
6V3TC6p0J0Veme7uXleRUTFOjzbh+7e5sDX19HrnPquzCnzfMiqbp4lSoeUuNdOf
FcpuTCQH+M+sIEIgPno4PLl0Uj2uE1o++mxmonBl/Krk+hly8hB2L/9n/vW3L7BN
OMb1Ll9PmgGPbWipcT8KRdz4SUex9TXGYzjlWb3jU3uXetdaQY1M3kVKE1siRsRN
YYDtpcjmwbhjpu4xm19aFqNoAHCDctEsXJA/mkU3erwIRocPyjAZE2dnlkL9ZkFZ
z9DQkcIarbCnybDM5lemBbdhXJ6hezJE/b17VA0t1fY04MoEkn6oJg==
=oyze
-----END PGP PUBLIC KEY BLOCK-----
```
1. 在您儲存 **awstoe.gpg** 的目錄中的命令提示字元中，使用下列命令將 AWS TOE 公有金鑰匯入 keyring。
```
gpg --import awstoe.gpg
```
此命令會傳回類似以下的結果：
```
gpg: key F5AEBC52: public key "AWSTOE " imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
```
請記下金鑰值，在後續步驟您將會用到它。在前面的範例中，金鑰值為 `F5AEBC52`。
1. 執行以下命令以驗證指紋，請以三個步驟的值取代 *key-value*：
```
gpg --fingerprint key-value
```
此命令會傳回類似以下的結果：
```
pub 2048R/F5AEBC52 2020-07-19
Key fingerprint = F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52
uid [ unknown] AWSTOE
```
此外，如以上範例所示，指紋字串應該與 `F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52` 完全相同。比較傳回的金鑰指紋與此頁面發佈的金鑰指紋。它們應該相符。如果不相符，請勿安裝 AWS TOE 安裝指令碼並聯絡 支援。
### 驗證套件的簽章
在您安裝 `GPG` 工具、驗證及匯入 AWS TOE 公有金鑰，以及驗證公有金鑰可信任之後，您就可以驗證安裝指令碼的簽章。
**驗證 安裝指令碼簽章**
1. 在命令提示字元中，執行下列命令來下載應用程式二進位檔：
```
curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe
```
例如：
```
curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe
```
支援的值**architecture**可以是 `amd64`、 `386`和 `arm64`。
1. 在命令提示字元中，執行下列命令，從相同的 S3 金鑰字首路徑下載對應應用程式二進位檔的簽章檔案：
```
curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe.sig
```
例如：
```
curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe.sig
```
支援的值**architecture**可以是 `amd64`、 `386`和 `arm64`。
1. 在儲存和 AWS TOE 安裝檔案的目錄中的命令提示字元中執行下列命令`awstoe.sig`來驗證簽章。兩個檔案都必須存在。
```
gpg --verify ./awstoe.sig ~/awstoe
```
輸出應類似以下所示：
```
gpg: Signature made Mon 20 Jul 2020 08:54:55 AM IST using RSA key ID F5AEBC52
gpg: Good signature from "AWSTOE awstoe@amazon.com" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52
```
如果輸出包含 `Good signature from "AWSTOE "` 片語，表示簽章已成功驗證，您可以繼續執行 AWS TOE 安裝指令碼。
如果輸出包含 `BAD signature` 片語，請檢查您是否已正確執行程序。如果您繼續取得此回應，請勿執行先前下載的安裝檔案，並聯絡 支援。
以下是您可能會看到的警告的詳細資訊：
+ **警告：此金鑰未通過信任簽章的認證！沒有指示簽章屬於擁有者。**理想情況下，您會前往 AWS 辦公室並親自收到金鑰。不過，您很可能會從網站下載。在這種情況下，網站是 AWS 網站。
+ **gpg：沒有發現最終信任的金鑰。**這表示您或您信任的其他人不會「最終信任」特定金鑰。
如需詳細資訊，請參閱 [http://www.gnupg.org](http://www.gnupg.org)。
## 驗證 Windows 上 AWS TOE 安裝下載的簽章
本主題說明在 Windows 作業系統上驗證 AWS 任務協調器和執行器 應用程式安裝檔案有效性的建議程序。
當您從網際網路下載應用程式時，建議您驗證軟體發佈者的身分，並檢查應用程式在發佈之後未遭更改或損毀。如此可保護您，避免安裝到包含病毒或其他惡意程式碼的應用程式版本。
如果在執行本主題中的步驟後，您判斷 AWS TOE 應用程式的軟體已更改或損毀，請勿執行安裝檔案。反之，請聯絡 支援。
若要在 Windows 作業系統上驗證下載的 awstoe 二進位檔的有效性，請確定其 Amazon Services LLC 簽署者憑證的指紋等於此值：
**9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15**
**注意**
在新二進位檔的推展時段期間，您的簽署者憑證可能與新的指紋不相符。如果您的簽署者憑證不相符，請確認指紋值為：
**BA 81 25 EE AC 64 2E A9 F3 C5 93 CA 6D 3E B7 93 7D 68 75 74**
若要驗證這個值，請執行以下程序：
1. 在下載的 `awstoe.exe` 上按一下滑鼠右鍵，然後開啟 **Properties (屬性)** 視窗。
1. 選擇 **數位簽章** 索引標籤。
1. 從 **Signature List (簽章清單)** 中選擇 **Amazon Services LLC**，然後選擇 **Details (詳細資訊)**。
1. 選擇 **General (一般)** 索引標籤 (如果尚未選取)，然後選擇 **View Certificate (檢視憑證)**。
1. 選擇**詳細資訊**索引標籤，如果尚未選取，請在**顯示**下拉式清單中選擇**全部**。
1. 向下捲動到看見 **Thumbprint (指紋)** 欄位為止，然後選擇 **Thumbprint (指紋)**。這會在下方的視窗中顯示整個指紋值。
+ 如果下方視窗中的指紋值與以下值完全相同：
**9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15**
然後，您下載 AWS TOE 的二進位檔是真實的，可以安全地安裝。
+ 如果較低詳細資訊視窗中的指紋值與先前的值不同，請勿執行 `awstoe.exe`。
**Topics**
+ [驗證 AWS TOE 安裝下載的簽章](awstoe-verify-sig.md)
+ [步驟 1：安裝 AWS TOE](#toe-start-install)
+ [步驟 2：設定 AWS 登入資料](#toe-start-credentials)
+ [步驟 3：在本機開發元件文件](#toe-start-develop)
+ [步驟 4：驗證 AWS TOE 元件](#toe-start-validate)
+ [步驟 5：執行 AWS TOE 元件](#toe-start-run)
## 步驟 1：安裝 AWS TOE
若要在本機開發元件，請下載並安裝 AWS TOE 應用程式。
1.
**下載 AWS TOE 應用程式**
若要安裝 AWS TOE，請為您的架構和平台選擇適當的下載連結。如需應用程式下載連結的完整清單，請參閱 [AWS TOE 下載](toe-component-manager.md#toe-downloads)
**重要**
AWS 正在暫停對 TLS 1.0 和 1.1 版的支援。若要存取 S3 儲存貯體進行 AWS TOE 下載，您的用戶端軟體必須使用 TLS 1.2 版或更新版本。如需詳細資訊，請參閱此[AWS 安全部落格文章](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)。
1.
**驗證簽章**
驗證下載的步驟取決於您在安裝後執行 AWS TOE 應用程式的伺服器平台。若要在 Linux 伺服器上驗證您的下載，請參閱 [驗證 Linux 或 macOS 上的簽章](awstoe-verify-sig.md#awstoe-verify-sig-linux)。若要在 Windows 伺服器上驗證您的下載，請參閱 [驗證 Windows 上的簽章](awstoe-verify-sig.md#awstoe-verify-sig-win)。
**注意**
AWS TOE 直接從其下載位置叫用。不需要單獨的安裝步驟。這也表示 AWS TOE 可以變更本機環境。
為了確保您在元件開發期間隔離變更，我們建議您使用 EC2 執行個體來開發和測試 AWS TOE 元件。
## 步驟 2：設定 AWS 登入資料
AWS TOE 執行任務時， 需要 AWS 登入資料才能連線到其他 AWS 服務，例如 Amazon S3 和 Amazon CloudWatch，例如：
+ 從使用者提供的 Amazon S3 路徑下載 AWS TOE 文件。
+ 執行 `S3Download`或 `S3Upload` 動作模組。
+ 啟用時，將日誌串流至 CloudWatch。
如果您在 EC2 執行個體 AWS TOE 上執行 ，則執行 AWS TOE 會使用與連接到 EC2 執行個體的 IAM 角色相同的許可。
如需 EC2 IAM 角色的詳細資訊，請參閱 [Amazon EC2 的 IAM 角色](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)。
下列範例示範如何使用 `AWS_ACCESS_KEY_ID`和 `AWS_SECRET_ACCESS_KEY`環境變數設定 AWS 登入資料。
若要在 Linux、macOS 或 Unix 上設定這些變數，請使用 `export`。
```
export AWS_ACCESS_KEY_ID=your_access_key_id
```
```
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
若要使用 PowerShell 在 Windows 上設定這些變數，請使用 `$env`。
```
$env:AWS_ACCESS_KEY_ID=your_access_key_id
```
```
$env:AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
若要使用命令提示字元在 Windows 上設定這些變數，請使用 `set`。
```
set AWS_ACCESS_KEY_ID=your_access_key_id
```
```
set AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
## 步驟 3：在本機開發元件文件
元件是以純文字 YAML 文件撰寫。如需文件語法的詳細資訊，請參閱 [使用自訂 AWS TOE 元件的元件文件架構](toe-use-documents.md)。
以下是 *Hello World* 元件文件範例，可協助您開始使用。
------
#### [ Linux ]
本指南中的一些 Linux 元件範例參考名為 的元件文件檔案`hello-world-linux.yml`。您可以使用下列文件來開始使用這些範例。
```
name: Hello World
description: This is hello world testing document for Linux.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the test phase.'
```
------
#### [ Windows ]
本指南中的一些 Windows 元件範例參考名為 的元件文件檔案`hello-world-windows.yml`。您可以使用下列文件來開始使用這些範例。
```
name: Hello World
description: This is Hello World testing document for Windows.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the test phase.'
```
------
#### [ macOS ]
本指南中的一些 macOS 元件範例參考名為 的元件文件檔案`hello-world-macos.yml`。您可以使用下列文件來開始使用這些範例。
```
name: Hello World
description: This is hello world testing document for macOS.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the test phase.'
```
------
## 步驟 4：驗證 AWS TOE 元件
您可以使用應用程式在本機 AWS TOE 驗證 AWS TOE 元件的語法。下列範例顯示 AWS TOE 應用程式`validate`命令，在不執行元件的情況下驗證元件的語法。
**注意**
AWS TOE 應用程式只能驗證目前作業系統的元件語法。例如，在 Windows `awstoe.exe` 上執行 時，您無法驗證使用 `ExecuteBash`動作模組的 Linux 文件語法。
Linux 或 macOS
```
awstoe validate --documents /home/user/hello-world.yml
```
Windows
```
awstoe.exe validate --documents C:\Users\user\Documents\hello-world.yml
```
## 步驟 5：執行 AWS TOE 元件
AWS TOE 應用程式可以使用`--phases`命令列引數執行指定文件的一或多個階段。支援的值`--phases`為 `build`、 `validate`和 `test`。多個階段值可以輸入為逗號分隔值。
當您提供階段清單時， AWS TOE 應用程式會依序執行每個文件的指定階段。例如， AWS TOE 執行 的 `build`和 `validate`階段`document1.yaml`，後面接著 的 `build`和 `validate`階段`document2.yaml`。
為了確保日誌安全儲存並保留以進行故障診斷，建議您在 Amazon S3 中設定日誌儲存。在映像建置器中，用於發佈日誌的 Amazon S3 位置是在基礎設施組態中指定。如需基礎設施組態的詳細資訊，請參閱 [管理映像建置器基礎設施組態](manage-infra-config.md)
如果未提供階段清單， AWS TOE 應用程式會依 YAML 文件所列的順序執行所有階段。
若要在單一或多個文件中執行特定階段，請使用下列命令。
單一階段
```
awstoe run --documents hello-world.yml --phases build
```
多個階段
```
awstoe run --documents hello-world.yml --phases build,test
```
**文件執行**
在單一文件中執行所有階段
```
awstoe run --documents documentName.yaml
```
在多個文件中執行所有階段
```
awstoe run --documents documentName1.yaml,documentName2.yaml
```
輸入 Amazon S3 資訊以從使用者定義的本機路徑上傳 AWS TOE 日誌 （建議）
```
awstoe run --documents documentName.yaml --log-s3-bucket-name amzn-s3-demo-destination-bucket --log-s3-key-prefix S3KeyPrefix --log-s3-bucket-owner S3BucketOwner --log-directory local_path
```
在單一文件中執行所有階段，並在主控台上顯示所有日誌
```
awstoe run --documents documentName.yaml --trace
```
範例 命令
```
awstoe run --documents s3://bucket/key/doc.yaml --phases build,validate
```
執行具有唯一 ID 的文件
```
awstoe run --documents documentName.yaml --execution-id user-provided-id --phases build,test
```
取得 的協助 AWS TOE
```
awstoe --help
```