Creating a Full-ECS Image

Function

This API is used to create a full-ECS image from an ECS, a Cloud Server Backup Service (CSBS) backup, or a Cloud Backup and Recovery (CBR) backup. This is an asynchronous API. A successful call only means the background has received the request. To see if an image is created successfully, you need to use the asynchronous job query API to query the image creation status. For details, see Querying the Progress of an Asynchronous Job.

Constraints (Creating a Full-ECS Image from an ECS)

• When creating a full-ECS image from an ECS, ensure that the ECS has been properly configured, or the image creation may fail.

  For details, see How Do I Configure an ECS, BMS, or Image File Before I Use It to Create an Image?

• A Windows ECS used to create a full-ECS image cannot have a spanned volume, or data may be lost when ECSs are created from that image.
• A Linux ECS used to create a full-ECS image cannot have a physical disk group or a logical disk that contains multiple physical disks, or data may be lost when ECSs are created from that image.
• An ECS with Dedicated Distributed Storage Service (DSS) disks cannot be used to create a full-ECS image.
• A full-ECS image cannot be published in KooGallery.
• A full-ECS image cannot be exported.
• A full-ECS image cannot be replicated within a region.
• Cross-region replication of full-ECS images is only available for certain regions.

  If a full-ECS image cannot be replicated to a different region, you can use it to create an ECS, use the ECS to create a system disk image and a data disk image, and replicate the images to the destination region.

  A full-ECS image created using an ECS backup can be replicated from the region where they reside to another region, but the replicated full-ECS image cannot be replicated across regions again.

• When creating a full-ECS image from a Windows ECS, you need to set the SAN policy of the ECS to OnlineAll. Otherwise, EVS disks attached to the ECSs created from the image may be offline. For details, see Setting the ECS SAN Policy to OnlineAll.

Constraints (Creating a Full-ECS Image from a CSBS Backup)

• When creating a full-ECS image from a CSBS backup, ensure that the source ECS of the CSBS backup has been properly configured, or the image creation may fail.

  For details, see How Do I Configure an ECS, BMS, or Image File Before I Use It to Create an Image?

• If an ECS is in Stopped state, do not start it when you are using it to create a full-ECS image.
• A CSBS backup used to create a full-ECS image cannot have shared disks.
• Only an available CSBS backup can be used to create a full-ECS image. A CSBS backup can be used to create only one full-ECS image.
• A full-ECS image cannot be published in KooGallery.
• A full-ECS image cannot be exported.
• A full-ECS image cannot be replicated within a region.
• Cross-region replication of full-ECS images is only available for certain regions.

  If a full-ECS image cannot be replicated to a different region, you can use it to create an ECS, use the ECS to create a system disk image and a data disk image, and replicate the images to the destination region.

  A full-ECS image created using an ECS backup can be replicated from the region where they reside to another region, but the replicated full-ECS image cannot be replicated across regions again.

Constraints (Creating a Full-ECS Image from a CBR Backup)

• When creating a full-ECS image from a CBR backup, ensure that the source ECS of the CBR backup has been properly configured, or the image creation may fail.

  For details, see How Do I Configure an ECS, BMS, or Image File Before I Use It to Create an Image?

• A CBR backup can be used to create only one full-ECS image.
• If an ECS is in Stopped state, do not start it when you are using it to create a full-ECS image.
• A full-ECS image created from a CBR backup can be shared with other tenants. However, if it is a shared CBR backup, the full-ECS image created from it cannot be shared.
• A full-ECS image cannot be published in KooGallery.
• A full-ECS image cannot be exported.
• A full-ECS image cannot be replicated within a region.
• Cross-region replication of full-ECS images is only available for certain regions.

  If a full-ECS image cannot be replicated to a different region, you can use it to create an ECS, use the ECS to create a system disk image and a data disk image, and replicate the images to the destination region.

  A full-ECS image created using an ECS backup can be replicated from the region where they reside to another region, but the replicated full-ECS image cannot be replicated across regions again.

• If a full-ECS image is created from a CBR backup and the backup is deleted due to arrears, the full-ECS image will also be deleted.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned. For details about the required permissions, see Permissions and Supported Actions.

URI

POST /v1/cloudimages/wholeimages/action

Request

• Parameters for creating a full-ECS image using an ECS

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition Image name. For details about name, see Image Attributes. Constraints A name cannot start or end with a space. The name length must be 1 to 128 characters. Range A name can contain only letters, digits, spaces, hyphens (-), underscores (_), and periods (.), and cannot start or end with a space. Default Value N/A
  description	No	String	Definition Image description. For details about description, see Image Attributes. Constraints The value contains a maximum of 1,024 characters, including letters and digits. Carriage returns and angle brackets (< >) are not allowed. Range N/A Default Value N/A
  tags	No	Array of strings	Definition Image tags. For details about tag, see Image Tag Format. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Image tags (new format). For details about image_tags, see Table 1. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  instance_id	Yes	String	Definition Cloud server ID. This parameter is required when a cloud server is used to create a full-ECS image. To obtain a cloud server ID: Log in to the ECS console. In the cloud server list, click a cloud server name to view its ID on the details page. Constraints N/A Range N/A Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, an image belongs to the default enterprise project. If the value is a UUID, an image belongs to the enterprise project with this UUID. Default Value N/A
  max_ram	No	Integer	Definition Maximum memory (MB) supported by an image. Constraints The value must be greater than or equal to min_ram. Range An integer greater than 0 Default Value N/A
  min_ram	No	Integer	Definition Minimum memory (MB) supported by an image. Constraints N/A Range An integer greater than 0 Default Value The default value is 0.
  vault_id	No	String	Definition ID of the vault that a cloud server is to be added to or has been added to. Constraints To create a full-ECS image from an ECS, create a backup from the ECS and then use the backup to create a full-ECS image. If a CBR backup is created, vault_id is mandatory. If a CSBS backup is created, vault_id is optional. Range You can obtain a vault ID from the CBR console or by referring to Querying the Vault List. Default Value N/A

