本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用浮水印追蹤 AMI 歷程
AMI 浮水印是追蹤機器映像歷史記錄的簡單文字標籤。您可以將浮水印名稱新增至映像配方，而映像建置器會在建置程序期間將其連接至輸出 AMI。
當您將 AMI 複製或分發到其他區域或帳戶時，浮水印會自動複製。AMI 的所有副本都具有相同的浮水印。這可協助您追蹤映像的歷史記錄。
您無法將浮水印 AMIs設為公有。如果您的配方包含浮水印或來源 AMI 具有浮水印，Image Builder 會拒絕將啟動許可設定為公有的分佈組態。
AMI 浮水印的主要特性：
+ **目的** – 追蹤跨複本和分佈的 AMI 歷程。
+ **範圍** – 僅限中繼資料。浮水印不會影響執行個體效能或執行時間行為。
+ **可見性限制** – 浮水印 AMIs無法公開。
**Topics**
+ [Watermark 限制條件](#ami-watermarks-constraints)
+ [先決條件](#ami-watermarks-prereqs)
+ [將浮水印新增至映像配方](#ami-watermarks-add)
+ [檢視現有配方上的浮水印](#ami-watermarks-view)
+ [考量事項](#ami-watermarks-considerations)
## Watermark 限制條件
下列限制條件適用於映像建置器映像配方中的 AMI 浮水印。
| 限制條件 | Value |
| --- | --- |
| 每個配方的浮水印 | 1 到 5 |
| 名稱長度 | 3 到 128 個字元 |
| 允許的字元 | 字母、數字、空格和下列特殊字元： `( ) [ ] . / - ' @ _` |
| Edge 字元 | 名稱不能以空格開頭或結尾 |
| 區分大小寫 | 浮水印名稱區分大小寫 |
| Duplicates (複製) | 不允許相同配方中的重複名稱 |
| 每個輸出 AMI 的總計 | 來源 AMI 浮水印加上配方浮水印不得超過 5 |
## 先決條件
在使用 AMI 浮水印之前，請確認下列需求。
+ AMI 浮水印僅支援映像配方，不支援容器配方。
+ 您的映像建置器執行角色必須包含 上的 `ec2:AttachImageWatermark`許可`arn:aws:ec2:*::image/*`。如果您使用 Image Builder 服務連結角色，則會自動包含此許可。
## 將浮水印新增至映像配方
您可以在建立映像配方或現有配方的新版本時新增浮水印。選擇下列其中一個索引標籤以取得指示。
------
#### [ Console ]
**將浮水印新增至映像配方**
1. 當您建立或版本映像配方時，請在配方組態區段中展開 **AMI 浮水印**。
1. 輸入浮水印名稱 (3 到 128 個字元）。選擇**新增浮水印**以新增更多名稱 （最多共 5 個）。
1. 完成剩餘的配方建立步驟，然後選擇**建立配方**。
------
#### [ AWS CLI ]
若要使用 新增浮水印 AWS CLI，請在**create-image-recipe**命令的 JSON 輸入檔案中包含 `amiWatermarks` 參數。
下列範例顯示已設定浮水印的配方 JSON 檔案。
```
{
"name": "{{MyWatermarkedRecipe}}",
"description": "{{Recipe with AMI watermarks for lineage tracking.}}",
"parentImage": "{{ami-1234567890abcdef1}}",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:{{us-west-2}}:{{111122223333}}:component/{{my-component/1.0.0/1}}"
}
],
"amiWatermarks": [
"{{ProductionV1}}",
"{{team-alpha}}"
]
}
```
執行下列命令來建立配方。
```
aws imagebuilder create-image-recipe --cli-input-json file://{{create-watermarked-recipe.json}}
```
下列清單說明 `amiWatermarks` 參數。
+ **amiWatermarks** （字串陣列，選用） – 要連接至從此配方建置之輸出 AMIs 的浮水印名稱清單。指定 1 到 5 個名稱。每個名稱必須為 3 到 128 個字元，且可包含字母、數字、空格和下列特殊字元： `( ) [ ] . / - ' @ _`
------
#### [ CloudFormation ]
您可以使用 `AmiWatermarks` 屬性在 `AWS::ImageBuilder::ImageRecipe` 資源中指定 AMI 浮水印。
下列範例顯示已設定浮水印的最小影像配方範本。
```
Resources:
WatermarkedRecipe:
Type: AWS::ImageBuilder::ImageRecipe
Properties:
Name: {{MyWatermarkedRecipe}}
Version: {{1.0.0}}
ParentImage: arn:aws:imagebuilder:{{us-west-2}}:aws:image/amazon-linux-2023-x86/x.x.x
Components:
- ComponentArn: arn:aws:imagebuilder:{{us-west-2}}:{{111122223333}}:component/{{my-component/1.0.0/1}}
AmiWatermarks:
- {{ProductionV1}}
- {{team-alpha}}
```
您只能在建立時設定 `AmiWatermarks` 屬性。由於映像配方不可變，因此變更浮水印需要新的配方版本。
如需 `AmiWatermarks` 屬性的詳細資訊，請參閱 *AWS CloudFormation 範本參考*中的 [AWS::ImageBuilder::ImageRecipe](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-imagebuilder-imagerecipe.html)。
------
## 檢視現有配方上的浮水印
您可以透過在 中呼叫 **get-image-recipe**命令來檢視為配方設定的浮水印 AWS CLI。
```
aws imagebuilder get-image-recipe --image-recipe-arn arn:aws:imagebuilder:{{us-west-2}}:{{111122223333}}:image-recipe/{{my-watermarked-recipe}}/{{1.0.0}}
```
如果已針對該配方版本設定浮水印，則回應會包含`amiWatermarks`陣列。
## 考量事項
當您使用 AMI 浮水印時，請記住下列幾點。
+ 來自來源 AMI 的浮水印加上配方中定義的浮水印會結合在輸出 AMI 上。總計不能超過 5。如果合併計數超過 5，則建置會失敗。
+ 如果您將浮水印 AMI 分佈到其他區域或帳戶，浮水印會自動傳播。
+ 映像建置器會驗證浮水印 AMIs映像建立時未設為公有。如果您的配方具有浮水印 （或來源 AMI 具有浮水印），且分佈組態將啟動許可設定為公有，則 Image Builder 會傳回`InvalidParameterCombinationException`錯誤。