Resource Center


Overview

A VM instance is a virtual machine instance running on a host. A VM instance has its own IP address to access a public network and run application services. VM instances are core components of ZStack Cloud.


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
zoneUuid The zone UUID. For more information, see Zone and Location. Yes 0.6
clusterUuid The cluster UUID. For more information, see Cluster and Location. Yes 0.6
hostUuid The UUID of the host on which the VM instance is running. For more information, see Host and Location. Yes 0.6
lastHostUuid The UUID of the host on which the VM instance was running last time. For more information, see Host and Location. Yes 0.6
imageUuid The UUID of the image from which the root volume of the VM instance is created. For more information, see Image. 0.6
instanceOfferingUuid The instance offering UUID. For more information, see Instance Offering. 0.6
rootVolumeUuid The root volume UUID of a VM instance. For more information, see Volume. 0.6
defaultL3NetworkUuid The default L3 network UUID of a VM instance. For more information, see L3 Network and Networks. 0.6
cpuSpeed The speed of the virtual CPU (vCPU). For more information, see CPU Capacity. 0.6
cpuNum The CPU count of the VM instance (the vCPU count). For more information, see CPU Capacity. 0.6
allocatorStrategy The host allocator strategy. For more information, see Allocator Strategy.
  • DefaultHostAllocatorStrategy
  • LastHostPreferredAllocatorStrategy
  • LeastVmPreferredHostAllocatorStrategy
  • MinimumCPUUsageHostAllocatorStrategy
  • MinimumMemoryUsageHostAllocatorStrategy
  • MaxInstancePerHostHostAllocatorStrategy
0.6
type

The VM instance type.

  • UserVm: The VM instance created by users.
  • ApplianceVm: The VM instance created by ZStack Cloud to help manage the cloud.
  • UserVm
  • ApplianceVm
0.6
hypervisorType The hypervisor type of the VM instance. For more information, see Host and Hypervisor Type.
  • KVM
0.6
state The VM instance state. For more information, see State.
  • Created
  • Starting
  • Running
  • Stopping
  • Stopped
  • Rebooting
  • Destroying
  • Destroyed
  • Migrating
  • Expunging
  • Pausing
  • Paused
  • Resuming
  • VolumeMigrating
  • Unknown
