Enable unmanaging of guest instances | CloudStack Feature First Look


This feature allows CloudStack administrators to unmanage guest virtual machines (VMs) from their CloudStack infrastructure. Once unmanaged, CloudStack can no longer monitor, control, or manage provisioning and orchestration related operations on it. This feature is currently supported only on VMware.

An interesting use case of this feature (when used in conjunction with the VM ingestion feature) is being able to move guest VMs from one vCenter to another, by unmanaging it from one zone and then importing it into a different zone. It is also possible to perform any out-of-band operations on the VM (once unmanaged from CloudStack) directly through VMware vSphere.

Whilst unmanaging a guest VM from the CloudStack infrastructure, the process also removes and cleans up resources used by the VM on the CloudStack database and network resources. From CloudStack’s database’s point of view, unmanaging a VM is like expunging one, where records are removed from several different tables where the VM is referenced.

There is, however, a case in which this feature does not remove an associated record from a table – a MAC address from a VM’s NIC can be preserved after unmanaging. This behavior is disabled by default, but it can be enabled with the zone setting ‘unmanage.vm.preserve.nics’. When the setting is enabled the VM’s NICs and their MAC addresses are preserved when unmanaging a VM. Otherwise, NICS are removed and MAC addresses can be reassigned by CloudStack to different VMs.

Unmanaging a VM is possible through a new API available to administrators – ‘unmanageVirtualMachine’ – which requires the UUID of a guest VM as a parameter. The complete list of actions performed when unmanaging a VM is the following:

  • Clean up VM’s NICs and deallocate network resources used, such as IP addresses and DHCP entries on virtual routers.
    • If ‘unmanage.vm.preserve.nics’ = ‘false’ then the NICs are deallocated and removed from CloudStack
    • If ‘unmanage.vm.preserve.nics’ = ‘true’ then the NICs remain allocated and are not removed from the database. The NIC’s MAC address remains in the database and therefore cannot be assigned to any new NIC.
  • Clean up VM volumes in the CloudStack database
  • Clean up VM snapshots in the CloudStack database (if any)
  • Revoke host access to any managed volumes attached to the VM
  • Clean up the VM from the following:
    • Remove the VM from security groups (if any)
    • Remove the VM from instance groups (if any)
    • Remove firewall rules for the VM (if any)
    • Remove port forwarding rules for the VM (if any)
    • Remove load balancing rules for the VM (if any)
    • Disable static NAT (if the VM is assigned to it)
    • Remove the VM from affinity groups (if any)
  • Set VM details to ‘removed’ in the CloudStack database
  • Decrement the account resources count for volumes and VMs
  • Generate usage events:
    • For volumes destroyed, with type: ‘VOLUME.DELETE’
    • For VM snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ and ‘VMSNAPSHOT.OFF_PRIMARY’
    • For VM NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’

For the VM being unmanaged: stopped and destroyed usage events (similar to the usage events generated when expunging a VM), with types: ‘VM.STOP’ and ‘VM.DESTROY’, unless the VM has already been stopped, in which case only the ‘VM.DESTROY’ event is generated.

The ‘unmanageVirtualMachine’ API has the following pre-conditions:

  • The VM must not be destroyed
  • The VM state must be ‘Running’ or ‘Stopped’
  • The VM must be a VMware VM

Assuming these pre-conditions are met, the API execution will perform the following pre-checks, failing if they are not met:

  • There are no volume snapshots associated with any of the VM volumes
  • There is no ISO attached to the VM

An additional check is performed prior to unmanaging a VM from CloudStack: the hypervisor returns checks that the VM exists, searching the VM by its instance name. If it is not found, then the operation fails.

Since the current UI is being replaced by Primate on the next CloudStack release, it is not possible to unmanage a guest VM from the current UI. However, a new button is displayed on the VM view in Primate, along with the allowed actions, enabling administrators to unmanage guest VMs from the UI. This button is displayed when:

  • The VM is running or stopped, and
  • The VM is a VMware VM

The introduction of the zone setting to preserve the VM NICs when unmanaging it makes it necessary to adapt the VM import functionality to this setting. Therefore, a new parameter has been introduced on the ‘importUnmanagedInstances’ API in which a new Boolean parameter was added: ‘forced’. The ‘forced’ parameter is false by default, but if set to true then a VM is imported despite some of its NIC’s MAC addresses being present. This parameter is false by default and prevents the importing of a VM which has a NIC containing a MAC address that has been previously assigned by CloudStack. If it is set to true, NICs with MAC addresses which already exist in the CloudStack database will have the current MAC addresses reassigned to its NICs. Also, the usage events generated when importing unmanaged VMs have been refactored:

  • The usage event with type: ‘VM.IMPORT’ has been replaced by the usage event with type: ‘VM.CREATE’.
  • If the imported VM is powered ON, then the VM import feature generates the usage event with type: ‘VM.START’

This feature will be available as of Apache CloudStack 4.15, which will be an LTS release.