Use ModifyImageSharePermission to share custom images or publish community images - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Manages image sharing permissions. You can share your custom images with other Alibaba Cloud accounts or publish them as community images for others to use.

Operation description

Before you call this operation, read Share a custom image.

When you call this operation, take note of the following sharing rules:

Sharing limits: You can share only custom images that you created under your account. Each image can be shared with up to 50 Alibaba Cloud accounts, and up to 10 Alibaba Cloud accounts at a time.
Impact on instances: After an ECS instance is created from a shared image by calling RunInstances, if the image owner cancels the image sharing or deletes the custom image (DeleteImage), the instance cannot reinitialize its system disk (ReInitDisk).

Important Rule change for sharing encrypted images in Elastic Compute Service (ECS): Only images encrypted with a customer master key (CMK) can be shared. Images encrypted with a service key can no longer be shared and will return an error during sharing. If you have images encrypted with a service key and plan to share them, use the copy image operation (CopyImage) to change the encryption key to a CMK.

To publish or unpublish community images, take note of the following:

Responsibilities and agreements: Community image owners are responsible for the quality and iterative updates of their images. Alibaba Cloud provides only platform support. Before publishing, make sure that you have read and signed the community image agreement. Otherwise, publishing is not allowed. For more information, see Publish a community image.
Encryption limits: Encrypted images cannot be published as community images.
Public access: Community images are fully public. All Alibaba Cloud accounts in the region where the image resides can use the image.
Feature limits: Community images do not support sharing, export, or copy.
Impact of unpublishing: After a community image is unpublished, it is no longer publicly available to other Alibaba Cloud accounts. However, existing sharing relationships are retained.

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:ModifyImageSharePermission

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 to be shared. Important Images encrypted with a service key can no longer be shared. Only images encrypted with a customer master key (CMK) can be shared. An error is returned if you attempt to share an image encrypted with a service key.	m-bp18ygjuqnwhechc****
LaunchPermission	string	No	Note This parameter is in invitational preview and is not available for use.	hide
AddAccount	array	No	The Alibaba Cloud account ID that is authorized to use the shared image. Valid values of N: 1 to 10. If more than 10 Alibaba Cloud accounts are submitted in a single commit, the system processes only the first 10 and ignores the rest.	1234567890
	string	No	The Alibaba Cloud account ID that is authorized to use the shared image.	1234567890
RemoveAccount	array	No	The Alibaba Cloud account ID from which you want to delete image sharing. Valid values of N: 1 to 10. If more than 10 Alibaba Cloud accounts are submitted in a single commit, the system processes only the first 10 and ignores the rest.	1234567890
	string	No	The Alibaba Cloud account ID from which you want to delete image sharing.	1234567890
IsPublic	boolean	No	Specifies whether to publish or unpublish the image as a community image. Valid values: true: Publishes the image as a community image. false: Unpublishes the image and converts it to a regular image. If the image is already a regular image, no changes are made. Default value: false.	false
DryRun	boolean	No

Response elements

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

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
400	MissingParameter	The input parameter "RegionId" that is mandatory for processing this request is not supplied.
400	InvalidGroup.Malformed	The specified Group is wrongly formed.	The specified group does not exist.
400	UnnecessaryParameter.LaunchPermission	The specified parameter "LaunchPermission" is unnecessary if paramter "AddAccounts" or "RemoveAccounts" exist.
400	InvalidParameter.LaunchPermission	The specified parameter "LaunchPermission" is invalid.
400	ForbiddenParameter.LaunchPermission	The specified parameter "LaunchPermission" is forbidden for current account.
403	AssumeRoleError	Requires a RAM role of AliyunECSShareEncryptImageDefaultRole before sharing encrypted image.	Before you share encrypted images, make sure that the AliyunECSShareEncryptImageDefaultRole RAM role is attached to your account.
403	ImageDescription.ContainsSensitiveWords	The specified image description contains sensitive words.	The specified image description contains sensitive words.
403	ImageName.ContainsSensitiveWords	The specified image name contains sensitive words.	The specified image name contains sensitive words.
403	Image.Public	The specified image is public image.
403	CurrentRegion.NotSupportPublicImage	Public image is not supported for current region.
403	Image.NotPublic	The specified image is not public image.	The specified image is not published as a community image and cannot be unpublished.
403	OperationDeined.FullImage	The encrypted image contains multiple snapshots, which do not support share.
403	QuotaExceed.ShareImage	The shared Image Quota exceeds.
403	QuotaExceed.ShareImageUser	The shared Image user Quota exceeds.
403	InvalidImageId.BidMismatch	Cannot share the image with users %s of other sites.	You cannot share images to users in other sites.
403	OperationDeined.EncryptedSnapshot	The image contains encrypted snapshots, which do not support share.	The specified image contains encrypted snapshots and cannot be shared.
403	OperationDenied.InvalidImageStatus	The specified image cannot be shared when it is deprecated.	The specified custom image is in deprecated status and cannot be shared. Call ModifyImageAttribute to modify the status of the specified image first.
403	PublicImageAgreement.NotSigned	The current account has not signed "Community Image Terms of Service".	You have not signed the Community Image Terms of Service.
403	InvalidParameter.IsPublic	The specified parameter IsPublic is conflicted with other parameters.	The specified parameter IsPublic conflict with another parameter.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The specified KMS key is not authorized for the ECS service. Please grant the ECS service permission to use the key in the KMS console and try again.
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The specified KMS key must be in an enabled state. Please enable the key in the KMS console and try again.
403	InvalidOperation.ServiceKeyEncryptedImageUnsupported	The specified image is encrypted with a service key and cannot be shared. Please call the CopyImage operation to encrypt the image with your own KMS key and then share the new image.
403	OperationDenied.KMSKeyUnauthorized	The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
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.
404	InvalidAccount.NotFound	The specified account %s in parameter "AddAccount.n" or "RemoveAccount.n" does not exist.	The account in the AddAccount or RemoveAccount does not exist.
404	InvalidAccount.Forbbiden	The specified Account does not yourself.
404	InvalidKMSKeyId.NotFound	The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.