0.6
vmNics The NICs of the VM instance. For more information, see NIC Inventory. 0.6
allVolumes The volumes of the VM instance. For more information, see Volume Inventory. 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":  {
            "agentPort": 7272,
            "allVolumes": [
                {
                    "actualSize": 293641216,
                    "createDate": "Oct 30, 2017 10:37:51 AM",
                    "description": "Root volume for VM[uuid:0f7730d25fff413d9ab42c174722c9d8]",
                    "deviceId": 0,
                    "format": "qcow2",
                    "installPath": "/Cloud_ps/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-1f9\
19d46bd7a43689b6401bf82b3e190/1f919d46bd7a43689b6401bf82b3e190.qcow2",
                    "isShareable": false,
                    "lastOpDate": "Oct 30, 2017 10:37:51 AM",
                    "name": "ROOT-for-vrouter.l3.The private network of the private cloud.ac5c7e",
                    "primaryStorageUuid": "2376c2874ae34e95a2309fa3453c547d",
                    "rootImageUuid": "bca9ad917cf3178281f27bc64d2dc96b",
                    "size": 8589934592,
                    "state": "Enabled",
                    "status": "Ready",
                    "type": "Root",
                    "uuid": "1f919d46bd7a43689b6401bf82b3e190",
                    "vmInstanceUuid": "0f7730d25fff413d9ab42c174722c9d8"
                }
            ],
            "allocatorStrategy": "LeastVmPreferredHostAllocatorStrategy",
            "applianceVmType": "vrouter",
            "clusterUuid": "175a8917ee794b849e4e96f0b680b717",
            "cpuNum": 2,
            "cpuSpeed": 0,
            "createDate": "Oct 30, 2017 10:37:51 AM",
            "defaultRouteL3NetworkUuid": "e315b2cb6151454bbab362a6e92909e7",
            "hostUuid": "232a730a0c9f4280803a8b0eddfebd77",
            "hypervisorType": "KVM",
            "imageUuid": "bca9ad917cf3178281f27bc64d2dc96b",
            "instanceOfferingUuid": "03a0a2b129f547b5bcb0745db8333390",
            "lastHostUuid": "232a730a0c9f4280803a8b0eddfebd77",
            "lastOpDate": "Oct 30, 2017 7:34:35 PM",
            "managementNetworkUuid": "e315b2cb6151454bbab362a6e92909e7",
            "memorySize": 2147483648,
            "name": "vrouter.l3.The private network of the private cloud.ac5c7e",
            "platform": "Linux",
            "publicNetworkUuid": "e315b2cb6151454bbab362a6e92909e7",
            "rootVolumeUuid": "1f919d46bd7a43689b6401bf82b3e190",
            "state": "Running",
            "status": "Connected",
            "type": "ApplianceVm",
            "uuid": "0f7730d25fff413d9ab42c174722c9d8",
            "vmNics": [
                {
                    "createDate": "Oct 30, 2017 10:37:51 AM",
                    "deviceId": 0,
                    "gateway": "10.0.0.1",
                    "ip": "10.58.22.43",
                    "l3NetworkUuid": "e315b2cb6151454bbab362a6e92909e7",
                    "lastOpDate": "Oct 30, 2017 10:37:51 AM",
                    "mac": "fa:08:2b:92:42:00",
                    "metaData": "3",
                    "netmask": "255.0.0.0",
                    "uuid": "bf1d8e2848fd48e39e71c9f859a2158b",
                    "vmInstanceUuid": "0f7730d25fff413d9ab42c174722c9d8"
                }
            ],
            "zoneUuid": "12489c7dce2b4e73811da4a1d38b53dc"
        }
}

Location

ZStack Cloud arranges compute resources through zones, clusters, and hosts. Therefore, the location of a VM instance can be identified according to the zoneUuid, clusterUuid, and hostUuid.
  • When a VM instance is running, these UUIDs will be set to values that represent the current location of the VM instance.
  • After a VM instance is stopped, hostUuid will be set to NULL, while zoneUuid and clusterUuid will remain unchanged.
  • The lastHostUuid parameter is special, as it represents the host on which the VM instance was running last time.
  • For newly created VM instances, lastHostUuid is set to NULL.
  • Once a VM instance is stopped, lastHostUuid is set to the previous value of lastHostUuid.

Networks

A VM instance can have one or more L3 networks. The VM NIC Inventory section lists the IP address, netmask, MAC address, and other information about each L3 network.
  • If a VM instance has more than one L3 network, you must set a default L3 network for this VM instance. The default L3 network provides default route, DNS, and hostname.
  • If a VM instance has only one L3 network, this one automatically becomes the default L3 network.
The following example helps you understand what a default L3 network is. Suppose you have a user VM instance, as shown in Figure 1.
Figure 1. User VM Instance


As shown in the figure above, the VM instance has three L3 networks, all of which provide the Source Network Address Translation (SNAT) service. The default L3 network is 10.10.1.0/24.
CIDR: 10.10.1.0/24
Gateway: 10.10.1.1
DNS domain: web.tier.mycompany.com
Then, the routing table of the VM instance would be as follows:
default via 10.10.1.1 dev eth0
10.10.1.0/24 dev eth0  proto kernel  scope link  src 10.10.1.99
192.168.0.0/24 dev eth1  proto kernel  scope link  src 192.168.0.10
172.16.0.0/24 dev eth2  proto kernel  scope link  src 172.16.0.55
As you can see, the default route points to 10.10.1.1, which is the gateway of the default L3 network. Meanwhile, the /etc/resolv.conf of the VM instance is as follows:
search web.tier.mycompany.com
nameserver 10.10.1.1
That is, the DNS domain is also from the default L3 network. In addition, the DNS name server is also set to the gateway 10.10.1.1 because the default L3 network provides a DNS server. Then, the Full Qualified Domain Name (FQDN) of the VM instance would be as follows:
vm2.web.tier.mycompany.com