• Parameters in the request body when a CSBS backup or CBR backup is used to create a full-ECS image

  Parameter	Mandatory	Type	Description
  name	Yes	String	Definition Image name. For details about name, see Image Attributes. Constraints A name cannot start or end with a space. The name length must be 1 to 128 characters. Range A name can contain only letters, digits, spaces, hyphens (-), underscores (_), and periods (.), and cannot start or end with a space. Default Value N/A
  description	No	String	Definition Image description. For details about description, see Image Attributes. Constraints The value contains a maximum of 1,024 characters, including letters and digits. Carriage returns and angle brackets (< >) are not allowed. Range N/A Default Value N/A
  tags	No	Array of strings	Definition Image tags. For details about tag, see Image Tag Format. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  image_tags	No	Array of objects	Definition Image tags (new format). For details about image_tags, see Table 1. Constraints Use either tags or image_tags. Range A tag key can contain letters, digits, spaces, underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space or start with sys_. A tag value can contain letters, digits, spaces, underscores (_), periods (.), colons (:), slashes (/), plus signs (+), hyphens (-), and at signs (@), but cannot start or end with a space. Default Value N/A
  backup_id	Yes	String	Definition CSBS backup ID or CBR backup ID. To obtain the CSBS backup ID, perform the following operations: Log in to the CSBS console. In the backup list, expand details of the backup to obtain its ID. To obtain the CBR backup ID, perform the following operations: Log in to the CSBS console. On the displayed Cloud Server Backup page, click the Backups tab and obtain the backup ID from the backup list. Constraints N/A Range N/A Default Value N/A
  enterprise_project_id	No	String	Definition Enterprise project that an image belongs to. For more information about enterprise projects and how to obtain enterprise project IDs, see Enterprise Center. Constraints If only enterprise project authorization is used, the enterprise_project_id parameter must be specified. Otherwise, an error may occur, indicating that you do not have the required permissions. Range If the value is 0 or left blank, an image belongs to the default enterprise project. If the value is a UUID, an image belongs to the enterprise project with this UUID. Default Value N/A
  max_ram	No	Integer	Definition Maximum memory (MB) supported by an image. Constraints The value must be greater than or equal to min_ram. Range An integer greater than 0 Default Value N/A
  min_ram	No	Integer	Definition Minimum memory (MB) supported by an image. Constraints N/A Range An integer greater than 0 Default Value The default value is 0.
  whole_image_type	No	String	Definition Method of creating a full-ECS image. Constraints This parameter is mandatory if a full-ECS image is created from a CBR backup. Range If a CBR backup is used to create a full-ECS image, this parameter is mandatory and the value must be CBR. In this case, backup_id is the CBR backup ID. If a CSBS backup is used to create a full-ECS image, this parameter can be left blank and the default value CSBS will be used. In this case, backup_id is the CSBS backup ID. Default Value CSBS

Example Request

• Creating a full-ECS image with parameter tags using an ECS (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  1 2 3 4 5 6 7 8 9 10 11 12

  POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "instance_whole_image", "description": "Create an image from an ECS", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "vault_id": "de9fcf45-11b2-432c-8562-5c5428574600", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a full-ECS image with parameter image_tags using an ECS (ID: 877a2cda-ba63-4e1e-b95f-e67e48b6129a)

  1 2 3 4 5 6 7 8

  POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "instance_whole_image", "description": "Create an image from an ECS", "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a", "vault_id": "de9fcf45-11b2-432c-8562-5c5428574600", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

• Creating a full-ECS image with parameter tags using a CSBS backup or CBR backup (ID: 9b27efab-4a17-4c06-bfa2-3e0cf021d3c3)

  1 2 3 4 5 6 7 8 9 10 11 12

  POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "backup_whole_image", "description": "Create a full-ECS image from a CBR backup", "backup_id": "9b27efab-4a17-4c06-bfa2-3e0cf021d3c3", "whole_image_type": "CBR", "tags": [ "aaa.111", "bbb.333", "ccc.444" ] }

• Creating a full-ECS image with parameter image_tags using a CSBS backup or CBR backup (ID: 9b27efab-4a17-4c06-bfa2-3e0cf021d3c3)

  1 2 3 4 5 6 7 8

  POST https://{Endpoint}/v1/cloudimages/wholeimages/action { "name": "backup_whole_image", "description": "Create a full-ECS image from a CBR backup", "backup_id": "9b27efab-4a17-4c06-bfa2-3e0cf021d3c3", "whole_image_type": "CBR", "image_tags": [{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}] }

Response

• Response parameters

  Parameter	Type	Description
  job_id	String	Definition Asynchronous job ID. For details, see Querying the Progress of an Asynchronous Job. Range N/A

• Example response

  STATUS CODE 200

  1 2 3

  { "job_id": "4010a32b5f909853015f90aaa24b0015" }

Returned Values

• Normal

  200

• Abnormal

  Returned Value	Description
  400 Bad Request	Request error. For details about the returned error code, see Error Codes.
  401 Unauthorized	Authentication failed.
  403 Forbidden	Insufficient permissions.
  404 Not Found	Requested resource not found.
  500 Internal Server Error	Internal service error.
  503 Service Unavailable	Service unavailable.