Apache CloudStack 4.23.0.0 Root Admin API Reference
updateVirtualMachine
Updates properties of an Instance. The Instance has to be stopped and restarted for the new properties to take effect. UpdateVirtualMachine does not first check whether the Instance is stopped. Therefore, stop the Instance manually before issuing this call.
Request parameters
| Parameter Name | Description | Required |
| id | The ID of the Instance | true |
| cleanupdetails | Optional boolean field, which indicates if details should be cleaned up or not (if set to true, details removed for this resource, details field ignored; if false or not set, no action) | false |
| cleanupextraconfig | Optional boolean field, which indicates if extraconfig for the instance should be cleaned up or not (If set to true, extraconfig removed for this instance, extraconfig field ignored; if false or not set, no action) | false |
| customid | An optional field, in case you want to set a custom id to the resource. Allowed to Root Admins only | false |
| deleteprotection | Set delete protection for the virtual machine. If true, the instance will be protected from deletion. Note: If the instance is managed by another service like autoscaling groups or CKS, delete protection will be ignored. | false |
| details | Details in key/value pairs. 'extraconfig' is not allowed to be passed in details. | false |
| dhcpoptionsnetworklist | DHCP options which are passed to the Instance on start up Example: dhcpoptionsnetworklist[0].dhcp:114=url&dhcpoptionsetworklist[0].networkid=networkid&dhcpoptionsetworklist[0].dhcp:66=www.test.com | false |
| displayname | User generated name | false |
| displayvm | An optional field, whether to the display the Instance to the end User or not. | false |
| extraconfig | An optional URL encoded string that can be passed to the Instance upon successful deployment | false |
| group | Group of the Instance | false |
| haenable | True if high-availability is enabled for the Instance, false otherwise | false |
| instancename | Instance name of the User Instance | false |
| isdynamicallyscalable | True if Instance contains XS/VMWare tools in order to support dynamic scaling of Instance cpu/memory. This can be updated only when dynamic scaling is enabled on Template, service offering and the corresponding global setting | false |
| leaseduration | Number of days to lease the instance from now onward. Use -1 to remove the existing lease | false |
| leaseexpiryaction | Lease expiry action, valid values are STOP and DESTROY | false |
| name | New host name of the Instance. The Instance has to be stopped/started for this update to take affect | false |
| ostypeid | The ID of the OS type that best represents this Instance. | false |
| securitygroupids | List of security group ids to be applied on the Instance. | false |
| securitygroupnames | Comma separated list of security groups names that going to be applied to the Instance. Should be passed only when Instance is created from a zone with Basic Network support. Mutually exclusive with securitygroupids parameter | false |
| userdata | An optional binary data that can be sent to the Instance upon a successful deployment. This binary data must be base64 encoded before adding it to the request. Using HTTP GET (via querystring), you can send up to 4KB of data after base64 encoding. Using HTTP POST (via POST body), you can send up to 1MB of data after base64 encoding. You also need to change vm.userdata.max.length value | false |
| userdatadetails | Used to specify the parameters values for the variables in userdata. | false |
| userdataid | The ID of the userdata | false |
Response Tags
| Response Name | Description |
| id | The ID of the Instance |
| account | The Account associated with the Instance |
| alloweddetails | List of allowed Vm details as comma separated string if VM instance settings are read from OVA. |
| arch | CPU arch of the VM |
| autoscalevmgroupid | ID of AutoScale Instance group |
| autoscalevmgroupname | Name of AutoScale Instance group |
| backupofferingid | The ID of the backup offering of the Instance |
| backupofferingname | The name of the backup offering of the Instance |
| backupprovider | The name of the backup provider of the offering attached to the Instance |
| bootmode | Guest Instance Boot Mode |
| boottype | Guest Instance Boot Type |
| cpunumber | The number of vCPUs this Instance is using |
| cpuspeed | The speed of each vCPU |
| cpuused | The amount of the Instance's CPU currently used |
| created | The date when this Instance was created |
| deleteprotection | true if vm has delete protection. |
| details | Instance details in key/value pairs. |
| diskioread | The read (IO) of disk on the Instance |
| diskiowrite | The write (IO) of disk on the Instance |
| diskkbsread | The Instance's disk read in KiB |
| diskkbswrite | The Instance's disk write in KiB |
| diskofferingid | The ID of the disk offering of the Instance. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead |
| diskofferingname | The name of the disk offering of the Instance. This parameter should not be used for retrieving disk offering details of DATA volumes. Use listVolumes API instead |
| displayname | User generated name. The name of the Instance is returned if no displayname exists. |
| displayvm | An optional field whether to the display the Instance to the end user or not. |
| domain | The name of the domain in which the Instance exists |
| domainid | The ID of the domain in which the Instance exists |
| domainpath | Path of the domain in which the virtual machine exists |
| forvirtualnetwork | The virtual Network for the service offering |
| gpucardid | the ID of the gpu card to which service offering is linked |
| gpucardname | the name of the gpu card to which service offering is linked |
| gpucount | the count of GPUs on the virtual machine |
| group | The group name of the Instance |
| groupid | The group ID of the Instance |
| guestosid | OS type ID of the Instance |
| haenable | True if high-availability is enabled, false otherwise |
| hostcontrolstate | The control state of the host for the Instance |
| hostid | The ID of the host for the Instance |
| hostname | The name of the host for the Instance |
| hypervisor | The hypervisor on which the Template runs |
| icon | Base64 string representation of the resource icon |
| instancename | Instance name of the user Instance; this parameter is returned to the ROOT admin only |
| ipaddress | the VM's primary IP address |
| isdynamicallyscalable | True if Instance contains XS/VMWare tools in order to support dynamic scaling of Instance CPU/memory. |
| isodisplaytext | An alternate display text of the ISO attached to the Instance |
| isoid | The ID of the ISO attached to the Instance |
| isomaxcount | Maximum number of ISOs that may be attached to this Instance, after applying the cluster-scoped vm.iso.max.count and the hypervisor's own cap. |
| isoname | The name of the ISO attached to the Instance |
| keypairs | SSH key-pairs |
| lastupdated | The date when this Instance was updated last time |
| leaseduration | Instance lease duration in days |
| leaseexpiryaction | Instance lease expiry action |
| leaseexpirydate | Instance lease expiry date |
| maxheads | the maximum number of display heads |
| maxresolutionx | the maximum X resolution |
| maxresolutiony | the maximum Y resolution |
| memory | The memory allocated for the Instance |
| memoryintfreekbs | The internal memory (KiB) that's free in Instance or zero if it can not be calculated |
| memorykbs | The memory used by the Instance in KiB |
| memorytargetkbs | The target memory in Instance (KiB) |
| name | The name of the Instance |
| networkkbsread | The incoming Network traffic on the Instance in KiB |
| networkkbswrite | The outgoing Network traffic on the host in KiB |
| osdisplayname | OS name of the Instance |
| ostypeid | OS type id of the Instance |
| password | The password (if exists) of the Instance |
| passwordenabled | True if the password rest feature is enabled, false otherwise |
| pooltype | The pool type of the Instance |
| project | The project name of the Instance |
| projectid | The project ID of the Instance |
| publicip | Public IP address id associated with Instance via Static NAT rule |
| publicipid | Public IP address id associated with Instance via Static NAT rule |
| readonlydetails | List of read-only Instance details as comma separated string. |
| receivedbytes | The total number of Network traffic bytes received |
| rootdeviceid | Device ID of the root volume |
| rootdevicetype | Device type of the root volume |
| sentbytes | The total number of Network traffic bytes sent |
| serviceofferingid | The ID of the service offering of the Instance |
| serviceofferingname | The name of the service offering of the Instance |
| servicestate | State of the Service from LB rule |
| state | The state of the Instance |
| templatedisplaytext | An alternate display text of the Template for the Instance |
| templateformat | The format of the template for the virtual machine |
| templateid | The ID of the Template for the Instance. A -1 is returned if the Instance was created from an ISO file. |
| templatename | The name of the Template for the Instance |
| templatetype | The type of the template for the virtual machine |
| userdata | Base64 string containing the user data |
| userdatadetails | List of variables and values for the variables declared in userdata |
| userdataid | The ID of userdata used for the Instance |
| userdataname | The name of userdata used for the Instance |
| userdatapolicy | The userdata override policy with the userdata provided while deploying Instance |
| userid | The User's ID who deployed the Instance |
| username | The User's name who deployed the Instance |
| vgpu | The vGPU type used by the Instance |
| vgpuprofileid | the ID of the vgpu profile to which service offering is linked |
| vgpuprofilename | the name of the vgpu profile to which service offering is linked |
| videoram | the video RAM size in MB |
| vmtype | User VM type |
| vnfdetails | VNF details |
| vnfnics | NICs of the VNF appliance |
| zoneid | The ID of the availability zone for the Instance |
| zonename | The name of the availability zone for the Instance |
| affinitygroup(*) | List of Affinity groups associated with the Instance |
| id | The ID of the affinity group |
| account | The account owning the affinity group |
| dedicatedresources | dedicated resources associated with this affinity group |
| description | The description of the affinity group |
| domain | The domain name of the affinity group |
| domainid | The domain ID of the affinity group |
| domainpath | path of the Domain the affinity group belongs to |
| name | The name of the affinity group |
| project | The project name of the affinity group |
| projectid | The project ID of the affinity group |
| type | The type of the affinity group |
| virtualmachineIds | Instance IDs associated with this affinity group |
| isos(*) | All ISOs attached to the Instance, keyed by cdrom slot. The first entry mirrors isoid/isoname for back-compat. |
| id | The ID of the attached ISO |
| bootable | Whether this is the bootable ISO for the VM |
| deviceseq | The cdrom slot that holds this ISO (3=hdc, 4=hdd, ...) |
| displaytext | The display text of the attached ISO |
| name | The name of the attached ISO |
| nic(*) | The list of NICs associated with Instance |
| id | The ID of the NIC |
| adaptertype | Type of adapter if available |
| broadcasturi | The broadcast URI of the NIC |
| deviceid | Device ID for the Network when plugged into the Instance |
| enabled | whether the NIC is enabled or not |
| extradhcpoption | The extra DHCP options on the NIC |
| gateway | The gateway of the NIC |
| ip6address | The IPv6 address of Network |
| ip6cidr | The CIDR of IPv6 Network |
| ip6gateway | The gateway of IPv6 Network |
| ipaddress | The IP address of the NIC |
| ipaddresses | IP addresses associated with NIC found for unmanaged Instance |
| isdefault | True if NIC is default, false otherwise |
| isolatedpvlan | The isolated private VLAN if available |
| isolatedpvlantype | The isolated private VLAN type if available |
| isolationuri | The isolation URI of the NIC |
| macaddress | True if NIC is default, false otherwise |
| mtu | MTU configured on the NIC |
| netmask | The netmask of the NIC |
| networkid | The ID of the corresponding Network |
| networkname | The name of the corresponding Network |
| nicdnsname | DNS name associated with this NIC's IP address |
| nsxlogicalswitch | Id of the NSX Logical Switch (if NSX based), null otherwise |
| nsxlogicalswitchport | Id of the NSX Logical Switch Port (if NSX based), null otherwise |
| publicip | Public IP address associated with this NIC via Static NAT rule |
| publicipid | Public IP address ID associated with this NIC via Static NAT rule |
| secondaryip | The Secondary IPv4 addr of NIC |
| traffictype | The traffic type of the NIC |
| type | The type of the NIC |
| virtualmachineid | Id of the Instance to which the NIC belongs |
| vlanid | ID of the VLAN/VNI if available |
| vpcid | ID of the VPC to which the NIC belongs |
| vpcname | Name of the VPC to which the NIC belongs |
| securitygroup(*) | List of security groups associated with the Instance |
| id | The ID of the security group |
| account | The Account owning the security group |
| description | The description of the security group |
| domain | The domain name of the security group |
| domainid | The domain ID of the security group |
| domainpath | path of the Domain the security group belongs to |
| name | The name of the security group |
| project | The project name of the group |
| projectid | The project id of the group |
| virtualmachinecount | The number of Instances associated with this Security Group |
| virtualmachineids | The list of Instance IDs associated with this Security Group |
| egressrule(*) | The list of egress rules associated with the security group |
| account | Account owning the security group rule |
| cidr | The CIDR notation for the base IP address of the security group rule |
| endport | The ending IP of the security group rule |
| icmpcode | The code for the ICMP message response |
| icmptype | The type of the ICMP message response |
| protocol | The protocol of the security group rule |
| ruleid | The ID of the security group rule |
| securitygroupname | Security group name |
| startport | The starting IP of the security group rule |
| tags(*) | The list of resource tags associated with the rule |
| ingressrule(*) | The list of ingress rules associated with the security group |
| account | Account owning the security group rule |
| cidr | The CIDR notation for the base IP address of the security group rule |
| endport | The ending IP of the security group rule |
| icmpcode | The code for the ICMP message response |
| icmptype | The type of the ICMP message response |
| protocol | The protocol of the security group rule |
| ruleid | The ID of the security group rule |
| securitygroupname | Security group name |
| startport | The starting IP of the security group rule |
| tags(*) | The list of resource tags associated with the rule |
| tags(*) | The list of resource tags associated with the rule |
| account | The Account associated with the tag |
| customer | Customer associated with the tag |
| domain | The domain associated with the tag |
| domainid | The ID of the domain associated with the tag |
| domainpath | Path of the Domain associated with the tag |
| key | Tag key name |
| project | The project name where tag belongs to |
| projectid | The project ID the tag belongs to |
| resourceid | ID of the resource |
| resourcetype | Resource type |
| value | Tag value |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |
| jobid | the ID of the latest async job acting on this object |
| jobstatus | the current status of the latest async job acting on this object |