View a markdown version of this page

Track AMI lineage with watermarks - EC2 Image Builder
Watermark constraintsPrerequisitesAdd watermarks to an image recipeView watermarks on an existing recipeConsiderations
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Track AMI lineage with watermarks

AMI watermarks are simple text labels that track the history of your machine images. You add watermark names to your image recipe, and Image Builder attaches them to the output AMI during the build process.

When you copy or distribute an AMI to other Regions or accounts, the watermarks copy automatically. All copies of your AMI carry the same watermarks. This helps you trace the history of your images.

You cannot make watermarked AMIs public. If your recipe includes watermarks or your source AMI has watermarks, Image Builder rejects distribution configurations that set launch permissions to public.

Key characteristics of AMI watermarks:

  • Purpose – Track AMI lineage across copies and distributions.

  • Scope – Metadata only. Watermarks do not affect instance performance or runtime behavior.

  • Visibility restriction – Watermarked AMIs cannot be made public.

Watermark constraints

The following constraints apply to AMI watermarks in Image Builder image recipes.

Constraint

Value

Watermarks per recipe

1 to 5

Name length

3 to 128 characters

Allowed characters

Letters, numbers, spaces, and the following special characters: ( ) [ ] . / - ' @ _

Edge characters

Names cannot begin or end with a space

Case sensitivity

Watermark names are case-sensitive

Duplicates

Duplicate names within the same recipe are not permitted

Total per output AMI

Source AMI watermarks plus recipe watermarks cannot exceed 5

Prerequisites

Before you use AMI watermarks, verify the following requirements.

  • AMI watermarks are supported only for image recipes, not container recipes.

  • Your Image Builder execution role must include the ec2:AttachImageWatermark permission on arn:aws:ec2:*::image/*. If you use the Image Builder service-linked role, this permission is included automatically.

Add watermarks to an image recipe

You can add watermarks when you create an image recipe or a new version of an existing recipe. Choose one of the following tabs for instructions.

Console
To add watermarks to an image recipe

  1. When you create or version an image recipe, in the recipe configuration section, expand AMI watermarks.

  2. Enter a watermark name (3 to 128 characters). Choose Add watermark to add more names (up to 5 total).

  3. Complete the remaining recipe creation steps, and then choose Create recipe.

Amazon CLI

To add watermarks with the Amazon CLI, include the amiWatermarks parameter in your JSON input file for the create-image-recipe command.

The following example shows a recipe JSON file with watermarks configured.

{
    "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"
    ]
}

Run the following command to create the recipe.

aws imagebuilder create-image-recipe --cli-input-json file://create-watermarked-recipe.json

The following list describes the amiWatermarks parameter.

  • amiWatermarks (array of strings, optional) – A list of watermark names to attach to output AMIs built from this recipe. Specify 1 to 5 names. Each name must be 3 to 128 characters, and can include letters, numbers, spaces, and the following special characters: ( ) [ ] . / - ' @ _

Amazon CloudFormation

You can specify AMI watermarks in an AWS::ImageBuilder::ImageRecipe resource by using the AmiWatermarks property.

The following example shows a minimal image recipe template with watermarks configured.

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

You can set the AmiWatermarks property only at creation time. Because image recipes are immutable, changing watermarks requires a new recipe version.

For more information about the AmiWatermarks property, see AWS::ImageBuilder::ImageRecipe in the Amazon CloudFormation Template Reference.

View watermarks on an existing recipe

You can view the watermarks configured for a recipe by calling the get-image-recipe command in the Amazon CLI.

aws imagebuilder get-image-recipe --image-recipe-arn arn:aws:imagebuilder:us-west-2:111122223333:image-recipe/my-watermarked-recipe/1.0.0

The response includes the amiWatermarks array if watermarks were configured for that recipe version.

Considerations

Keep the following points in mind when you use AMI watermarks.

  • Watermarks from a source AMI plus watermarks defined in the recipe combine on the output AMI. The total cannot exceed 5. If the combined count exceeds 5, the build fails.

  • If you distribute a watermarked AMI to other Regions or accounts, the watermarks propagate automatically.

  • Image Builder validates that watermarked AMIs are not set to public at image creation time. If your recipe has watermarks (or the source AMI has watermarks) and the distribution configuration sets launch permissions to public, Image Builder returns an InvalidParameterCombinationException error.