本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 為您的映像建置器映像開發自訂元件 您可以建立自己的元件，根據您確切的規格自訂映像建置器映像。使用下列步驟為您的映像建置器映像或容器配方開發自訂元件。 1. 如果您想要開發元件文件並在本機進行驗證，您可以安裝 AWS 任務協調器和執行器 (AWS TOE) 應用程式，並在本機電腦上進行設定。如需詳細資訊，請參閱[手動設定以使用 開發自訂元件 AWS TOE](toe-get-started.md)。 1. 建立使用元件文件架構的 AWS TOE 元件文件。如需文件架構的詳細資訊，請參閱 [使用自訂 AWS TOE 元件的元件文件架構](toe-use-documents.md)。 1. 當您建立自訂元件時，請指定您的元件文件。如需詳細資訊，請參閱[使用映像建置器建立自訂元件](create-component.md)。 **Topics** + [在映像建置器中為自訂元件建立 YAML 元件文件](create-component-yaml.md) + [使用映像建置器建立自訂元件](create-component.md) # 在映像建置器中為自訂元件建立 YAML 元件文件 若要建置元件，您必須提供 YAML 或 JSON 應用程式元件文件。文件包含您在為映像提供自訂所定義的階段和步驟期間執行的程式碼。 本節中的一些範例會建立建置元件，在 AWS TOE 元件管理應用程式中呼叫 `UpdateOS`動作模組。模組會更新作業系統。如需 `UpdateOS`動作模組的詳細資訊，請參閱 [UpdateOS](toe-action-modules.md#action-modules-updateos)。 macOS 作業系統範例使用 `ExecuteBash`動作模組來安裝和驗證`wget`公用程式。`UpdateOS` 動作模組不支援 macOS。如需 `ExecuteBash`動作模組的詳細資訊，請參閱 [ExecuteBash](toe-action-modules.md#action-modules-executebash)。如需應用程式元件文件之階段、步驟和語法 AWS TOE 的詳細資訊，請參閱[使用 文件 AWS TOE](https://docs.aws.amazon.com/imagebuilder/latest/userguide/toe-use-documents.html)。 **注意** Image Builder 會從元件文件中定義的階段決定元件類型，如下所示： **組建** – 這是預設元件類型。任何未分類為測試元件的項目，都是建置元件。這種類型的元件會在映像*建置階段*期間執行。如果此建置元件已定義`test`階段，則該階段會在*測試階段*期間執行。 **測試** – 若要符合測試元件的資格，元件文件只能包含一個名為 的階段`test`。對於與建置元件組態相關的測試，我們建議您不要使用獨立測試元件。反之，請在相關聯的建置元件中使用 `test`階段。 如需 Image Builder 如何在其建置程序中使用階段和階段來管理元件工作流程的詳細資訊，請參閱 [使用元件來自訂映像建置器映像](manage-components.md)。 若要為範例應用程式建立 YAML 應用程式元件文件，請遵循與映像作業系統相符標籤上的步驟。 ------ #### [ Linux ] **建立 YAML 元件檔案** 使用檔案編輯工具來建立元件文件。文件範例使用名為 的檔案`update-linux-os.yaml`，其中包含下列內容： ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-linux-os description: Updates Linux with the latest security updates. schemaVersion: 1 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **提示** 使用此線上 [YAML 驗證器](https://jsonformatter.org/yaml-validator)等工具，或在您的程式碼環境中使用 YAML lint 延伸模組，以確認您的 YAML 格式正確。 ------ #### [ Windows ] **建立 YAML 元件檔案** 使用檔案編輯工具來建立元件文件。文件範例使用名為 的檔案`update-windows-os.yaml`，其中包含下列內容： ``` # Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: MIT-0 # # Permission is hereby granted, free of charge, to any person obtaining a copy of this # software and associated documentation files (the "Software"), to deal in the Software # without restriction, including without limitation the rights to use, copy, modify, # merge, publish, distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A # PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT # HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. name: update-windows-os description: Updates Windows with the latest security updates. schemaVersion: 1.0 phases: - name: build steps: - name: UpdateOS action: UpdateOS # Document End ``` **提示** 使用此線上 [YAML 驗證器](https://jsonformatter.org/yaml-validator)之類的工具，或在您的程式碼環境中使用 YAML lint 延伸，以驗證您的 YAML 格式正確。 ------ #### [ macOS ] **建立 YAML 元件檔案** 使用檔案編輯工具來建立元件文件。文件範例使用名為 的檔案`wget-macos.yaml`，其中包含下列內容： ``` name: WgetInstallDocument description: This is wget installation document. schemaVersion: 1.0 phases: - name: build steps: - name: WgetBuildStep action: ExecuteBash inputs: commands: - | PATH=/usr/local/bin:$PATH sudo -u ec2-user brew install wget - name: validate steps: - name: WgetValidateStep action: ExecuteBash inputs: commands: - | function error_exit { echo $1 echo "{\"failureMessage\":\"$2\"}" exit 1 } type wget if [ $? -ne 0 ]; then error_exit "$stderr" "Wget installation failed!" fi - name: test steps: - name: WgetTestStep action: ExecuteBash inputs: commands: - wget -h ``` **提示** 使用此線上 [YAML 驗證器](https://jsonformatter.org/yaml-validator)之類的工具，或在您的程式碼環境中使用 YAML lint 延伸模組來驗證您的 YAML 格式是否正確。 ------ # 使用映像建置器建立自訂元件 完成元件文件後，您可以使用它來建立映像建置器配方可以使用的自訂元件。您可以從 Image Builder 主控台、API 或 SDKs，或從命令列建立自訂元件。如需如何使用輸入參數建立自訂元件並在配方中使用它的詳細資訊，請參閱 [教學課程：使用輸入參數建立自訂元件](tutorial-component-parameters.md)。 下列各節說明如何從 主控台或 建立元件 AWS CLI。 **Topics** + [從主控台建立自訂元件](#create-component-ib-console) + [從 建立自訂元件 AWS CLI](#create-component-ib-cli) + [匯入指令碼以從 建立元件 AWS CLI](#import-component-cli) + [自動建置版本管理](#auto-build-version-management) + [使用版本參考](#using-version-references) ## 從主控台建立自訂元件 若要從 Image Builder 主控台建立 AWS TOE 應用程式元件，請遵循下列步驟： 1. 開啟 EC2 Image Builder 主控台，位於 [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)。 1. 從導覽窗格中選取**元件**。然後選取**建立元件**。 1. 在**建立元件**頁面的**元件詳細資訊**下，輸入下列項目： 1. **映像作業系統 (OS)**。指定元件相容的作業系統。 1. **元件類別**。從下拉式清單中選取您要建立的建置或測試元件類型。 1. **元件名稱**。輸入元件的名稱。 1. **元件版本**。輸入元件的版本編號。 1. **描述**。提供選用的描述，協助您識別元件。 1. **變更描述**。提供選用的描述，協助您了解對此版本元件所做的變更。 1. 在**定義文件**區段中，預設選項為**定義文件內容**。元件文件定義映像建置器在建置和測試執行個體上執行的動作，以建立映像。 在**內容**方塊中，輸入您的 YAML 元件文件內容。若要從 Linux 的 *Hello World* 範例開始，請選擇**使用範例**選項。若要進一步了解如何建立 YAML 元件文件，或從該頁面複製並貼上 *UpdateOS* 範例，請參閱 [在映像建置器中為自訂元件建立 YAML 元件文件](create-component-yaml.md)。 1. 輸入元件詳細資訊後，請選取**建立元件**。 **注意** 若要在建立或更新配方時查看您的新元件，請將**我擁有的**篩選條件套用至建置或測試元件清單。篩選條件位於元件清單頂端的搜尋方塊旁。 1. 若要刪除元件，請從**元件**頁面中選取您要刪除之元件旁的核取方塊。從**動作**下拉式清單中，選取**刪除元件**。 **更新元件** 若要建立新的元件版本，請遵循下列步驟： 1. 視您開始的位置而定： + 從**元件**清單頁面 – 選取元件名稱旁的核取方塊，然後從**動作**功能表中選取**建立新版本**。 + 從元件詳細資訊頁面 – 選擇標題右上角的**建立新版本**按鈕。 1. 顯示**建立元件**頁面時，元件資訊已填入目前的值。遵循建立元件步驟來更新元件。這可確保您在**元件版本中輸入唯一的語意版本**。若要進一步了解映像建置器資源的語意版本控制，請參閱[Image Builder 中的語意版本控制](ibhow-semantic-versioning.md)。 ## 從 建立自訂元件 AWS CLI 在本節中，您將了解如何在 中設定和使用 Image Builder 命令 AWS CLI 來建立 AWS TOE 應用程式元件，如下所示。 + 將您的 YAML 元件文件上傳至您可以從命令列參考的 S3 儲存貯體。 + 使用 **create-component**命令建立 AWS TOE 應用程式元件。 + 使用 **list-components**命令和名稱篩選條件列出元件版本，以查看哪些版本已存在。您可以使用輸出來判斷下一個版本應該是什麼以進行更新。 若要從輸入 YAML 文件建立 AWS TOE 應用程式元件，請遵循符合您映像作業系統平台的步驟。 ------ #### [ Linux ] **將您的應用程式元件文件存放在 Amazon S3 中** 您可以使用 S3 儲存貯體做為 AWS TOE 應用程式元件來源文件的儲存庫。若要存放元件文件，請遵循下列步驟： + **將文件上傳至 Amazon S3** *如果您的文件小於 64 KB，您可以略過此步驟。*大小為 64 KB 或更大的文件必須存放在 Amazon S3 中。 ``` aws s3 cp update-linux-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml ``` **從 YAML 文件建立元件** 若要簡化您在 中使用的**create-component**命令 AWS CLI，請建立 JSON 檔案，其中包含您要傳入命令的所有元件參數。包含您先前建立`update-linux-os.yaml`的文件位置。`uri` 鍵/值對包含檔案參考。 **注意** JSON 檔案中資料值的命名慣例遵循為映像建置器 API 操作請求參數指定的模式。若要檢閱 API 命令請求參數，請參閱 *EC2 Image Builder API 參考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。 若要提供資料值做為命令列參數，請參閱 *AWS CLI 命令參考*中指定的參數名稱。 1. **建立 CLI 輸入 JSON 文件** 使用檔案編輯工具來建立名為 的檔案`create-update-linux-os-component.json`。包含下列內容： ``` { "name": "update-linux-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Linux operating system", "changeDescription": "Initial version.", "platform": "Linux", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "security-updates" } } ``` 1. **建立元件** 使用下列命令來建立元件，並參考您在上一個步驟中建立的 JSON 檔案名稱： ``` aws imagebuilder create-component --cli-input-json file://create-update-linux-os-component.json ``` **注意** 您必須在 JSON 檔案路徑的開頭包括 `file://` 標記。 JSON 檔案的路徑應遵循執行命令之基礎作業系統的適當慣例。例如，Windows 使用反斜線 (\$1) 來參考目錄路徑，而 Linux 和 macOS 則使用正斜線 (/)。 ------ #### [ Windows ] **將您的應用程式元件文件存放在 Amazon S3 中** 您可以使用 S3 儲存貯體做為 AWS TOE 應用程式元件來源文件的儲存庫。若要存放元件文件，請遵循下列步驟： + **將文件上傳至 Amazon S3** *如果您的文件小於 64 KB，您可以略過此步驟。*大小為 64 KB 或更大的文件必須存放在 Amazon S3 中。 ``` aws s3 cp update-windows-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml ``` **從 YAML 文件建立元件** 若要簡化您在 中使用的**create-component**命令 AWS CLI，請建立 JSON 檔案，其中包含您要傳入命令的所有元件參數。包含您先前建立`update-windows-os.yaml`的文件位置。`uri` 鍵/值對包含檔案參考。 **注意** JSON 檔案中資料值的命名慣例遵循為映像建置器 API 操作請求參數指定的模式。若要檢閱 API 命令請求參數，請參閱 *EC2 Image Builder API 參考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。 若要提供資料值做為命令列參數，請參閱 *AWS CLI 命令參考*中指定的參數名稱。 1. **建立 CLI 輸入 JSON 文件** 使用檔案編輯工具來建立名為 的檔案`create-update-windows-os-component.json`。包含下列內容： ``` { "name": "update-windows-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Windows operating system.", "changeDescription": "Initial version.", "platform": "Windows", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "security-updates" } } ``` **注意** 您必須在 JSON 檔案路徑的開頭包括 `file://` 標記。 JSON 檔案的路徑應遵循執行命令之基礎作業系統的適當慣例。例如，Windows 使用反斜線 (\$1) 來參考目錄路徑，而 Linux 和 macOS 則使用正斜線 (/)。 1. **建立元件** 使用下列命令來建立元件，並參考您在上一個步驟中建立的 JSON 檔案名稱： ``` aws imagebuilder create-component --cli-input-json file://create-update-windows-os-component.json ``` **注意** 您必須在 JSON 檔案路徑的開頭包括 `file://` 標記。 JSON 檔案的路徑應遵循執行命令之基礎作業系統的適當慣例。例如，Windows 使用反斜線 (\$1) 來參考目錄路徑，而 Linux 和 macOS 則使用正斜線 (/)。 ------ #### [ macOS ] **將您的應用程式元件文件存放在 Amazon S3 中** 您可以使用 S3 儲存貯體做為 AWS TOE 應用程式元件來源文件的儲存庫。若要存放元件文件，請遵循下列步驟： + **將文件上傳至 Amazon S3** *如果您的文件小於 64 KB，您可以略過此步驟。*大小為 64 KB 或更大的文件必須存放在 Amazon S3 中。 ``` aws s3 cp wget-macos.yaml s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml ``` **從 YAML 文件建立元件** 若要簡化您在 中使用的**create-component**命令 AWS CLI，請建立 JSON 檔案，其中包含您要傳入命令的所有元件參數。包含您先前建立`wget-macos.yaml`的文件位置。`uri` 鍵/值對包含檔案參考。 **注意** JSON 檔案中資料值的命名慣例遵循為映像建置器 API 操作請求參數指定的模式。若要檢閱 API 命令請求參數，請參閱 *EC2 Image Builder API 參考*中的 [CreateComponent](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateComponent.html) 命令。 若要提供資料值做為命令列參數，請參閱 *AWS CLI 命令參考*中指定的參數名稱。 1. **建立 CLI 輸入 JSON 文件** 使用檔案編輯工具來建立名為 的檔案`install-wget-macos-component.json`。包含下列內容： ``` { "name": "install install-wget-macos-component", "semanticVersion": "1.1.2", "description": "An example component that installs and verifies the wget utility on macOS.", "changeDescription": "Initial version.", "platform": "macOS", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/98765432-b123-456b-7f89-0123456f789c", "tags": { "MyTagKey-purpose": "install-software" } } ``` 1. **建立元件** 使用下列命令來建立元件，並參考您在上一個步驟中建立的 JSON 檔案名稱： ``` aws imagebuilder create-component --cli-input-json file://install-wget-macos-component.json ``` **注意** 您必須在 JSON 檔案路徑的開頭包括 `file://` 標記。 JSON 檔案的路徑應遵循執行命令之基礎作業系統的適當慣例。例如，Windows 使用反斜線 (\$1) 來參考目錄路徑，而 Linux 和 macOS 則使用正斜線 (/)。 ------ ### AWS TOE 從 更新元件版本控制 AWS CLI AWS TOE 元件名稱和版本內嵌在元件字首後面的 Amazon Resource Name (ARN) 中。元件的每個新版本都有自己的唯一 ARN。建立新版本的步驟與建立新元件的步驟完全相同，只要該元件名稱的語意版本是唯一的。若要進一步了解映像建置器資源的語意版本控制，請參閱[Image Builder 中的語意版本控制](ibhow-semantic-versioning.md)。 為了確保您指派下一個邏輯版本，請先取得您要變更之元件的現有版本清單。使用 **list-components**命令搭配 AWS CLI，並篩選名稱。 在此範例中，您可以篩選您在先前 Linux 範例中建立的元件名稱。若要列出您建立的元件，請使用您在**create-component**命令中使用的 JSON 檔案的 `name` 參數值。 ``` aws imagebuilder list-components --filters name="name",values="update-linux-os" { "requestId": "123a4567-b890-123c-45d6-ef789ab0cd1e", "componentVersionList": [ { "arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.0", "name": "update-linux-os", "version": "1.0.0", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2020-09-24T16:58:24.444Z" }, { "arn": "arn:aws:imagebuilder:us-west-2:1234560087789012:component/update-linux-os/1.0.1", "name": "update-linux-os", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "123456789012", "dateCreated": "2021-07-10T03:38:46.091Z" } ] } ``` 根據您的結果，您可以判斷下一個版本應該是什麼。 ## 匯入指令碼以從 建立元件 AWS CLI 對於某些案例，從預先存在的指令碼開始可能更容易。在此案例中，您可以使用下列範例。 此範例假設您有一個名為 的檔案 `import-component.json`（如圖所示）。請注意， 檔案會直接參考名為 `AdminConfig.ps1`且已上傳至 的 PowerShell 指令碼`amzn-s3-demo-source-bucket`。目前， `SHELL` 支援元件 `format`。 ``` { "name": "MyImportedComponent", "semanticVersion": "1.0.0", "description": "An example of how to import a component", "changeDescription": "First commit message.", "format": "SHELL", "platform": "Windows", "type": "BUILD", "uri": "s3://amzn-s3-demo-source-bucket/AdminConfig.ps1", "kmsKeyId": "arn:aws:kms:us-west-2:123456789012:key/60763706-b131-418b-8f85-3420912f020c" } ``` 若要從匯入的指令碼建立元件，請執行下列命令。 ``` aws imagebuilder import-component --cli-input-json file://import-component.json ``` ## 自動建置版本管理 當您建立與現有元件具有相同名稱和語意版本的元件時，Image Builder 會自動遞增組建版本 （例如，從 `/1`到 `/2`、 到 `/3`等）。這可讓您對元件進行反覆更新，而無需手動管理版本編號，這在 CI/CD 管道和infrastructure-as-code部署中特別有用。如果元件內容與先前的建置版本相同，Image Builder 會傳回 `ResourceAlreadyExistsException` ，以防止重複的元件消耗您的服務配額。 ## 使用版本參考 當您建立或擷取元件時，Image Builder 會自動在 latestVersionReferences 物件中提供具有萬用字元版本模式的預先建構 ARNs。這些參考可讓您輕鬆地在配方和管道中使用最新版本的元件，而無需手動剖析 ARNs。 **選擇正確的版本參考** + latestVersionArn (x.x.x) - 一律使用絕對最新的元件版本。 + atestMajorVersionArn (1.x.x) - 在主要版本中使用最新的次要和修補程式版本。 + latestMinorVersionArn (1.2.x) - 僅使用最新的修補程式版本。 + latestPatchVersionArn (1.2.3) - 參考特定語意版本，但取得最新的建置版本。 **注意** 為了避免意外費用，請務必清除您從本指南中的範例建立的資源和管道。如需在映像建置器中刪除資源的詳細資訊，請參閱 [刪除過期或未使用的映像建置器資源](delete-resources.md)。