• Image Management Service

ims
  1. Help Center
  2. Image Management Service
  3. Developer Guide
  4. Creating an Image Using an External Image File

Creating an Image Using an External Image File

Scenario

An external image file can also be used to create a private image.

NOTE:
  • The API used here is the same as the one for creating a private image from an ECS except for the parameters in the request body.
  • The token obtained from IAM is valid for only 24 hours. If you want to use a token for authentication, you can cache it to avoid frequently calling the IAM API.

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.

Involved APIs

If you use a token for authentication, you must obtain the token and add X-Auth-Token to the request header of the IMS API when making an API call.

  • IAM API used to obtain the token

    URI format: POST https://IAM endpoint/v3/auth/tokens

  • IMS API used to create a data disk image using an external image file

    URI format: POST /v1/cloudimages/dataimages/action

Procedure

  1. Obtain the token by referring to Token Authentication.
  2. Send POST https://IMS endpoint/v2/cloudimages/action.
  3. Add X-Auth-Token to the request header.
  4. Specify the following parameters in the request body:
    {
      "name": "ims_test_file", //Image name (mandatory, string)
      "description": "Image creation using an image file uploaded to the OBS bucket", //Image description (optional, string)
      "image_url": "ims-image:centos70.qcow2",//Image file address (mandatory, string)
      "os_version": " CentOS 7.0 64bit",//OS version (optional, string)
      "is_config_init":true,//Initialized or not (optional, Boolean)
      "min_disk": 40,//Minimum system disk space (mandatory, int)
      "is_config":true,//Whether to enable automatic configuration (optional, Boolean)
      "tags":[  
                "aaa.111",  
                "bbb.333",  
                "ccc.444"  
            ] //Image tag list (optional, List<String>)
    }
    NOTE:

    For how to obtain the address of the image file in the OBS bucket, see "Operations on Buckets" in the Object Storage Service API Reference.

    • If the request is successful, a job ID is returned.
    • If the request fails, an error code and error information are returned. For details about error codes, see Error Codes.
  5. Query job details using the job ID by referring to Querying Job Details.

    If the job status is SUCCESS, the private image is successfully created.

    For details about status codes for request exceptions, see Status Code.

  6. Obtain the image ID from the job body and query, delete, and export the private image using the image ID.