• Image Management Service

ims
  1. Help Center
  2. Image Management Service
  3. API Reference
  4. APIs
  5. Image (Extension APIs)
  6. Creating an Image

Creating an Image

Function

This API is used to create a private image. The following methods are supported:

  • Create a private image from an ECS.
  • Create a private image from an external image file uploaded to an OBS bucket.

The API is an asynchronous one. If it is successfully called, the cloud service system receives the request. However, you need to use the asynchronous job query API to query the image creation status. For details, see Asynchronous Job Query.

You cannot export public images (such as Windows, SUSE Linux, Red Hat Linux, Oracle Linux, and Ubuntu) or private images created using these public images.

URI

URI format

POST /v2/cloudimages/action

Constraints (Creating a Windows Image Using an External Image File)

  • External image files in QCOW2 format cannot be encrypted.
  • The size of external image files must not exceed 1 TB. If an image file is larger than 128 GB, you need to change the file format to ZVHD2 or RAW and use the fast image creation function.
    • The fast image creation function is only available for image files in RAW or ZVHD2, and the size of image files must be less than 1 TB.
    • Before using fast image creation to import RAW image files, ensure that image files have been optimized and that bitmap files have been generated for each image file.
    • Before using fast image creation to import ZVHD2 image files, ensure that image files have been optimized.
  • The system disk size in external image files is from 1 GB to 1024 GB.
  • The administrator account and its password must have been configured for the external image file using Windows. In subsequent operations, you may use the username and password to log in to and configure the ECS.
  • External image files must support the Integrated Drive Electronics (IDE) device driver, which is automatically loaded when the system starts.
  • The boot partition and system partition of external image files must be on the same disk.
  • BIOS must be selected as the boot mode during image creation.
  • Ensure that each external image file contains the password or certificate used to log in to ECSs made from the created private image, or ensure that Cloudbase-Init has been installed and configured in the image file.
  • To protect ECSs created from an external image file against attacks, ensure that the initial password of the image file contains at least the following types of characters:
    • Uppercase letters
    • Lowercase letters
    • Digits
    • Special characters, including !@$%^-_=+[{}]:,./?
  • If disks in an external image file use specific encryption mechanisms, ECSs created using the private image registered from the external image file may become unavailable.
  • Some default drivers are not supported on the cloud platform. Therefore, you cannot use external image files with OEM OSs to create private images.
  • OSs in external image files cannot be bound to specified hardware.
  • OSs in external image files must support full virtualization.
  • When uploading external image files to an OBS bucket, you must select one with Standard storage.

Constraints (Creating a Linux Image Using an External Image File)

  • External image files in QCOW2 format cannot be encrypted.
  • The size of external image files must not exceed 1 TB. If an image file is larger than 128 GB, you need to change the file format to ZVHD2 or RAW and use the fast image creation function.
    • The fast image creation function is only available for image files in RAW or ZVHD2, and the size of image files must be less than 1 TB.
    • Before using fast image creation to import RAW image files, ensure that image files have been optimized and that bitmap files have been generated for each image file.
    • Before using fast image creation to import ZVHD2 image files, ensure that image files have been optimized.
  • For a Linux OS, the /etc/fstab file cannot contain configuration items for automatic data disk attaching. Otherwise, ECSs created using the private image cannot be logged in to.
  • The system disk size in external image files is from 1 GB to 1024 GB.
  • Ensure that each image file contains the password or certificate used to log in to the ECS created using the image, or ensure that Cloud-Init has been installed and configured in the image file.
  • Each external image file must contain user root and its password. In subsequent operations, you may use the username and password to log in to and configure the ECS.
  • To protect ECSs created from an external image file against attacks, ensure that the initial password of the image file contains at least the following types of characters:
    • Uppercase letters
    • Lowercase letters
    • Digits
    • Special characters, including !@$%^-_=+[{}]:,./?
  • External image files must support the Integrated Drive Electronics (IDE) and ParaVirtual OPerationS (PVOPS) device driver, which is automatically loaded when the system starts.
  • To create high-performance ECSs, ensure that external image files support VirtIO drivers, and the drivers automatically load upon system boot.
  • The boot partition and system partition of external image files must be on the same disk.
  • BIOS must be selected as the boot mode during image creation.
  • If disks in an external image file use specific encryption mechanisms, ECSs created using the private image registered from the external image file may become unavailable.
  • Some default drivers are not supported on the cloud platform. Therefore, you cannot use external image files with OEM OSs to create private images.
  • OSs in external image files cannot be bound to specified hardware.
  • OSs in external image files must support full virtualization.
  • If an external image file uses Logical Volume Manager (LVM) as the system disk, ECSs created using the private image registered from the external image file do not support file injection.
  • When uploading external image files to an OBS bucket, you must select one with Standard storage.

