使用自訂 AWS TOE 元件的元件文件架構 - EC2 Image Builder
元件文件工作流元件記錄輸入和輸出鏈接文件結構描述和定義文件範例結構

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用自訂 AWS TOE 元件的元件文件架構

若要使用 AWS 任務協調器和執行器 (AWS TOE) 組件架構建置組件，您必須提供代表適用於您建立之組件的階段和步驟的 YAML 文件。 AWS 服務 在建立新的 Amazon 機器映像 (AMI) 或容器映像時使用您的元件。

主題

元件文件工作流

AWS TOE 元件文件會使用階段和步驟將相關工作分組，並將這些任務組織成元件的邏輯工作流程。

提示

使用元件建置映像檔的服務可能會實作規則，說明要用於其建置程序的階段，以及允許執行這些階段的時間。設計元件時，這一點很重要。

階段

階段代表工作流程在映像建置程序中的進度。例如，Image Builder 服務會在其建置validate階段針對其產生的影像使用build和階段。它在測試container-host-test階段使用test和階段，以確保映像快照或容器映像在創建最終 AMI 或分發容器映像之前產生預期的結果。

當元件執行時，每個階段的關聯指令將按照它們在元件文件中的顯示順序來套用。

階段規則

  • 每個階段名稱在文件中都必須是唯一的。

  • 您可以在文件中定義許多階段。

  • 您必須至少在文件中包含下列其中一個階段：

    • build-對於 Image Builder，此階段通常在構建階段使用。

    • validate — 對於 Image Builder，此階段通常會在建置階段使用。

    • test — 對於 Image Builder，此階段通常在測試階段使用。

  • 階段總是按照它們在文檔中定義的順序運行。針對中的指 AWS TOE 令指定它們的順序不 AWS CLI 起作用。

步驟

步驟是定義每個階段中工作流程的個別工作單位。步驟會循序執行。但是，一個步驟的輸入或輸出也可以進入後續步驟作為輸入。這就是所謂的「鏈接」。

步驟規則

  • 階段的步驟名稱必須是唯一的。

  • 步驟必須使用支援的動作 (動作模組) 來傳回結束代碼。

    如需支援的動作模組、其運作方式、輸入/輸出值和範例的完整清單，請參閱AWS TOE 元件管理員支援的動作模組。

元件記錄

AWS TOE 每次執行元件時，都會在 EC2 執行個體上建立新的記錄檔資料夾，用於建置和測試新映像。對於容器映像檔，記錄檔資料夾會儲存在容器中。

若要在影像建立過程中發生問題時協助進行疑難排解，輸入文件和所有在執行元件時 AWS TOE 建立的輸出檔案都會儲存在記錄檔資料夾中。

記錄檔資料夾名稱由下列部分組成：

  1. 記錄目錄 — 當服務執行 AWS TOE 元件時，它會傳入 log 目錄，以及指令的其他設定。在下列範例中，我們展示了 Image Builder 使用的記錄檔格式。

    • Linux: /var/lib/amazon/toe/

    • Windows: $env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\

  2. 文件前綴-這是用於所有組件的標準前綴："TOE_」。

  3. 執行時間 — 此時間戳記格式為 YYYY-MM-MM-MM-SS_UTC-0 格式的時間戳記。

  4. 執行 ID — 這是執行一或多個元件 AWS TOE 時指派的 GUID。

範例：/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4

AWS TOE 將下列核心檔案儲存在記錄檔資料夾中：

輸入文件

  • 文件 .yaml — 用來做為指令輸入的文件。元件執行後，此檔案會儲存為人工因素。

輸出檔案

  • application.log — 應用程式記錄檔包含時間戳記的偵錯層級資訊，來自 AWS TOE 元件執行時發生的情況。

  • detailedoutput.json — 此 JSON 檔案包含有關執行狀態、輸入、輸出和失敗的詳細資訊，適用於元件執行時適用的所有文件、階段和步驟。

  • console.log — 主控台記錄檔包含元件執行時 AWS TOE 寫入主控台的所有標準輸出 (stdout) 和標準錯誤 (stderr) 資訊。

  • 鏈接 .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）開始引用第一個元素。

範例

若要參照下列範例步驟第二個項目中的 source 變數，鏈結模式為{{ 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:

文件的結構描述定義如下。

欄位 Description (描述) Type 必要
name 文件的名稱。 字串 否
description 文件的描述。 字串

否
schemaVersion 文件的結構描述版本，目前為 1.0。 字串

是
階段 階段及其步驟的列表。

清單

是

階段的結構描述定義如下。

欄位 Description (描述) Type 必要
name 階段的名稱。 字串 是
steps 階段中的步驟清單。 清單

是

步驟的結構描述定義如下。

欄位 Description (描述) Type 必要 預設值
name 步驟的使用者定義名稱。 字串
動作 與執行步驟之模組相關的關鍵字。 字串
timeoutSeconds

失敗或重試之前，步驟執行的秒數。

此外，支持 -1 值，這表示無限超時。0 和其他負值是不允許的。

 Integer

否

 七百二十秒 (一百二十分鐘)
onFailure

指定步驟在失敗時應執行的動作。有效值如下：

  • 中止 — 嘗試次數上限後的步驟失敗，並停止執行。將階段與文件的狀態設定為Failed。

  • 繼續 — 在嘗試次數上限之後失敗步驟，並繼續執行剩餘步驟。將階段與文件的狀態設定為Failed。

  • 略過 — 將步驟設定為超過失敗嘗試次數上限IgnoredFailure之後的步驟，並繼續執行剩餘步驟。將階段與文件的狀態設定為SuccessWithIgnoredFailure。

字串

否

 中止
maxAttempts 在步驟失敗之前允許的嘗試次數上限。 Integer

否

 1
inputs 包含動作模組執行步驟所需的參數。 字典

是

文件範例結構

以下是範例文件結構描述，用於安裝所有可用的 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}}'

以下是下載並執行自訂 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://<replaceable>mybucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - 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 執行個體 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 }}'

以下是 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 }}'