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

Call the ModifyImageAttribute API to modify the attributes of a custom image, such as its image family, name, boot mode, status, or whether NVMe is supported.

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 ID of the region where the custom image is located. You can call the DescribeRegions operation to view the latest list of Alibaba Cloud regions.	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. The name cannot start with `aliyun` or `acs:` and cannot contain `http://` or `https://`. It can contain digits, periods (.), colons (:), underscores (_), and hyphens (-). If you do not specify this parameter, the original name is retained.	testImageName
Status	string	No	The image status. Valid values: `Deprecated`: Deprecates the image. If a custom image that you want to deprecate is shared, you must unshare it first. You cannot share or copy a deprecated image. However, you can use the image to create an instance or replace a system disk. `Available`: Makes the image available. You can change the status of a deprecated image to `Available`. Note However, if this is the only available custom image in the image family, deprecating it prevents the creation of instances from any image in that family. Use this option 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. The name cannot start with `aliyun` or `acs:` and cannot contain `http://` or `https://`. It can contain digits, periods (.), colons (:), underscores (_), and hyphens (-). By default, this parameter is empty.	hangzhou-daily-update
BootMode	string	No	The boot mode of the image. Valid values: `BIOS`: BIOS boot mode. `UEFI`: UEFI boot mode. `UEFI-Preferred`: UEFI-preferred boot mode. Important To prevent startup failures, verify the boot modes that the image supports before you change its boot mode. For more information, see Boot modes. Valid values: BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
LicenseType	string	No	The license type for activating the operating system after you import the image. The only valid value is `BYOL`. `BYOL`: Bring Your Own License. If you use the BYOL license type, you must ensure that your license key is supported for use on Alibaba Cloud.	BYOL
Description	string	No	The new description of the custom image. The description must be 2 to 256 characters in length and cannot start with `http://` or `https://`. If you do not specify this parameter, the original description is retained.	testDescription
Features	object	No	The features of the image.
NvmeSupport	string	No	Specifies whether the image supports NVMe. Valid values: `supported`: The image supports NVMe. Instances that you create from this image support the NVMe protocol. `unsupported`: The image does not support NVMe. Instances that you create from this image do not support the NVMe protocol.	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 `enforced mode`. `v2`: When you create an ECS instance from this image, you can set the metadata access mode to `enforced mode`. Important You cannot change the value of `ImdsSupport` from `v2` to `v1`. To use the `v1` mode, create a new image from a snapshot that is associated with the image and set `ImdsSupport` to `v1`.	v2
DryRun	boolean	No	Specifies whether to perform a dry run to check whether the request is valid. Valid values: `true`: performs a dry run to check the request for validity, syntax, and required permissions. If the request fails the dry run, an error message is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. `false` (default): sends the request. If the request passes the validation checks, the operation is performed.

Response elements

Element	Type	Description	Example
	object	The response data.
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.
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.
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.
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.