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).

Semantic versioning in Image Builder

Image Builder uses semantic versioning to organize resources and ensure that they have unique IDs. The semantic version has four nodes:

<major>.<minor>.<patch>/<build>

You can assign values for the first three, and can filter on all of them.

Semantic versioning is included in each object's Amazon Resource Name (ARN), at the level that applies to that object as follows:

Assignment: For the first three nodes you can assign any positive integer value, or zero, with an upper limit of 2^30-1, or 1073741823 for each node. Image Builder automatically assigns the build number to the fourth node.

Patterns: You can use any numeric pattern that adheres to the assignment requirements for the nodes that you can assign. For example, you might choose a software version pattern, such as 1.0.0, or a date, such as 2021.01.01.

Selection: With semantic versioning, you have the flexibility to use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards.

For example, given the following recent versions: 2.2.4, 1.7.8, and 1.6.8, version selection using wildcards produces the following results:

Using version references

Version references are ready-to-use ARN strings that incorporate wildcard patterns based on the semantic version of the resource you created or retrieved. Instead of writing custom code to parse ARNs and insert wildcards, Image Builder does this work for you.

When you create or retrieve Image Builder resources, Image Builder automatically provides pre-constructed ARNs with wildcard version patterns in the latestVersionReferences object. This eliminates the need to manually parse and reconstruct ARNs when you want to reference resources using wildcard versioning patterns.

For example, when you create a component with version 1.2.3, Image Builder returns:

{
    "componentBuildVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.3/1",
    "latestVersionReferences": {
        "latestVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/x.x.x",
        "latestMajorVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.x.x",
        "latestMinorVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.x",
        "latestPatchVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.3"
    }
}
		

Available version reference patterns

The latestVersionReferences object contains four ARN patterns:

Resources that return version references

Version references are returned by Create and Get APIs for all versioned Image Builder resources:

Note: For Image Builder-managed workflows, only latestVersionArn (x.x.x) is returned, since Image Builder requires you to always use the latest version of Image Builder-managed workflows.