Introduction

Purpose

Currently Cloudstack allows to deploy a VM using a single API call. In order to deploy multiple VMs, the same API needs to be called multiple times. Most user scenarios would be handled with this. But there are certain scenarios which depends on already deployed VMs (for e.g. user dispersion/concentration heuristics for placement of new VMs). In some of these scenarios if the VM deployment calls are issued at small intervals or simultaneously then there are chances that the distribution may not happen accurately. In order to solve these issues there is a need to support deployment of VMs in bulk using a single API call. This will allow more accurate placement of VMs compared to calling the API multiple times.

Use case/requirements

• Allow deploying multiple VMs using a single API call with the constraint of dispersing them across clusters/pods.
• Allow specifying cluster and/or pod as additional placement parameters for bulk VM deployment.

References

CLOUDSTACK-9951 - Getting issue details... STATUS

Document History

Glossary

Not supported

• API not available for regular user due to security issues (may lead to resource exhaustion if not used diligently)
• Multiple VM configuration is not supported in a single bulk deployment API call
• VM specific parameters like display name etc. cannot be specified, all such properties will be automatically generated by the system to maintain uniqueness
• Distribution of VM is based on count only and not on any other parameter like CPU/RAM capacity
• Distribution is not based on host (based on cluster OR pod based on the existing global configuration "apply.allocation.algorithm.to.pods")

Open items

None

Quality

In addition to testing the new functionality, regressions needs to be run on all deploy VM scenarios.

Perf/scale

The VM placement computation process will be serialised within the bulk deployment call. This will lead to some amount of delay proportional to the size of deployment. Once the placement for deploying the VM is finalized, remaining steps will be immediately commenced 

Design

The bulk deployment API will internally create multiple deployment jobs (one per VM). Additional contextual information (VMs getting deployed as part of bulk deployment) will be used to compute placement for individual VMs. Once placement for all VMs are finalised the remaining deployment steps for all VMs will happen in parallel and follow the existing logic.

APIs

New API bulkDeployVirtualMachine to be added available to root admin only.

Input parameters

• zoneid - Id of availability zone for the VM
  
  • type - long
  • validation - should exist in DB
  • required
• serviceofferingid - Id of service offering for the VM
  • type - long
  • validation - should exist in DB
  • required
• templateid - Id of template used to deploy VM
  • type - long
  • validation - should exist in DB
  • required
• virtualmachinecount - number of VMs to deploy
  • type - integer
  • validation - positive number
  • required
• podid - Id of the pod in which to deploy
  • type - long
  • validation - should exist in DB
  • optional - mutually exclusive with clusterid
• clusterid - Id of the cluster in which to deploy
  • type - long
  • validation - should exist in DB
  • optional - mutually exclusive with podid
• hypervisor - hypervisor type on which to deploy VM
  • type - string
  • validation - should be a valid hypervisor type (XenServer, VMware, KVM etc.)
  • optional - if hypervisor information not present in template then required
• userdata - binary data (base64) that can be sent to the virtual machine upon a successful deployment
  • type - string
  • validation - base64 encoded, size restriction with GET and POST methods
  • optional
• keypair - name of the SSH key pair used to login to the virtual machine
  • type - string
  • validation - should exist in DB
  • optional
• networkids - comma separated list of network IDs used by VM
  • type - list of longs
  • validation - should exist in DB

• diwskofferingid - optional disk offering ID for the VM, if the template is of ISO format, it is for the root disk volume otherwise used to indicate the offering for the data disk volume

  • type - long
  • validation - should exist in DB
  • optional

• securitygroupids - comma separated list of security group IDs that are going to be applied to the VM, applicable only for basic network

  • type - list of longs
  • validation - should exist in DB
  • optional - mutually exclusive with securitygroupnames

• securitygroupnames - comma separated list of security group names that are going to be applied to VM, applicable only for basic network

  • type - list of strings
  • validation - should exist in DB
  • optional - mutually exclusive with securitygroupids

• affinitygroupids - comma separated list of affinity groups IDs that are going to be applied to the VM

  • type - list of longs
  • validation - should exist in DB
  • optional - mutually exclusive with affinitygroupnames

• affinitygroupnames - comma separated list of affinity groups names that are going to be applied to the VM

  • type - list of strings
  • validation - should exist in DB
  • optional - mutually exclusive with affinitygroupids
• account - account for VM
  • type - string
  • validation - should exist in DB
  • optional - used along with domainid
• domainid - domain to which the account belongs
  • type - long
  • validation - should exist in DB
  • optional - used along with account

Output

Returns a list of jobs that are scheduled to deploy individual VMs

UI flow

TODO

Upgrade Considerations

Based on the current requirements no DB schema changes is needed, so no upgrade impact

Security

The new API is available to root admin only and the parameters passed doesn't have any sensitive information

Concurrency Considerations

Distribution of VMs based on count is only for a single bulk deployment API call. If there are multiple bulk deployment API calls then distribution may not be uniform.

Appendix