本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用自訂 AWS TOE 元件的元件文件架構 若要使用 AWS 任務協調器和執行器 (AWS TOE) 元件架構建置元件，您必須提供 YAML 型文件，代表適用於您建立之元件的階段和步驟。當元件建立新的 Amazon Machine Image (AMI) 或容器映像時 AWS 服務 ，請使用您的元件。 **Topics** + [元件文件工作流程](#component-doc-workflow) + [元件記錄](#component-logging) + [輸入和輸出鏈結](#document-chaining) + [文件結構描述和定義](#document-schema) + [文件範例](#document-example) + [在自訂元件文件中使用變數](toe-user-defined-variables.md) + [在 中使用條件式建構 AWS TOE](toe-conditional-constructs.md) + [在 AWS TOE 元件文件中使用比較運算子](toe-comparison-operators.md) + [在 AWS TOE 元件文件中使用邏輯運算子](toe-logical-operators.md) + [在 中使用迴圈建構 AWS TOE](toe-looping-constructs.md) ## 元件文件工作流程 AWS TOE 元件文件使用階段和步驟來分組相關任務，並將這些任務組織到元件的邏輯工作流程中。 **提示** 使用 元件建置映像的服務可能會實作有關要用於其建置程序的階段，以及允許執行這些階段的規則。當您設計元件時，請務必考量這一點。 **階段** 階段代表工作流程在映像建置過程中的進展。例如，Image Builder 服務會在其產生的映像的*建置階段*使用 `build`和 `validate`階段。它在其*測試階段*使用 `test`和 `container-host-test`階段，以確保在建立最終 AMI 或分發容器映像之前，映像快照或容器映像會產生預期的結果。 當元件執行時，每個階段的相關聯命令會按照元件文件中顯示的順序套用。 **階段的規則** + 每個階段名稱在文件中必須是唯一的。 + 您可以在文件中定義多個階段。 + 您必須在文件中至少包含下列其中一個階段： + **build** – 對於映像建置器，此階段通常會在*建置階段*期間使用。 + **validate** – 對於映像建置器，此階段通常會在*建置階段*期間使用。 + **測試** – 對於映像建置器，此階段通常會在*測試階段*期間使用。 + 階段一律會按照文件中定義的順序執行。在 中 AWS CLI 為 AWS TOE 命令指定的順序沒有效果。 **步驟** 步驟是個別的工作單位，可定義每個階段內的工作流程。步驟會循序執行。不過，一個步驟的輸入或輸出也可以做為輸入饋送至後續步驟。這稱為「鏈結」。 **步驟的規則** + 步驟名稱對於 階段必須是唯一的。 + 步驟必須使用傳回結束代碼的支援動作 （動作模組）。 如需支援的動作模組的完整清單、運作方式、輸入/輸出值和範例，請參閱 [AWS TOE 元件管理員支援的動作模組](toe-action-modules.md)。 ## 元件記錄 AWS TOE 會在 EC2 執行個體上建立新的日誌資料夾，用於在每次元件執行時建置和測試新映像。對於容器映像，日誌資料夾會存放在容器中。 為了協助在映像建立過程中發生錯誤時進行故障診斷，在執行元件時 AWS TOE 建立的輸入文件和所有輸出檔案都會存放在日誌資料夾中。 日誌資料夾名稱包含下列部分： 1. **日誌目錄** – 當服務執行 AWS TOE 元件時，它會在日誌目錄中傳遞，以及命令的其他設定。針對下列範例，我們會顯示 Image Builder 使用的日誌檔案格式。 + **Linux 和 macOS**： `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **檔案字首** – 這是用於所有元件的標準字首："`TOE_`"。 1. **執行時間** – 這是 YYYY-MM-DD\_HH-MM-SS\_UTC-0 格式的時間戳記。 1. **執行 ID** – 這是 AWS TOE 執行一或多個元件時指派的 GUID。 範例：`{{/var/lib/amazon/toe/}}TOE_{{2021-07-01_12-34-56_UTC-0}}_{{a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4}}` AWS TOE 會將下列核心檔案存放在日誌資料夾中： **輸入檔案** + **document.yaml** – 用作命令輸入的文件。元件執行後，此檔案會儲存為成品。 **輸出檔案** + **application.log** – 應用程式日誌包含來自 的時間戳記偵錯層級資訊， AWS TOE 了解元件執行時的情況。 + **detailedoutput.json** – 此 JSON 檔案提供有關執行狀態、輸入、輸出和故障的詳細資訊，適用於元件執行時的所有文件、階段和步驟。 + **console.log** – 主控台日誌包含元件執行時 AWS TOE 寫入主控台的所有標準輸出 (stdout) 和標準錯誤 (stderr) 資訊。 + **chaining.json** – 此 JSON 檔案代表 AWS TOE 適用於解析鏈結表達式的最佳化。 **注意** 日誌資料夾也可能包含此處未涵蓋的其他暫存檔案。 ## 輸入和輸出鏈結 AWS TOE 組態管理應用程式以下列格式撰寫參考，提供鏈結輸入和輸出的功能： `{{ phase_name.step_name.inputs/outputs.variable }}` 或 `{{ phase_name.step_name.inputs/outputs[index].variable }}` 鏈結功能可讓您回收程式碼並改善文件的可維護性。 **鏈結規則** + 鏈結表達式只能在每個步驟的輸入區段中使用。 + 具有鏈結表達式的陳述式必須以引號括住。例如： + **無效的表達式**： `echo {{ phase.step.inputs.variable }}` + **有效表達式**： `"echo {{ phase.step.inputs.variable }}"` + **有效表達式**： `'echo {{ phase.step.inputs.variable }}'` + 鏈結表達式可以參考相同文件中其他步驟和階段的變數。不過，呼叫服務可能有規則，需要鏈結表達式才能僅在單一階段的內容中操作。例如，Image Builder 不支援從*建置階段*鏈結至*測試階段*，因為它會獨立執行每個階段。 + 鏈結表達式中的索引遵循以零為基礎的索引。索引以零 (0) 開頭，以參考第一個元素。 **範例** 若要參考下列範例步驟第二個項目中的來源變數，鏈結模式為 `{{ build.{{SampleS3Download}}.inputs[1].source }}`。 ``` phases: - name: 'build' steps: - name: {{SampleS3Download}} action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://{{sample-bucket}}/{{sample1}}.ps1' destination: 'C:\{{sample1}}.ps1' - source: 's3://{{sample-bucket}}/{{sample2}}.ps1' destination: 'C:\{{sample2}}.ps1' ``` 若要參考下列範例步驟的輸出變數 （等於 "Hello")，鏈結模式為 `{{ build.{{SamplePowerShellStep}}.outputs.stdout }}`。 ``` phases: - name: 'build' steps: - name: {{SamplePowerShellStep}} action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## 文件結構描述和定義 以下是文件的 YAML 結構描述。 ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` 文件的結構描述定義如下。 | 欄位 | 說明 | Type | 必要 | | --- | --- | --- | --- | | name | 文件的名稱。 | String | 否 | | description | 文件的描述。 | String | 否 | | schemaVersion | 文件的結構描述版本，目前為 1.0。 | String | 是 | | 階段 | 階段清單及其步驟。 | 清單 | 是 | 階段的結構描述定義如下所示。 | 欄位 | 說明 | Type | 必要 | | --- | --- | --- | --- | | name | 階段的名稱。 | String | 是 | | steps | 階段中的步驟清單。 | 清單 | 是 | 步驟的結構描述定義如下所示。 | 欄位 | 說明 | Type | 必要 | 預設值 | | --- | --- | --- | --- | --- | | name | 步驟的使用者定義名稱。 | String | | | | 動作 | 與執行 步驟之模組相關的關鍵字。 | String | | | | timeoutSeconds | 步驟在失敗或重試前執行的秒數。
此外， 支援 -1 值，表示無限逾時。不允許 0 和其他負值。 | Integer | 否 | 7，200 秒 (120 分鐘） | | onFailure | 指定步驟在失敗時應執行的動作。有效值如下：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/toe-use-documents.html) | String | 否 | 中止 | | maxAttempts | 在步驟失敗之前允許的嘗試次數上限。 | Integer | 否 | 1 | | inputs | 包含動作模組執行步驟所需的參數。 | 口述 | 是 | | ## 文件範例 下列範例顯示為目標作業系統執行任務的 AWSTOE 元件文件。 ------ #### [ Linux ] **範例 1：執行自訂二進位檔案** 以下是在 Linux 執行個體上下載並執行自訂二進位檔案的範例文件。 ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **範例 1：安裝 Windows 更新** 以下是安裝所有可用 Windows 更新、執行組態指令碼、在建立 AMI 之前驗證變更，以及在建立 AMI 之後測試變更的範例文件。 ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **範例 2：在 Windows 執行個體 AWS CLI 上安裝** 以下是使用 安裝檔案在 Windows 執行個體 AWS CLI 上安裝 的範例文件。 ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **範例 3： AWS CLI 使用 MSI 安裝程式安裝** 以下是 AWS CLI 使用 MSI 安裝程式安裝 的範例文件。 ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **範例 1：執行自訂 macOS 二進位檔案** 以下是在 macOS 執行個體上下載並執行自訂二進位檔案的範例文件。 ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------