本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 手動設定以使用 開發自訂元件 AWS TOE
AWS 任務協調器和執行器 (AWS TOE) 應用程式是一種獨立的應用程式，可在元件定義架構中建立、驗證和執行命令。 AWS 服務可以使用 AWS TOE 來協調工作流程、安裝軟體、修改系統組態和測試映像組建。
請依照下列步驟手動安裝 AWS TOE 應用程式，並將其用作獨立應用程式來開發自訂元件。如果您使用 Image Builder 主控台或 AWS CLI 命令來建立自訂元件，Image Builder 會為您處理這些步驟。如需詳細資訊，請參閱[使用映像建置器建立自訂元件](create-component.md)。
**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
```