使用自訂 AWS TOE 元件的元件文件架構 - EC2 映像建置器
元件文件工作流程元件記錄輸入和輸出鏈結文件結構描述和定義文件範例結構描述

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

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

若要使用 AWS 任務協調器和執行器 （AWS TOE） 元件架構建置元件，您必須提供 YAML型文件，其代表適用於您建立之元件的階段和步驟。當元件建立新的 Amazon Machine Image （AMI） 或容器映像時 AWS 服務 ，請使用您的元件。

主題

元件文件工作流程

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

提示

使用 元件建置映像的服務可能會實作有關要用於建置程序的階段，以及允許執行這些階段的規則。在設計元件時，請務必考量這一點。

階段

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

當元件執行時，每個階段的關聯命令會按照元件文件中顯示的順序套用。

階段的規則

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

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

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

    • build – 對於 Image Builder，此階段通常用於建置階段 。

    • 驗證 – 對於 Image Builder，此階段通常用於建置階段 。

    • 測試 – 對於 Image Builder，此階段通常用於測試階段 。

  • 階段一律以文件中定義的順序執行。中 AWS CLI 為 AWS TOE 命令指定的順序沒有效果。

步驟

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

步驟的規則

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

  • 步驟必須使用傳回結束碼的支援動作 （動作模組）。

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

元件記錄

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

為了在映像建立過程中發生問題時協助疑難排解，在執行元件時 AWS TOE 建立的輸入文件和所有輸出檔案都會存放在日誌資料夾中。

日誌資料夾名稱包含下列部分：

  1. 日誌目錄 – 當服務執行 AWS TOE 元件時，它會在日誌目錄中傳遞，以及命令的其他設定。針對下列範例，我們會顯示 Image Builder 使用的日誌檔案格式。

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

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

  2. 檔案字首 – 這是所有元件的標準字首："TOE_"。

  3. 執行時間 – 這是 YYYY-MM-DD_HH-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 會將下列核心檔案儲存在日誌資料夾中：

輸入檔案

  • document.yaml – 用作命令輸入的文件。元件執行後，此檔案會儲存為成品。

輸出檔案

  • application.log – 應用程式日誌包含 AWS TOE 有關元件執行時所發生情況的時間戳記偵錯層級資訊。

  • detailedoutput.json – 此JSON檔案提供有關執行狀態、輸入、輸出和故障的詳細資訊，這些文件、階段和步驟會在元件執行時套用。

  • console.log – 主控台日誌包含在元件執行時 AWS TOE 寫入主控台的所有標準輸出 （停止） 和標準錯誤 （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:

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

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

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

是
階段 包含其步驟的階段清單。

清單

是

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

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

是

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

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

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

此外， 支援 -1 值，表示無限逾時。不允許 0 和其他負值。

 Integer

否

 7，200 秒 （120 分鐘）
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>amzn-s3-demo-source-bucket</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 }}'