Image¶
Table of contents
Overview¶
Images provide templates for virtual machine file systems. Images can be RootVolumeTemplate that provide templates for VMs’ root volumes where VMs’ operating systems install; or DataVolumeTemplate that provide templates for VMs’ data volumes that usually contain non operating system data; or ISO that can be used to install operating systems to blank root volumes.
Images are stored on backup storage. Prior to starting a VM, if the image to create VM root volume is not in primary storage‘s image cache, it will be downloaded to the cache first. So when creating a VM with an image at the first time, it takes longer than normal because the downloading process.
ZStack uses thin provisioning to create root volumes. Root volumes from the same image share the same base in primary storage’s image cache, and any changes made to the root volumes do not affect the base image.
Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
state | see state |
|
0.6 | |
status | see status |
|
0.6 | |
size | image size, in bytes | 0.6 | ||
url | url the image registered from, see url | 0.6 | ||
mediaType | image’s media type, see media type |
|
0.6 | |
guestOsType | a string for user records VM’s operating system type | true | 0.6 | |
platform | indicates platform of VM’s operating system, see platform |
|
0.6 | |
system | see system image | 0.6 | ||
format | see format |
|
0.6 | |
md5Sum | image’s md5sum Note MD5 sum is not calculated at this ZStack version |
0.6 | ||
type | reserved field |
|
0.6 | |
backupStorageRefs | a list of backup storage reference | 0.6 |
Example¶
{
"backupStorageRefs": [
{
"backupStorageUuid": "8b99641a4d644820932e0ec5ada78eed",
"createDate": "Jun 1, 2015 6:17:48 PM",
"imageUuid": "b395386bdb4a4ff1b1850a457c949c5e",
"installPath": "/export/backupStorage/sftp/templates/acct-36c27e8ff05c4780bf6d2fa65700f22e/b395386bdb4a4ff1b1850a457c949c5e/centos_400m_140925.template",
"lastOpDate": "Jun 1, 2015 6:17:48 PM"
}
],
"createDate": "Jun 1, 2015 6:17:40 PM",
"description": "Test Image Template for network test",
"format": "qcow2",
"guestOsType": "unknown",
"lastOpDate": "Jun 1, 2015 6:17:40 PM",
"md5Sum": "not calculated",
"mediaType": "RootVolumeTemplate",
"name": "image_for_sg_test",
"platform": "Linux",
"size": 419430400,
"state": "Enabled",
"status": "Ready",
"system": false,
"type": "zstack",
"url": "http://172.16.0.220/templates/centos_400m_140925.img",
"uuid": "b395386bdb4a4ff1b1850a457c949c5e"
},
State¶
Images have two states:
Enabled:
The state that allows VMs to be created from this image
Disabled:
The state that DOESN’T allow VMs to be created from this image
Status¶
Status indicates images’ lifecycle:
Creating:
The image is in process of creating from a volume or a volume snapshot; not ready to use.
Downloading:
The image is in process of downloading from a url; not ready to use.
Ready:
The image is on backup storage and ready to use.
URL¶
Depending on how an image was created on a backup storage, the url has different meanings; when an image was downloaded from a web server, the url is the HTTP/HTTPS link; when an image was created from a volume or a volume snapshot, the url is a string encoding UUID of the volume or the volume snapshot, like:
volume://b395386bdb4a4ff1b1850a457c949c5e
volumeSnapshot://b395386bdb4a4ff1b1850a457c949c5e
Note
In this ZStack version, the only way to register an image to backup storage is providing a URL that is a HTTP/HTTPS link and calling AddImage.
Media Type¶
A media type indicates the image’s usage.
RootVolumeTemplate:
The image is used to create root volumes.
DataVolumeTemplate:
The image is used to create data volumes.
ISO:
The image is used to install operating systems to blank root volumes.
Platform¶
Platform gives ZStack a hint that whether to use paravirtualization for VMs created from this image.
Use paravirtualization |
|
Not to use paravirtualization |
|
System Image¶
System images are images used only for appliance VMs but not for user VMs. This is normally used for virtual router image in this ZStack version.
Format¶
Format exhibits relationships between hypervisors and images. For example, images of format qcow2 can only be used for VMs of KVM. In this ZStack version, as KVM is the only supported hypervisor, the relationship table is like:
Hypervisor Type | Format |
---|---|
KVM |
|
Volumes will inherit formats of images from which they are created; for example, root volumes created from images of format qcow2 will have format qcow2 too. Format ‘raw’ is an exception, volumes created from ‘raw’ images will have the format qcow2 because ZStack will thin-clone it using qcow2 format.
Backup Storage Reference¶
An image can be stored on more than one backup storage. For every backup storage, the image has a backup storage reference encompassing backup storage UUID and image’s installation path.
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
imageUuid | image uuid | 0.6 | ||
backupStorageUuid | backup storage uuid, see backup storage | 0.6 | ||
installPath | installation path on backup storage | 0.6 | ||
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Example¶
{
"backupStorageUuid": "8b99641a4d644820932e0ec5ada78eed",
"imageUuid": "b395386bdb4a4ff1b1850a457c949c5e",
"installPath": "/export/backupStorage/sftp/templates/acct-36c27e8ff05c4780bf6d2fa65700f22e/b395386bdb4a4ff1b1850a457c949c5e/centos_400m_140925.template",
"createDate": "Jun 1, 2015 6:17:48 PM",
"lastOpDate": "Jun 1, 2015 6:17:48 PM"
}
Operations¶
Add Image¶
Admins can use AddImage to add an image. For example:
AddImage name=CentOS7 format=qcow2 backupStorageUuids=8b99641a4d644820932e0ec5ada78eed url=http://172.16.0.220/templates/centos7_400m_140925.img mediaType=RootVolumeTemplate platform=Linux
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
url | HTTP/HTTPS url, see url | 0.6 | ||
mediaType | image media type, see media type. Default is RootVolumeTemplate | true |
|
0.6 |
guestOsType | a string that indicates VM’s operating system type, for example, CentOS7 | true | 0.6 | |
system | indicates whether this is a system image, see system image. Default is false | true |
|
0.6 |
format | image format, see format |
|
0.6 | |
platform | image platform, see platform. Default is Linux | true |
|
0.6 |
backupStorageUuids | a list of backup storage uuid to which the image is going to add | 0.6 | ||
type | reserved field, leave it alone | true |
|
0.6 |
An image can be added to multiple backup storage by providing a list of backup storage UUID in ‘backupStorageUuids’; The AddImage command succeeds as long as the image is successfully added to one backup storage, and fails if the image fails on all backup storage. Backup storage that successfully added the image can be retrieved from image backup storage reference of the image inventory in the API response.
Delete Image¶
Admins can use DeleteImage to delete an image from specified backup storage or all backup storage. For example:
DeleteImage uuid=b395386bdb4a4ff1b1850a457c949c5e backupStorageUuids=c310386bdb4a4ff1b1850a457c949c5e,f295386bdb4a4ff1b1850a457c949c5e
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | image uuid | 0.6 | ||
deleteMode | see Delete Resources | true |
|
0.6 |
backupStorageUuids | a list of backup storage storing the image; if omitted, the image will be deleted from all backup storage it’s on. | 0.6 |
An image is considered as deleted only if it is deleted from all backup storage; otherwise, its copy get deleted on some specific backup storage.
Danger
There is no way to recover an image if it has been deleted from all backup storage.
Change State¶
Admins can use ChangeImageState to change the state of an image. For example:
ChangeImageState stateEvent=enable uuid=b395386bdb4a4ff1b1850a457c949c5e
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | image uuid | 0.6 | ||
stateEvent | state trigger event
|
|
0.6 |
Create RootVolumeTemplate From Root Volume¶
Users can create an RootVolumeTemplate image from a root volume. For example:
CreateRootVolumeTemplateFromRootVolume name=CentOS7 rootVolumeUuid=1ab2386bdb4a4ff1b1850a457c949c5e backupStorageUuids=backupStorageUuids,f295386bdb4a4ff1b1850a457c949c5e
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
backupStorageUuids | a list of backup storage uuid on which the image is going to created, see backup storage uuids | true | 0.6 | |
rootVolumeUuid | uuid of root volume from which the image is going to create | 0.6 | ||
platform | image platform, see platform; default to Linux | true |
|
0.6 |
guestOsType | a string that indicates VM’s operating system type, for example, CentOS7 | true | 0.6 | |
system | indicates whether this is system image, see system image; default to false | true |
|
0.6 |
Backup Storage UUIDs¶
When calling CreateRootVolumeTemplateFromRootVolume, users can provide a list of backup storage UUIDs to specify where the image is going to create; if this field is omitted, a random backup storage will be chosen.
Create RootVolumeTemplate From Volume Snapshot¶
Users can use CreateRootVolumeTemplateFromVolumeSnapshot to create a RootVolumeTemplate from a volume snapshot. For example:
CreateRootVolumeTemplateFromVolumeSnapshot name=CentOS7 snapshotUuid=1ab2386bdb4a4ff1b1850a457c949c5e
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
snapshotUuid | uuid of volume snapshot, see volume snapshot | 0.6 | ||
backupStorageUuids | a list of backup storage uuid on which the image is going to created, see backup storage uuids | true | 0.6 | |
platform | image platform, see platform. Default to Linux | true |
|
0.6 |
guestOsType | a string that indicates VM’s operating system type, for example, CentOS7 | true | 0.6 | |
system | indicates whether this is system image, see system image. Default is false | true |
|
0.6 |
Backup Storage Uuids¶
When calling CreateRootVolumeTemplateFromVolumeSnapshot, users can provide a list of backup storage UUIDs to specify where the image is going to create; if this field is omitted, a random backup storage will be chosen.
Create DataVolumeTemplate From Volume¶
Users can use CreateDataVolumeTemplateFromVolume to create a DataVolumeTemplate from a volume. For example:
CreateDataVolumeTemplateFromVolume name=data volumeUuid=1ab2386bdb4a4ff1b1850a457c949c5e
The volume can be either root volume or data volume. This provides a way to create a data volume from a root volume. Users can firstly create a DataVolumeTemplate from a root volume, then create a data volume from the DataVolumeTemplate.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
volumeUuid | uuid of volume, see volume | 0.6 | ||
backupStorageUuids | a list of backup storage uuid on which the image is going to created, see backup storage uuids | true | 0.6 |
Backup Storage Uuids¶
When calling CreateDataVolumeTemplateFromVolume, users can provide a list of backup storage UUIDs to specify where the image is going to create; if this field is omitted, a random backup storage will be chosen.
Query Image¶
Users can use QueryImage to query images. For example:
QueryImage status=Ready system=true
QueryImage volume.vmInstanceUuid=85ab231e392d4dfb86510191278e9fc3
Nested And Expanded Fields of Query¶
Field | Inventory | Description | Since |
---|---|---|---|
backupStorage | backup storage inventory | backup storage this image is on | 0.6 |
volume | volume inventory | volumes created from this image | 0.6 |
backupStorageRef | backup storage reference | reference used to query by backup storage install path | 0.6 |