From e4e774fb3e4bfb73862093d75b55f836fe8d0695 Mon Sep 17 00:00:00 2001 From: nvazquez Date: Tue, 16 Jun 2020 10:33:01 -0300 Subject: [PATCH 1/4] Unmanage VMs documentation --- source/adminguide/virtual_machines.rst | 5 ++ .../virtual_machines/VM_Ingestion.rst | 16 ---- .../virtual_machines/unmanage_vms.rst | 81 +++++++++++++++++++ 3 files changed, 86 insertions(+), 16 deletions(-) create mode 100644 source/adminguide/virtual_machines/unmanage_vms.rst diff --git a/source/adminguide/virtual_machines.rst b/source/adminguide/virtual_machines.rst index d6c2c3a912..fd1bd1a752 100644 --- a/source/adminguide/virtual_machines.rst +++ b/source/adminguide/virtual_machines.rst @@ -913,6 +913,11 @@ snapshot: VM snapshots are deleted automatically when a VM is destroyed. You don't have to manually delete the snapshots in this case. +Unmanaging Virtual Machines +=========================== + +.. include:: virtual_machines/unmanage_vms.rst + Importing Virtual Machines =========================== diff --git a/source/adminguide/virtual_machines/VM_Ingestion.rst b/source/adminguide/virtual_machines/VM_Ingestion.rst index 54bf18b29b..7be274f755 100644 --- a/source/adminguide/virtual_machines/VM_Ingestion.rst +++ b/source/adminguide/virtual_machines/VM_Ingestion.rst @@ -13,22 +13,6 @@ specific language governing permissions and limitations under the License. -About Importing VMs --------------------- - -Unmanaged Virtual Machines -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As of ACS 4.14, CloudStack has the concept of **unmanaged** virtual machines. These are virtual machines that are on CloudStack -managed hosts, but that are not in CloudStack's database and therefore CloudStack cannot control (manage) then in any way. Previously, -such VMs could exist, but CloudStack did not 'see' them (their existence *would* be reported in logs as unrecognised VMs). - -From ACS 4.14 onwards, CloudStack is able to list these VMs via the listUnmanagedInstances API command and then import (also known as ingest) -those unmanaged VMs via the importUnmanagedInstance API so that they become CloudStack managed guest instances - -.. note:: This is currently only available for **vSphere** clusters. - - Use Cases and General Usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/adminguide/virtual_machines/unmanage_vms.rst b/source/adminguide/virtual_machines/unmanage_vms.rst new file mode 100644 index 0000000000..41e9181818 --- /dev/null +++ b/source/adminguide/virtual_machines/unmanage_vms.rst @@ -0,0 +1,81 @@ +About Unmanaged Virtual Machines +-------------------------------- + +As of ACS 4.14, CloudStack has the concept of **unmanaged** virtual machines. These are virtual machines that are on CloudStack +managed hosts, but that are not in CloudStack's database and therefore CloudStack cannot control (manage) then in any way. Previously, +such VMs could exist, but CloudStack did not 'see' them (their existence *would* be reported in logs as unrecognised VMs). + +From ACS 4.14 onwards, CloudStack is able to list these VMs via the listUnmanagedInstances API command and then import (also known as ingest) +those unmanaged VMs via the importUnmanagedInstance API so that they become CloudStack managed guest instances + +From ACS 4.15 onwards, administrators are able to unmanage guest virtual machines. + +.. note:: This is currently only available for **vSphere** clusters. + +Unmanaging Virtual Machines via API +----------------------------------- + +Administrators are able to unmanage guest virtual machines from CloudStack. Once unmanaged, CloudStack can no longer monitor, control or administer the provisioning and orchestration related operations on a virtual machine. + +To unmanage a guest virtual machine, an administrator must invoke the unmnageVirtualMachine API passing the ID of the virtual machine to unmanage. The API has the following preconditions: + +- The virtual machine must not be destroyed +- The virtual machine state must be 'Running’ or ‘Stopped’ +- The virtual machine must be a VMware virtual machine + +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 virtual machine volumes +- There is no ISO attached to the virtual machine + +.. note:: This is currently only available for **vSphere** clusters. + + +Preserving unmanaged virtual machine NICS +----------------------------------------- + +The zone setting: unmanage.vm.preserve.nics can be used to preserve virtual machine NICs and its MAC addresses after unmanaging them. If set to true, the virtual machine NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned. + + +Unmanaging virtual machine actions +---------------------------------- + +- Clean up virtual machine 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 addresses remain preserved and therefore cannot be assigned to any new NIC. + +- Clean up virtual machine volumes in the CloudStack database + +- Clean up virtual machine snapshots in the CloudStack database (if any) · Revoke host access to any managed volumes attached to the VM + +- Clean up the virtual machine from the following: + + - Remove the virtual machine from security groups (if any) + + - Remove the virtual machine from instance groups (if any) + + - Remove firewall rules for the virtual machine (if any) + + - Remove forwarding rules for the virtual machine (if any) + + - Remove load balancing rules for the virtual machine (if any) + + - Disable static NAT (if the virtual machine is assigned to it) + + - Remove the virtual machine from affinity groups (if any) + +- Set VM details as removed in the CloudStack database + +- Decrement the account resources count for volumes and virtual machines + +- Generate usage events: + + - For volumes destroyed, with type: ‘VOLUME.DELETE’ + + - For virtual machine snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ + + - For virtual machine NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’ + + - For the virtual machine being unmanaged: stopped and destroyed usage events (similar as the generated usage events when expunging a virtual machine), with types: ‘VM.STOP’ and ‘VM.DESTROY \ No newline at end of file From abad608fdea1095a4808c090d928c3a2d7941d3f Mon Sep 17 00:00:00 2001 From: Nicolas Vazquez Date: Tue, 16 Jun 2020 14:16:23 -0300 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Andrija Panic <45762285+andrijapanicsb@users.noreply.github.com> --- .../adminguide/virtual_machines/unmanage_vms.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/source/adminguide/virtual_machines/unmanage_vms.rst b/source/adminguide/virtual_machines/unmanage_vms.rst index 41e9181818..9cf2c3635c 100644 --- a/source/adminguide/virtual_machines/unmanage_vms.rst +++ b/source/adminguide/virtual_machines/unmanage_vms.rst @@ -17,7 +17,7 @@ Unmanaging Virtual Machines via API Administrators are able to unmanage guest virtual machines from CloudStack. Once unmanaged, CloudStack can no longer monitor, control or administer the provisioning and orchestration related operations on a virtual machine. -To unmanage a guest virtual machine, an administrator must invoke the unmnageVirtualMachine API passing the ID of the virtual machine to unmanage. The API has the following preconditions: +To unmanage a guest virtual machine, an administrator must invoke the unmanageVirtualMachine API passing the ID of the virtual machine to unmanage. The API has the following preconditions: - The virtual machine must not be destroyed - The virtual machine state must be 'Running’ or ‘Stopped’ @@ -31,7 +31,7 @@ The API execution will perform the following pre-checks, failing if they are not .. note:: This is currently only available for **vSphere** clusters. -Preserving unmanaged virtual machine NICS +Preserving unmanaged virtual machine NICs ----------------------------------------- The zone setting: unmanage.vm.preserve.nics can be used to preserve virtual machine NICs and its MAC addresses after unmanaging them. If set to true, the virtual machine NICs (and their MAC addresses) are preserved when unmanaging it. Otherwise, NICs are removed and MAC addresses can be reassigned. @@ -48,7 +48,8 @@ Unmanaging virtual machine actions - Clean up virtual machine volumes in the CloudStack database -- Clean up virtual machine snapshots in the CloudStack database (if any) · Revoke host access to any managed volumes attached to the VM +- Clean up virtual machine snapshots in the CloudStack database (if any) +- Revoke host access to any managed volumes attached to the VM (applicable to managed storage only) - Clean up the virtual machine from the following: @@ -58,7 +59,7 @@ Unmanaging virtual machine actions - Remove firewall rules for the virtual machine (if any) - - Remove forwarding rules for the virtual machine (if any) + - Remove port forwarding rules for the virtual machine (if any) - Remove load balancing rules for the virtual machine (if any) @@ -66,7 +67,7 @@ Unmanaging virtual machine actions - Remove the virtual machine from affinity groups (if any) -- Set VM details as removed in the CloudStack database +- Remove VM details from the CloudStack database - Decrement the account resources count for volumes and virtual machines @@ -74,8 +75,8 @@ Unmanaging virtual machine actions - For volumes destroyed, with type: ‘VOLUME.DELETE’ - - For virtual machine snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ + - For virtual machine snapshots destroyed (if any), with type: ‘VMSNAPSHOT.DELETE’ and 'VMSNAPSHOT.OFF_PRIMARY' - For virtual machine NICs destroyed: with type: ‘NETWORK.OFFERING.REMOVE’ - - For the virtual machine being unmanaged: stopped and destroyed usage events (similar as the generated usage events when expunging a virtual machine), with types: ‘VM.STOP’ and ‘VM.DESTROY \ No newline at end of file + - For the virtual machine being unmanaged: stopped and destroyed usage events (similar to the generated usage events when expunging a virtual machine), with types: ‘VM.STOP’ and ‘VM.DESTROY', unless the VM has been already stopped before being unmanaged and in this case only ‘VM.DESTROY' is generated. From 3caf3d6175c638e9a6e5f2ecbd97fbfc1d0bb70c Mon Sep 17 00:00:00 2001 From: nvazquez Date: Tue, 16 Jun 2020 14:53:11 -0300 Subject: [PATCH 3/4] Update VM ingestion docs --- source/adminguide/virtual_machines/VM_Ingestion.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/VM_Ingestion.rst b/source/adminguide/virtual_machines/VM_Ingestion.rst index 7be274f755..d38e2e3db0 100644 --- a/source/adminguide/virtual_machines/VM_Ingestion.rst +++ b/source/adminguide/virtual_machines/VM_Ingestion.rst @@ -107,12 +107,14 @@ importUnmanagedInstance API - **projectid** - **templateid** - **serviceofferingid** - - **diskofferingid** (UUID of disk offering for root disk) - **nicnetworklist** (Map for NIC ID and corresponding Network UUID) - **nicipaddresslist** (Map for NIC ID and corresponding IP address) - **datadiskofferinglist** (Map for data disk ID and corresponding disk offering UUID) - **details** (Map for VM details) - **migrateallowed** (VM and its volumes are allowed to migrate to different host/storage pool when offering tags conflict with host/storage pool) + - **forced** (True to override existing VM NICS with existing MAC address in case it exists, false by default) + +.. note:: The `forced` parameter is false by default and prevents importing a VM which has a NIC containing a MAC address that has been previously assigned by CloudStack. If it is set to true, the NICs with MAC addresses which already exist in the CloudStack database have the existing MAC addresses reassigned to its NICs. **Response**: From b37ed46e014fcc89f782c6aa89059c87f1e0cba9 Mon Sep 17 00:00:00 2001 From: nvazquez Date: Tue, 16 Jun 2020 14:56:33 -0300 Subject: [PATCH 4/4] Refactor forced param description --- source/adminguide/virtual_machines/VM_Ingestion.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/adminguide/virtual_machines/VM_Ingestion.rst b/source/adminguide/virtual_machines/VM_Ingestion.rst index d38e2e3db0..a1eda3e2c8 100644 --- a/source/adminguide/virtual_machines/VM_Ingestion.rst +++ b/source/adminguide/virtual_machines/VM_Ingestion.rst @@ -112,7 +112,7 @@ importUnmanagedInstance API - **datadiskofferinglist** (Map for data disk ID and corresponding disk offering UUID) - **details** (Map for VM details) - **migrateallowed** (VM and its volumes are allowed to migrate to different host/storage pool when offering tags conflict with host/storage pool) - - **forced** (True to override existing VM NICS with existing MAC address in case it exists, false by default) + - **forced** (If true, a VM is imported despite some of its NIC's MAC addresses being already present) .. note:: The `forced` parameter is false by default and prevents importing a VM which has a NIC containing a MAC address that has been previously assigned by CloudStack. If it is set to true, the NICs with MAC addresses which already exist in the CloudStack database have the existing MAC addresses reassigned to its NICs.