Constraints (Creating a Data Disk Image Using a Data Disk)

  • When creating a data disk image using an ECS data disk, ensure that the ECS has a system disk and that the data disk is not empty.
  • One data disk image can be used only for one data disk.

Request

  • Parameters in the request body when an ECS is used to create an image

    Parameter

    Mandatory

    Type

    Description

    name

    Yes

    String

    Specifies the name of the system disk image. For detailed description, see Image Attributes.

    description

    No

    String

    Provides supplementary information about the image. For detailed description, see Image Attributes. The value contains a maximum of 1024 characters and consists of only letters and digits. Carriage returns and angle brackets (< >) are not allowed. This parameter is left blank by default.

    instance_id

    Yes

    String

    Specifies the ID of the ECS that needs to be converted into an image.

    If an ECS is used to create a private image, set the value of this parameter to the ECS ID.

    data_images

    No

    List<Map>

    Specifies the data disk information to be converted. This parameter is mandatory when an ECS data disk is used to create a private data disk image. There are two mandatory fields in the map: Name (which is a string and indicates the data disk image name) and volume_id (which is a string and indicates the data disk ID), and two optional fields: description (which is string and provides supplementary information about the data disk) and tags (which is a list of strings and lists the data disk image tags).

    If you want to use a data disk to create a data disk image, set the values of parameters in the table, such as name, description, and tags by referring to those in data_image. instance_id is not allowed.

    tags

    No

    List<String>

    Lists the image tags. This parameter is left blank by default.

    Use either tags or image_tags.

    image_tags

    No

    List<Map>

    Lists the image tags. This parameter is left blank by default. Use either tags or image_tags.

    max_ram

    No

    Int

    Specifies the maximum memory of the image in the unit of MB.

    min_ram

    No

    Int

    Specifies the minimum memory of the image in the unit of MB. The default value is 0, indicating that the memory is not restricted.

  • Parameters in the request body when an image file uploaded to the OBS bucket is used to create an image

    Parameter

    Mandatory

    Type

    Description

    name

    Yes

    String

    Specifies the image name. For detailed description, see Image Attributes.

    description

    No

    String

    Provides supplementary information about the image. For detailed description, see Image Attributes. The value contains a maximum of 1024 characters and consists of only letters and digits. Carriage returns and angle brackets (< >) are not allowed. This parameter is left blank by default.

    os_version

    No

    String

    Specifies the OS version.

    This parameter is valid if an external image file uploaded to the OBS bucket is used to create an image. For its value, see Values of Related Parameters.

    image_url

    Yes

    String

    Specifies the URL of the external image file in the OBS bucket.

    This parameter is mandatory if an external image file in the OBS bucket is used to create an image. The format is OBS bucket name:Image file name.

    NOTICE:

    The storage class of the OBS bucket must be Standard.

    min_disk

    Yes

    Int

    Specifies the minimum size of the system disk in the unit of GB.

    This parameter is mandatory if an external image file in the OBS bucket is used to create an image. The value ranges from 1 GB to 1024 GB.

    is_config

    No

    Boolean

    Specifies whether automatic configuration is enabled.

    The value can be true or false.

    If automatic configuration is required, set the value to true. Otherwise, set the value to false The default value is false.

    For details about automatic configuration, see Creating a Linux System Disk Image Using an External Image File > Registering an Image File as a Private Image in the Image Management Service User Guide.

    cmk_id

    No

    String

    Specifies the master key used for encrypting an image. For its value, see the Key Management Service User Guide.

    tags

    No

    List<String>

    Lists the image tags. Use either tags or image_tags.

    image_tags

    No

    List<Map>

    Lists the image tags. This parameter is left blank by default. Use either tags or image_tags.

    type

    No

    String

    Specifies the image type.

    The value can be ECS, BMS, FusionCompute, or Ironic. The default value is ECS.

    • ECS and FusionCompute: indicate an ECS image.
    • BMS and Ironic: indicate a BMS image.

    max_ram

    No

    Int

    Specifies the maximum memory of the image in the unit of MB.

    min_ram

    No

    Int

    Specifies the minimum memory required by the image in the unit of MB. The default value is 0, indicating that the memory is not restricted.

  • Example requests
    • Request for creating a system disk image using an ECS
      POST /v2/cloudimages/action
      {
             "name": "ims_test",
          "description":"Create an image using an ECS.",
             "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a",
             "tags":[  
                   "aaa.111",  
                   "bbb.333",  
                   "ccc.444"  
               ]
      } 
    • Request for creating a data disk image using an ECS
      POST /v2/cloudimages/action
      {
             "data_images": [{"name": "ims_data_image_test",
             "description": "Create a data disk image using an ECS data disk.",
             "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30",
             "tags":[
                        "aaa.111",
                        "bbb.333",
                        "ccc.444"
                    ]}]
      }
    • Request for creating an image using an external image file uploaded to the OBS bucket
      POST /v2/cloudimages/action
      {
            "name": "ims_test_file",
        "description": "Create an image using a file in the OBS bucket.",
            "image_url": "ims-image:centos70.qcow2",
            "os_version": " CentOS 7.0 64bit",
            "is_config_init":true,
            "min_disk": 40,
            "is_config":true,
            "tags":[  
                  "aaa.111",  
                  "bbb.333",  
                  "ccc.444"  
              ]     
      }
    • Request for creating a system disk image using an ECS
      POST /v2/cloudimages/action
      {
             "name": "ims_test",
          "description":"Create an image using an ECS.",
             "instance_id": "877a2cda-ba63-4e1e-b95f-e67e48b6129a",
             "image_tags":[{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}]
      } 
    • Request for creating a data disk image using an ECS
      POST /v2/cloudimages/action
      {
             "data_images": [{"name": "ims_data_image_test",
             "description": "Create a data disk image using an ECS data disk.",
             "volume_id": "c5dfbd0c-bf0a-4798-a453-61dc6b54aa30",
             "image_tags":[{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}]
             }]
      }
    • Request for creating an image using an external image file uploaded to the OBS bucket
      POST /v2/cloudimages/action
      {
             "name": "ims_test_file",
        "description": "Create an image using a file in the OBS bucket.",
             "image_url": "ims-image:centos70.qcow2",
             "os_version": " CentOS 7.0 64bit",
             "is_config_init":true,
             "min_disk": 40,
             
             "image_tags":[{"key":"key2","value":"value2"},{"key":"key1","value":"value1"}]    
      }

Response

  • Parameter description

    Parameter

    Type

    Description

    job_id

    String

    Specifies the asynchronous job ID.

  • Example response
    STATUS CODE 200
    {
        "job_id": "8a12fc664fb4daa3014fb4e581380005"
    }

Returned Values

  • Normal

    200

  • Abnormal

    Returned Value

    Description

    400 Bad Request

    Request error. For details, see Error Codes.

    401 Unauthorized

    Authentication failed.

    403 Forbidden

    You do not have the rights to perform the operation.

    404 Not Found

    The requested resource was not found.

    500 Internal Server Error

    Internal service error.

    503 Service Unavailable

    The service is unavailable.