Modify custom image attributes with the ModifyImageAttribute API - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Modifies the attributes of a custom image, such as the image family, name, boot mode, status, and NVMe support, by calling the ModifyImageAttribute operation with parameters such as ImageId and ImageFamily.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:ModifyImageAttribute

update

*Image

acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the custom image. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
ImageId	string	Yes	The ID of the custom image.	m-bp18ygjuqnwhechc****
ImageName	string	No	The name of the custom image. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`. It can contain digits, periods (.), colons (:), underscores (_), or hyphens (-). Default value: null, which indicates that the original name is retained.	testImageName
Status	string	No	The image status. Valid values: Deprecated: Sets the image to the deprecated state. If you have shared the custom image, you must unshare it before you can set it to the deprecated state. A deprecated image cannot be shared or copied. However, you can use the image to create instances or replace system disks. Available: Sets the image to the available state. You can restore a deprecated image to the available state. Note To roll back a custom image in an image family to the previous version, you can set the latest available custom image to the deprecated state. However, if the image is the only available custom image in the image family, the image family will have no available custom image for creating instances after the image is deprecated. Proceed with caution.	Deprecated
ImageFamily	string	No	The name of the image family. The name must be 2 to 128 characters in length. It must start with a letter or a Chinese character and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`. It can contain digits, periods (.), colons (:), underscores (_), or hyphens (-). Default value: null.	hangzhou-daily-update
BootMode	string	No	The boot mode of the image. Valid values: BIOS: Basic Input/Output System (BIOS) boot mode. UEFI: Unified Extensible Firmware Interface (UEFI) boot mode. UEFI-Preferred: dual boot mode. Important To prevent instances from failing to start due to an unsupported boot mode, make sure that you understand the boot modes supported by the image before you modify this parameter. For more information about image boot modes, see Image boot modes. Valid values: BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
LicenseType	string	No	The license type used to activate the operating system after the image is imported. Currently, only BYOL is supported. BYOL: The license that comes with the source operating system. When you use BYOL, make sure that your license key supports use on Alibaba Cloud.	BYOL
Description	string	No	The description of the custom image. The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`. Default value: null, which indicates that the original description is retained.	testDescription
Features	object	No	The image feature attributes.
NvmeSupport	string	No	Modifies the NVMe support attribute of the image. If this parameter is not specified, the current value is retained. Important Before enabling this feature, make sure that the NVMe driver is pre-installed in the operating system. Recommended procedure: install the driver on an instance, create a custom image, and then call this operation. Forcibly enabling this feature without the driver will cause instance startup failures.	supported
ImdsSupport	string	No	The metadata access mode of the image. Valid values: v1: When you create an ECS instance from this image, you cannot set the metadata access mode to IMDSv2 only (hardened mode). v2: When you create an ECS instance from this image, you can set the metadata access mode to IMDSv2 only (hardened mode). Important ImdsSupport cannot be changed from v2 to v1. If you need to change it, create a new image from the snapshot associated with this image and set the value to v1.	v2
DryRun	boolean	No

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

Examples

Success response

JSON format

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidImageName.Malformed	Image names must be between 2 and 128 characters long, using either English or Chinese characters. The name must start with a letter or a Chinese character, and can include numbers, colons, underscores and hyphens.	The length of the image name is 2 to 128 English or Chinese characters. It must start with an uppercase letter or a Chinese character and can contain numbers, colons (:), underscores (_), or dashes (-).
400	MissingParameter	The input parameter "RegionId" that is mandatory for processing this request is not supplied.
400	InvalidImageName.Duplicated	The specified Image name has already bean used.	The specified image name is already in use.
400	InvalidDescription.Malformed	The specified description is wrongly formed.	The resource description is invalid. The description must be 2 to 256 characters in length and cannot start with http:// or https://.
400	ImageQuotaFull.ImageFamily	The specified image family has exceeded max number of images for one image family.
400	InvalidImageFamily.Malformed	The specified parameter "ImageFamily" is malformed.
400	ImageFamilyQuotaFull	The specified region has exceeded max number of image family.
400	InvalidBootMode.NotSupport	The specified parameter BootMode is not supported.
400	InvalidLicenseType.NotSupported	The specified parameter LicenseType is not supported.
400	InvalidParameter.FeaturesImdsSupport	The specified parameter Features.ImdsSupport is not supported.	The specified parameter Features.ImdsSupport is not supported.
403	ImageStatus.NotAvailable	The specified image status is not available.	The status of the specified image is not Available.
403	ImageStatus.NotDeprecated	The specified image status is not deprecated.	The specified image is not in the Deprecated state.
403	ImageUseShared	The specified image has been shared to others, please remove shared accounts first.
403	OperationDeined.ImageUsingByInstance	The boot mode of the image cannot be modified because it has associated instances.	The boot mode of the image cannot be modified while the image has associated instances.
403	InvalidOperation.FeaturesImdsSupportNotMatch	The specified parameter Features.ImdsSupport can not be set to v1 from v2.	The specified parameter Features.ImdsSupport can not be set to v1 from v2.
403	InvalidStatus.ImageIsCreating	The operation cannot be performed because the image is creating. Please wait until the creation is complete and try again.	The operation cannot be performed because the image is creating. Please wait until the creation is complete and try again.
403	InvalidOperation.PublicImageUnsupported	The community image's publisher is not the current account. Modification is not permitted.	The community image's publisher is not the current account. Modification is not permitted.
403	InvalidDescription.Malformed	The specified parameter description is not valid.	The specified parameter description is invalid.
403	InvalidBootMode.SecureBootUnsupported	Secure Boot requires UEFI or UEFI-Preferred boot mode. Please check the BootMode and try again.	Secure Boot requires UEFI or UEFI-Preferred boot mode. Please check the startup mode and try again.
404	InvalidImageId.NotFound	The specified ImageId does not exist.	The specified image does not exist in this account. Check whether the image ID is correct.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.