FQDN is an extension of the DNS domain.

VM NIC Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 0.6
vmInstanceUuid The UUID of the parent VM instance. 0.6
l3NetworkUuid The UUID of the L3 network to which the NIC is attached. 0.6
ip The IP address. 0.6
mac The MAC address. 0.6
hypervisorType The hypervisor type. 0.6
netmask The netmask. 0.6
gateway The gateway. 0.6
metaData The reserved field for internal use. Yes 0.6
deviceId The device ID, which is an integer that indicates the order of NICs in the Ethernet device of the guest operating system. For example, 0 usually means eth0, and 1 usually means eth1. 0.6
usedIps 0.6
ipVersion The IP version. 0.6

Sample

{
    "inventories": [
        {
            "createDate": "Sep 1, 2021 1:19:41 PM",
            "deviceId": 0,
            "driverType": "virtio",
            "gateway": "10.34.0.1",
            "hypervisorType": "KVM",
            "internalName": "vnic7.0",
            "ip": "10.34.0.199",
            "l3NetworkUuid": "fa7ae74a3bc64532b672bcdac820c3c6",
            "lastOpDate": "Sep 1, 2021 1:19:41 PM",
            "mac": "fa:4e:29:d7:6e:00",
            "netmask": "255.255.255.0",
            "type": "VNIC",
            "usedIps": [
                {
                    "createDate": "Sep 1, 2021 1:19:41 PM",
                    "gateway": "10.34.0.1",
                    "ip": "10.34.0.199",
                    "ipInLong": 170000583,
                    "ipRangeUuid": "e04aea52053443de9bb7b82af8233303",
                    "ipVersion": 4,
                    "l3NetworkUuid": "fa7ae74a3bc64532b672bcdac820c3c6",
                    "lastOpDate": "Sep 1, 2021 1:19:41 PM",
                    "netmask": "255.255.255.0",
                    "uuid": "0a678264c3d338358a6c1615d808a8e4",
                    "vmNicUuid": "2e1d6026e32e402ca1d3db5119940f29"
                }
            ],
            "uuid": "2e1d6026e32e402ca1d3db5119940f29",
            "vmInstanceUuid": "8049b3be8efb46c6aa143236d184c843"
        }
    ],
    "success": true
}

Volume

The allVolumes field is a list of volumes, including root volumes and data volumes. To find the root volumes, you can iterate the list by checking the volume type or by using the rootVolumeUuid field to match the volume UUID. A root volume will be always with the VM instance until the VM instance is destroyed.

Hypervisor Type

The hypervisor type of a VM instance might be inherited from the hypervisor type of an image or a host. This depends on how the VM instance is created.
  • For a VM instance that is created from RootVolumeTemplate:

    Images already have operating system installed. Therefore, the VM instance will be created on a host with the same hypervisor type as the VM instance image. In this case, the hypervisor type of the VM instance is inherited from image.

  • For a VM instance that is created from ISO:

    ISO is used to install the operating system on a blank root volume of the VM instance. Therefore, the VM instance might be created on a host of any hypervisor type. In this case, the hypervisor type of the VM instance is inherited from host.

State

A VM instance has the following states during its lifecycle:
  • Created

    Indicates that the VM instance is just created as a record in the database and is not started on any host. This state only exists when you create a new VM instance.

  • Starting

    Indicates that the VM instance is being started on a host.

  • Running

    Indicates that the VM instance is running on a host.

  • Stopping

    Indicates that the VM instance is being stopped on a host.

  • Stopped

    Indicates that the VM instance is stopped and is not running on any host.

  • Rebooting

    Indicates that the VM instance is being rebooted on the host where the VM instance was running last time.

  • Destroying

    Indicates that the VM instance is being deleted.

  • Destroyed

    Indicates that the VM instance is deleted

  • Migrating

    Indicates that the VM instance is being migrated to the other host.

  • Expunging

    Indicates that the database of the VM instance is being deleted.

  • Pausing

    Indicates that the VM instance is being paused on a host.

  • Paused

    Indicates that the VM instance is paused.

  • Resuming

    Indicates that the VM instance is being resumed from the Paused state to the Running state.

  • VolumeMigrating

    Indicates that the root volume of the VM instance is being migrated from local storage to the other host.

  • Unknown

    Indicates that ZStack Cloud fails to detect the state due to reasons such as losing disconnection to the host.

