shwstppr commented on a change in pull request #84: [WIP DO NOT MERGE] VM ingestion URL: https://github.com/apache/cloudstack-documentation/pull/84#discussion_r366831302
########## File path: source/adminguide/virtual_machines/VM_Ingestion.rst ########## @@ -0,0 +1,321 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information# + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + 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 unamged VMs so that they become CloudStack managed guest instances + +.. note:: This is currently only available for **vSphere** clusters. + + +Use Cases and General Usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ability to import VMs allows Cloud operators (both public and private) on onboard new tenants simply and quickly, +with the minimum amount disk IO. But also can be used in disaster recovery scenarios at remote sites (if storage is +replicated) and in the recreation of VMs which have been backed up (part of the code is indeed used in +CloudStack's Backup and Recovery feature). + +The most complex part of importing VMs is the mapping of an unmanaged VM's networks to CloudStack networks. As an operator +could be importing tens or even hundreds of VMs, a UI for this feature has not been created as yet. + +If the 'destination' network VLAN(s) and the requested service offerings match the existing VM, then the instance can be +imported whilst it is running. If the VLANs or service offerings do not match, then the instance to be imported must be stopped. +Once the instance has been added to CloudStack, starting it through CloudStack will alter the instances settings in line with +those set in the CloudStack DB. + +To import instances, it is imagined that a Cloud Provider will: + +#. List all of the existing networks which the instances to be imported are on. +#. Create corresponding networks in CloudStack +#. Use the listUnmanagedInstances API to create a CSV of instances to be imported. +#. Where required, add metadata to the CSV such as the Account into which each VM is to associated, the network which each VM is to be + attached to, the Compute Offering required for each instance, and the Disk Offering for each disk +#. Create a script that will loop through the CSV, sending the importUnmanagedInstance API command with the corresponding + parameters for each instance being read from the CSV + +listUnmanagedInstances API +-------------------------- + +Prerequisites to list unmanaged instances (vSphere) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order for CloudStack to list the instances that are not managed by CloudStack on a host/cluster, the host(s) in the vSphere cluster +must have been added to CloudStack. The standard prerequisites for adding a host to CloudStack apply. + +API +~~~ + +This API will list all unmanaged VMs for a given cluster. Optionally, the vSphere name for an existing unmanaged +VM can be given to retrieve VM details. The API will filter all CloudStack managed VMs, and will also filter templates that show up as VMs on vCenter. + +**Request parameters**: + +.. parsed-literal:: + - **clusterid** (CloudStack UUID of cluster) + - **name** (vSphere instance name) + +**Response**: + +.. parsed-literal:: + - **clusterid** + - **hostid** + - **name** + - **osdisplayname** + - **memory** + - **powerstate** + - **cpuCoresPerSocket** + - **cpunumber** + - **cpuspeed** + - **disk** + - **id** + - **capacity** (in bytes) + - **controller** + - **controllerunit** + - **imagepath** + - **position** + - **nic** + - **id** + - **macaddress** + - **networkname** + - **vlanid** + - **pcislot** + - **adaptertype** (when available) + - **ipaddress** (Only returned when VMware tools are running on instance) + + +Importing Unmanaged Instances +------------------------------ + +importUnmanagedInstance API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Request parameters**: + +.. parsed-literal:: + - **clusterid** (CloudStack UUID of cluster) + - **name** (vSphere instance name) + - **displayname** + - **hostname** + - **account** (An optional account name for the virtual machine. Must be used with domainid parameter) + - **domainid** (An optional domain ID for the virtual machine. Must be used with account parameter) + - **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) + +**Response**: + +.. parsed-literal:: + Same response as that of deployVirtualMachine API. + + + +Prerequisites to Importing Unmanaged Instances (vSphere) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few prerequisites to importing unmanaged instances into CloudStack. Largely these are simply that the networks which you are going to +attach the instance in CloudStack need to already exist in CloudStack also the storage which an unmanaged instance is on (before importing) and +also the storage which you wish the instance to be on after importing must already have been added to CloudStack. + +VMs can be imported to isolated, shared or L2 networks. VMs can also be imported and then automatically migrated to storage in accordance with +service offerings using the *migrateAllowed* API parameter. Review comment: ```suggestion service offerings using the *migrateallowed* API parameter. ``` ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
