DocsKnowledge BaseAPI Explorer
Documentation›ZCF›ZStack Cloud›Explore more›CLI Command ManualZCF
Document navigation

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
  • UserVm
  • VirtualRouter
 0.6
allocatorStrategy The host allocator strategy. For more information, see Allocator Strategy.
  • DefaultHostAllocatorStrategy
  • LastHostPreferredAllocatorStrategy
  • LeastVmPreferredHostAllocatorStrategy
  • MinimumCPUUsageHostAllocatorStrategy
  • MinimumMemoryUsageHostAllocatorStrategy
  • MaxInstancePerHostHostAllocatorStrategy
 0.6
state The state. For more information, see State.
  • Enabled
  • Disabled
 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
Note: 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
  • DefaultHostAllocatorStrategy
  • LastHostPreferredAllocatorStrategy
  • LeastVmPreferredHostAllocatorStrategy
  • MinimumCPUUsageHostAllocatorStrategy
  • MinimumMemoryUsageHostAllocatorStrategy
  • MaxInstancePerHostHostAllocatorStrategy
 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
Note:
  • 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
  • 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.

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
  • Permissive
  • Enforcing
 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
  • DefaultHostAllocatorStrategy
  • LastHostPreferredAllocatorStrategy
  • LeastVmPreferredHostAllocatorStrategy
  • MinimumCPUUsageHostAllocatorStrategy
  • MinimumMemoryUsageHostAllocatorStrategy
  • MaxInstancePerHostHostAllocatorStrategy
 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.
  • enable
  • disable
 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}
PreviousVM Scheduling PolicyNextDisk Offering
CLI Command Manual | 5.5.30 | ZStack Cloud · ZCF | ZStack Resource Center