The state transition diagram of a VM instance is shown in Figure 2.
Figure 2. VM Instance State Transition Diagram


ZStack Cloud uses VM Tracer to periodically track the state of VM instances. The default interval is 60 seconds. The state of a VM instance might be affected by factors outside ZStack Cloud.
  • For example, the power outage of a host will cause all VM instances running on the host to stop running. Once VM Tracer detects a mismatch between the actual state of a VM instance and the recorded state in the database, VM Tracer will update the database to catch up with the actual state.
  • If VM Tracer fails to check the state of a VM instance due to reasons such as disconnection between the management node and the host, VM Tracer will set the state of the VM instance to Unknown. Once VM Tracer successfully detects the VM instance state again, for example, after the management node is reconnected to the host, VM Tracer will update the VM instance to the actual state.

VM CD-ROM Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 3.3.0
name The name. For more information, see Resource Property. 3.3.0
description The description. For more information, see Resource Property. Yes 3.3.0
deviceId The device ID. Yes 3.3.0
isoInstallPath The installation path on the backup storage. 3.3.0
isoUuid The ISO UUID. 3.3.0
vmInstanceUuid The VM instance UUID. 3.3.0
groupBy Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type. Yes 3.3.0
createDate The creation date. For more information, see Resource Property. 3.3.0
lastOpDate The last operation date. For more information, see Resource Property. 3.3.0
userTags The user tags. For more information, see CreateUserTag. Yes 3.3.0
systemTags The system tags. For more information, see CreateSystemTag. Yes 3.3.0
Sample
{
    "inventories": [
        {
            "createDate": "Jan 15, 2019 4:59:25 PM",
            "deviceId": 0,
            "lastOpDate": "Jan 15, 2019 4:59:25 PM",
            "name": "vm-6e243d2edf8443a4968d3878a4fed2a6-cdRom",
            "uuid": "29f6e8c277a94e57bd0b7c627bd65e85",
            "vmInstanceUuid": "6e243d2edf8443a4968d3878a4fed2a6"
        }
    ],
    "success": true
}

VM Priority Configuration Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 3.7.0
accountUuid The account UUID. 3.7.0
cpuShares 3.7.0
level The resource priority. 3.7.0
oomScoreAdj 3.7.0
groupBy Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type. Yes 3.7.0
createDate The creation date. For more information, see Resource Property. 3.7.0
lastOpDate The last operation date. For more information, see Resource Property. 3.7.0
userTags The user tags. For more information, see CreateUserTag. Yes 3.7.0
systemTags The system tags. For more information, see CreateSystemTag. Yes 3.7.0
Sample
{
    "inventories": [
        {
            "cpuShares": 512,
            "createDate": "Oct 16, 2019 9:51:40 AM",
            "lastOpDate": "Oct 16, 2019 9:51:40 AM",
            "level": "Normal",
            "oomScoreAdj": 0,
            "uuid": "b29df0c34e874a1c83033a3cfe61f086"
        },
        {
            "cpuShares": 1024,
            "createDate": "Oct 16, 2019 9:51:40 AM",
            "lastOpDate": "Oct 16, 2019 9:51:40 AM",
            "level": "High",
            "oomScoreAdj": -900,
            "uuid": "c804903064f54e36b3a066be0cd24aef"
        }
    ],
    "success": true
}




































































































































































































































Download

Already filled the basic info? Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

An email with a verification code will be sent to you. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io
ZStack certification training consulting
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Submit successfully.

We'll connect soon.

Thank you for choosing ZStack products and services.

Back to Top