Instance Offering
Overview
An instance offering is the count or specification of the CPU, memory, the host allocation strategy, disk bandwidth, and network bandwidth, for a VM instance.
Inventory
Properties
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| uuid | The UUID. For more information, see Resource Property. | 0.6 | ||
| name | The name. For more information, see Resource Property. | 0.6 | ||
| description | The description. For more information, see Resource Property. | Yes | 0.6 | |
| cpuNum | The number of virtual CPUs (vCPUs). For more information, see CPU Capacity. | 0.6 | ||
| cpuSpeed | The vCPU speed. For more information, see CPU Capacity. | 0.6 | ||
| memorySize | The memory size. Unit: byte. | 0.6 | ||
| type | The instance offering type. Default type: UserVm. For more information, see Type. | Yes |
|
0.6 |
| allocatorStrategy | The host allocator strategy. For more information, see Allocator Strategy. |
|
0.6 | |
| state | The state. For more information, see State. |
|
0.6 | |
| sortKey | 0.6 | |||
| createDate | The creation date. For more information, see Resource Property. | 0.6 | ||
| lastOpDate | The last operation date. For more information, see Resource Property. | 0.6 |
Sample
{
"inventories": [
{
"allocatorStrategy": "LeastVmPreferredHostAllocatorStrategy",
"cpuNum": 1,
"cpuSpeed": 0,
"createDate": "Oct 30, 2017 3:51:50 PM",
"description": "",
"lastOpDate": "Oct 30, 2017 4:49:03 PM",
"memorySize": 1073741824,
"name": "1G-1CPU",
"sortKey": 0,
"state": "Enabled",
"type": "VirtualRouter",
"uuid": "fa550cb9bdcc4fd397ae37f9ddf4c390"
}
],
"success": true
}
CPU Capacity
Instance offerings use cpuNum and cpuSpeed to define the CPU capacity of a VM instance. The cpuNum field means the number of vCPUs that a VM instance has. The vCPU of a VM instance always has the same frequency as that of the host’s physical CPU. Therefore, the cpuSpeed field here actually means the vCPU weight in hypervisors. The use and implementation of cpuSpeed vary depending on hypervisor types.
KVM CPU Speed
In KVM, ZStack Cloud uses the result of shares=cpuSpeed * cpuNum to set the VM instance XML configuration of libvirt.
<cputune>
<shares>128</shares>
</cputune>
shares = cpuNum * cpuSpeed
When cpuSpeed is set to 0, the value of shares is displayed as 2 by default.
Type
The type of instance offering. Currently, two instance offering types are available:
UserVm:
The instance offering for creating user VM instances.
VirtualRouter:
The instance offering for creating virtual router (vRouter) VM instances.
Allocator Strategy
Allocator strategy defines the algorithm of selecting destination hosts for creating VM instances.
DefaultHostAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return randomly_pick_one_host(host_set6)
LastHostPreferredAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return pick_vm_last_host(host_set6)
LeastVmPreferredHostAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return pick_host_with_the_fewest_vm(host_set6)
MinimumMemoryUsageHostAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return pick_host_with_the_lowest_memory_load(host_set6)
MinimumCPUUsageHostAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return pick_host_with_the_lowest_cpu_load(host_set6)
MaxInstancePerHostHostAllocatorStrategy
Algorithm:
l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached\
_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)
return pick_host_with_vm_is_less_than_expected(host_set6)
State
An instance offering has the following two states:
Enabled:
Indicates that VM instances can be created from this instance offering.
Disabled:
Indicates that VM instances cannot be created from this instance offering.
Operations
CreateInstanceOffering
Creates an instance offering. For example,
CreateInstanceOffering name=test cpuNum=1 memorySize=2097152000
Parameters
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| name | The instance offering name. | 0.6 | ||
| description | The detailed description of the instance offering. | Yes | 0.6 | |
| cpuNum | The number of CPUs. | 0.6 | ||
| memorySize | The memory size. Unit: byte. | 0.6 | ||
| allocatorStrategy | The allocator strategy. | Yes |
|
0.6 |
| sortKey | The sort key. | Yes | 0.6 | |
| type | The type. | Yes | 0.6 | |
| resourceUuid | The resource UUID. If specified, the image will use the specified value as UUID. | Yes | 0.6 | |
| userTags | The user tags. For more information, see CreateUserTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| systemTags | The system tags. For more information, see CreateSystemTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| timeout | Yes |
When you create an instance offering in ZStack Cloud, you can add a GPU specification by adding the pciRom option to SystemTags.
- Format of the pciRom option:
pciRomUuid::UUID. Here, the UUID is the UUID of the PCI device firmware. - Example:
pciRomUuid::5fd71606d5af451d981413f35367a8d6
- Format of the pciRom option:
When you create an instance offering in ZStack Cloud, you can customize the instance offering parameters by adding the instanceOfferingUserConfig option to SystemTags.
- Format of the instanceOfferingUserConfig option:
instanceOfferingUserConfig::xxx. Here, xxx must be a JSON string.
- Format of the instanceOfferingUserConfig option:
DeleteInstanceOffering
Deletes an instance offering. For example,
DeleteInstanceOffering uuid=ecf1f40130b148b39f82c07921ee11ff
Parameters
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| uuid | The instance offering UUID. | 0.6 | ||
| deleteMode | The delete mode. For more information, see Delete Resources. | Yes |
|
0.6 |
| userTags | The user tags. For more information, see CreateUserTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| systemTags | The system tags. For more information, see CreateSystemTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| timeout | Yes |
QueryInstanceOffering
Queries an instance offering. For example,
QueryInstanceOffering cpuSpeed=512 cpuNum>2
QueryInstanceOffering vmInstance.state=Stopped
Primitive Fields of Query
See Instance Offering Inventory.
Nested and Expanded Fields of Query
| Field | Inventory | Description | Starting Version |
|---|---|---|---|
| vmInstance | VM Instance Inventory | The VM instances that are created from this instance offering. | 0.6 |
ChangeInstanceOffering
Changes an instance offering. For example,
ChangeInstanceOffering vmInstanceUuid=108af59a0f4e4d6cb838a5591db1016a
instanceOfferingUuid=f1dacd026c7645deaeeaef4e89313c8e
Parameters
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| vmInstanceUuid | The VM instance UUID. | 0.6 | ||
| instanceOfferingUuid | The instance offering UUID. | 0.6 | ||
| userTags | The user tags. For more information, see CreateUserTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| systemTags | The system tags. For more information, see CreateSystemTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| timeout | Yes |
UpdateInstanceOffering
Updates an instance offering. For example,
UpdateInstanceOffering uuid=32190aabcf47470c90b20bd849767a49
Parameters
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| uuid | The instance offering UUID. | 0.6 | ||
| name | The instance offering name. | Yes | 0.6 | |
| description | The detailed description of the instance offering. | Yes | 0.6 | |
| allocatorStrategy | Yes |
|
2.3 | |
| userTags | The user tags. For more information, see CreateUserTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| systemTags | The system tags. For more information, see CreateSystemTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| timeout | Yes |
ChangeInstanceOfferingState
Changes the state of an instance offering. For example,
ChangeInstanceOfferingState stateEvent=enable uuid=32190aabcf47470c90b20bd849767a49
Parameters
| Name | Description | Optional | Valid Value | Starting Version |
|---|---|---|---|---|
| uuid | The instance offering UUID. | 0.6 | ||
| stateEvent | The state event. |
|
0.6 | |
| userTags | The user tags. For more information, see CreateUserTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| systemTags | The system tags. For more information, see CreateSystemTag. The resource type is InstanceOfferingVO. | Yes | 0.6 | |
| timeout | Yes |
Tags
You can create a user tag on an instance offering by using resourceType=InstanceOfferingVO. For example,
CreateUserTag resourceType=InstanceOfferingVO tag=web-server-offering \
resourceUuid=45f909969ce24865b1bbca4adb66710a
System Tags
Dedicated Primary Storage
When you create a VM instance, you can use a system tag to specify the primary storage on which root volumes will be created.
| Tag | Description | Example | Starting Version |
|---|---|---|---|
| primaryStorage::allocator::uuid::{uuid} | If this tag exists, the root volume of the VM instance will be allocated on the primary storage with the specified UUID. If the specified primary storage does not exist, or if the specified primary storage does not have sufficient capacity, an allocation failure will be reported. | primaryStorage::allocator::uuid::b8398e8b7ff24527a3b81dc4bc64d974 | 0.6 |
| primaryStorage::allocator::userTag::{tag}::required | If this tag exists, the root volume of the VM instance will be allocated on the primary storage with the specified user tag. If the primary storage with specified user tag does not exist, or if the specified primary storage does not have sufficient capacity, an allocation failure will be reported. | primaryStorage::allocator::userTag::SSD::required | 0.6 |
| primaryStorage::allocator::userTag::{tag} | If this tag exists, the root volume of the VM instance will be allocated on the primary storage with the specified user tag. If the primary storage with specified user tag does not exist, or if the specified primary storage does not have sufficient capacity, ZStack Cloud will choose a random primary storage to allocate the root volume. | primaryStorage::allocator::userTag::SSD | 0.6 |
If more than one system tag mentioned above exists on an instance offering, the precedent order is as follows:
primaryStorage::allocator::uuid::{uuid} > primaryStorage::allocator::userTag::{tag}::\
required > primaryStorage::allocator::userTag::{tag}
