Group related images into a family to always launch instances from the latest version, with built-in rollback by deprecating or deleting images.
When you create an ECS instance with an image family instead of an image ID, ECS selects the most recent Available image in that family. To roll back, deprecate or delete the current latest image — ECS then falls back to the previous one.
How it works
Image families use the ImageFamily parameter in the RunInstances and CreateInstance API operations. Set ImageFamily instead of ImageId, and ECS resolves the family to the latest Available image at launch time.
Latest image selection rule: ECS selects the image with the most recent creation timestamp. For example, if a family contains images created on January 1 and January 3, 2020, ECS selects the January 3 image.
In multi-region deployments, ECS selects the latest Available image in the target region, not the globally latest image.
Image family-based instance creation is only supported via API. The ECS console does not support this feature.
Supported image types
All image types support image families. The following table describes how family information is assigned for each type.
| Image type | Image family behavior |
|---|---|
| Public images | Have family information by default. See Overview of public images. |
| Custom images | Assign a family when creating the image or by modifying its attributes. See Set an image family. Family names cannot start with acs. Copies do not inherit the source image's family. |
| Shared images | Inherit the family if the source custom image belongs to one. The sharer sees the original name; the sharee sees acs:<UID of sharing account>:<family name>. |
| Community images | Inherit the family if the source custom image belongs to one. The provider sees the original name; other users see acs:<UID of image provider>:<family name>. |
Family name visibility across accounts
The following example shows how family names differ by account role.
User M has custom images A1 and B1, both in Image Family A. User M publishes A1 as community image A2 and shares B1 as shared image B2 with User N.
| Image | Family name seen by User N |
|---|---|
| Community Image A2 | acs:<UID of User M>:A |
| Shared Image B2 | acs:<UID of User M>:A |
Example 1: User N calls RunInstances or CreateInstance with ImageFamily set to acs:<UID of User M>:A. ECS selects the latest Available image in that family (A2 or B2) to create the instance.
Example 2: User N copies B2 to create custom image B3. B3 does not inherit B2's family. User N must assign a family to B3 separately.
Example 3: If User M shares B1 as B2 with User N (without publishing A1 as a community image), User N can still reference acs:<UID of User M>:A to create instances using B2.
Example 4: Custom image family names cannot start with acs. User N cannot add a custom image to the acs:<UID of User M>:A family that contains Shared Image B2 and Community Image A1.
Roll back to a previous version
Deprecate or delete the current latest Available image. ECS then resolves the family to the next most recent Available image.
Deprecate or restore custom images in the ECS console or by calling ModifyImageAttribute. See Deprecate or restore an image.
Query the latest Available image in a family with DescribeImageFromFamily, or retrieve the family name of a specific image with DescribeImages.
Deprecated image behavior: A deprecated custom image can still create instances and replace system disks, but cannot be shared or copied.
Flowchart
The following figure shows the image family workflow.
Limitations
| Constraint | Detail |
|---|---|
| Image families per region | 100 per Alibaba Cloud account |
| Images per family | 100 |
| Family name uniqueness | Unique within an account per region; the same name can be reused across regions |
| Custom image family names | Cannot start with acs |
| Changing or deleting a family | Once assigned, the family can be changed but not removed |
| Image copies | Copies do not inherit the source image's family |
| Deprecation: image types | Only custom images can be deprecated or restored |
| Deprecation: shared images | Unshare an image before deprecating it |