VirtualMachineTemplatesResource


Create a persistent virtual machine template in a virtual datacenter


Create a new persistent template from an existing template.
The disk of the existing template will be dumped onto a volume.

The body in this request contains: the name of the new volume to create and the name of the new VM template to create. And links to :

  • source VM template, which has the disk to dump to the volume
  • *
  • virtual datacenter, where the VM template will be accessible
  • storage device where the disk will be dumped, which could be a link to a specific volume or a link to a tier where a new volume will be created.

Requires a RAW conversion of all the disks in the source VM template. If those conversions do not exist, they will be created as the first step of the process.

POST https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates

Roles : [ROLE_VAPP_CREATE_STATEFUL, ROLE_APPLIB_ALLOW_MODIFY, ROLE_APPLIB_EXPORT_TO_PUBLIC, ROLE_APPLIB_EXPORT_TO_PRIVATE]

Error Codes

  • CONSTR-LENGTH-NAME-MAX - The length of the NAME parameter must be less than 255 characters
  • CONSTR-LENGTH-VOL-NAME-MAX - The length of the NAME parameter must be less than 255 characters
  • GEN-4 - Not enough permissions to perform this action
  • PERSISTENT-1 - The virtual machine template is already persistent
  • PERSISTENT-12 - No virtual datacenter found for the persistent virtual machine
  • PERSISTENT-14 - The virtual datacenter does not belong to the correct enterprise
  • PERSISTENT-19 - Cannot request creation of a persistent disk from an empty disk
  • PERSISTENT-20 - Cannot request creation of a persistent disk from an ISO disk
  • PERSISTENT-3 - No name given for the new persistent template
  • PERSISTENT-4 - No tier or volume for storing the persistent virtual machine template was found in the request but one of these is required
  • PERSISTENT-5 - There are no pools available in at least one of the selected tiers
  • PERSISTENT-8 - No virtual machine template found to persist
  • PERSISTENT-9 - Invalid tier link
  • TIER-0 - The requested storage tier does not exist
  • VDC-0 - The requested virtual datacenter does not exist
  • VIMAGE-0 - The requested virtual machine template does not exist
  • VIMAGE-55 - The operation is not allowed because the template/disk does not physically exist in the repository
  • VOL-3 - The volume does not exist

Example

Create a virtual machine template in a datacenter repository by download promote or export


Create a VM template in the datacenter repository.

The body can specify multiple options:

  • If it contains a link to a template definition: download the template definition
  • If it contains a link to another VM template (and attribute ''promotedName''): create a copy of this VM template in a datacenter repository. A VM template link from another location means it's an **export**; one from an instance means it's a **promote to master**, otherwise it's a **copy**.
    You can specify a subset of disks to export/promote/copy
The response includes the link to the pre-created VM template (the template will be available when the task finishes)

POST https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates

Roles : [ROLE_VAPP_CREATE_STATEFUL, ROLE_APPLIB_ALLOW_MODIFY, ROLE_APPLIB_EXPORT_TO_PUBLIC, ROLE_APPLIB_EXPORT_TO_PRIVATE]

Error Codes

  • VIMAGE-55 - The operation is not allowed because the template/disk does not physically exist in the repository

Example

Create a virtual machine template in a datacenter repository by downloading a template definition


Creates a VM template by downloading the content of a template definition into a datacenter repository

POST https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates

Roles : [ROLE_VAPP_CREATE_STATEFUL, ROLE_APPLIB_ALLOW_MODIFY, ROLE_APPLIB_EXPORT_TO_PUBLIC, ROLE_APPLIB_EXPORT_TO_PRIVATE]

Content-Type : templatedefinition Accept : acceptedrequest

Create a virtual machine template in a public cloud region repository


Store a VM template that was returned from a list ''source=REMOTE'' in a public cloud region to enable users to create new VMs from it

POST https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates

Roles : [ROLE_VAPP_CREATE_STATEFUL, ROLE_APPLIB_ALLOW_MODIFY, ROLE_APPLIB_EXPORT_TO_PUBLIC, ROLE_APPLIB_EXPORT_TO_PRIVATE]

Error Codes

  • VIMAGE-0 - The requested virtual machine template does not exist
  • VIMAGE-39 - A public cloud template already exists for this path identifier

Example

List virtual machine templates in a datacenter repository


Retrieve VM templates in a datacenter repository (location and enterprise)

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates

Roles : [ROLE_APPLIB_VIEW, ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_CREATE_STATEFUL]

Parameter Type Default Value Description
categoryName String If present, filter by category name
hypervisorTypeName String If present, filter by compatibility with a hypervisor type (disk format types)
virtualdatacenter Integer If present, filter by compatibility with a virtual datacenter identifier (disk format types of the virtual datacenter type)
stateful String If present, filter persistent VM templates by ALL, USED or NOTUSED
imported Boolean false If true, include imported VM templates (from captured virtual machines)
description String If present, filter by the description
ostype String If present, filter by operating system
name String If present, filter by name
path String If present, filter by path
publishers String If present, filters by a comma-separated list of valid publisher names
ovfId String If present, filter by URI of the template definition.
For public clouds, this is used for ''image id''
creationUser String If present, filter by the user who created the template.
Can be a nonexistent user or a simple identifier
64bits Boolean If true, only return x64 architecture; if false, only return x86 architectures.
It requires ''ostype'' param set to null (null for any filter)
startwith Integer 0 The first element to be retrieved of the filtered search
by String state Order by
has String If present filter to apply in the search.
limit Integer 25 The number of entities to retrieve
asc Boolean true If the value of the 'by' parameter must be sorted in ascending order (true) or descending order (false)
source String LOCAL only for public cloud regions:
  • LOCAL: only retrieve stored VM templates
  • REMOTE: search in the public cloud region provider, and don't return already stored VM templates
  • ALL: both LOCAL and REMOTE templates, may contain duplicate templates (local and remote representation of the same template)
public Boolean If true, include public VM templates in the public cloud region provider.
plugin String If present, only for public cloud regions, requires ''source=REMOTE'' specify the public cloud region provider type (eg. DOCKER)
master Boolean If true, only returns VM templates with instance/s. If false, only returns VM template instances.
includeorphaninstances boolean false If true, requires ''masterInclusion=true'', and includes instances with the master not visible (not shared and in another enterprise)
states String If present, filter by comma separated value of VM template states
external Boolean true If false, do not include external VM templates in the public cloud region provider. Only return the templates that physically exist in the datacenter repository
When using Docker, the container images are not physically downloaded to the datacenter repository (NFS).
boot boolean false If true, include only VM templates with bootable disk/s
diskformattypes String If present, filter by comma separated values of disk format types {@DiskFormatType}

Error Codes

  • DC-0 - The requested datacenter does not exist
  • EN-0 - The requested enterprise does not exist
  • ENTERPRISE-10 - The enterprise does not have permission to use the requested datacenter
  • HYPERVISOR_TYPE-0 - The requested hypervisor type is invalid
  • PUBLIC-10 - The enterprise does not have credentials for this provider
  • VIMAGE-66 - You are not allowed to access the templates of this enterprise from your current one

Example

Delete a virtual machine template


Remove a VM template and all its associated disks from the datacenter repository

If it cannot be deleted because it's in use (VMs are using it or it has instances), use the method to ''make a virtual machine template unavailable''

DELETE https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}

Roles : [ROLE_APPLIB_ALLOW_MODIFY, ROLE_VAPP_CREATE_STATEFUL]

Example

Get a virtual machine template


Retrieve a virtual machine template in private or public cloud

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}

Roles : [ROLE_APPLIB_VIEW, ROLE_VDC_ENUMERATE, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS, ROLE_VAPP_PERFORM_ACTIONS, ROLE_VAPP_DEPLOY_UNDEPLOY, ROLE_VAPP_ASSIGN_NETWORK, ROLE_VAPP_ASSIGN_VOLUME, ROLE_VAPP_CREATE_STATEFUL, ROLE_PHYS_DC_RETRIEVE_DETAILS, ROLE_MANAGE_HARD_DISKS]

Parameter Type Default Value Description
source String LOCAL only for public cloud regions:
  • LOCAL: only retrieve stored virtual machine templates
  • REMOTE: search in the public cloud region provider, it doesn't contain already stored virtual machine templates
plugin String If present, only for public cloud regions, requires ''source=REMOTE'' specify the public cloud region provider type (eg. DOCKER)

Error Codes

  • DC-0 - The requested datacenter does not exist
  • EN-0 - The requested enterprise does not exist
  • ENTERPRISE-10 - The enterprise does not have permission to use the requested datacenter
  • VIMAGE-0 - The requested virtual machine template does not exist

Example

Update a virtual machine template


Update a VM template. To modify the recommended hardware profiles, add or change the ''hardwareprofile'' link for each profile.

PUT https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}

Roles : [ROLE_APPLIB_ALLOW_MODIFY, ROLE_VAPP_CREATE_STATEFUL]

Error Codes

  • CONSTR-DIVISIBLE - The property 'cpuRequired' is not divisible by the configured cores per socket 3.
  • CONSTR-LENGTH - The property 'name' length must be between 1 and 255.
  • CONSTR-RANGE - The property 'cpuRequired' must be between 1 and 2147483647.
  • COSTCODE-0 - The requested cost code does not exist
  • DISK-3 - Disk not found
  • GEN-4 - Not enough permissions to perform this action
  • PROFILE-1 - The requested hardware profile does not exist
  • PROFILE-3 - Invalid link to the hardware profile; cannot get profile values
  • SCOPE-1 - The requested scope does not exist
  • SCOPE-11 - Cannot remove the scope. The virtual machine template is being used by virtual machines in other enterprises.
  • VIMAGE-14 - Cannot modify a failed persistent virtual machine template
  • VIMAGE-15 - Cannot modify a persistent virtual machine template that is in progress
  • VIMAGE-21 - A persistent virtual machine template cannot be shared
  • VIMAGE-42 - Could not modify disk information; use the new Disk resource
  • VIMAGE-43 - Could not modify a virtual machine template with multiple disks
  • VIMAGE-49 - Invalid input. Repeated disk attachment value is not allowed.
  • VIMAGE-51 - Cannot add/remove disk. Use Disk resource.
  • VIMAGE-61 - Invalid minimum CPU. Check VM CPU settings or recommended hardware profile
  • VIMAGE-62 - Invalid maximum CPU. Check VM CPU settings or recommended hardware profile
  • VIMAGE-63 - Invalid minimum RAM. Check VM RAM settings or recommended hardware profile
  • VIMAGE-64 - Invalid maximum RAM. Check VM RAM settings or recommended hardware profile
  • VIMAGE-65 - Cannot edit CPU/RAM or set minimum and maximum values for a public template with a hardware profile
  • VIMAGE-70 - Cannot edit template because the template belong to another enterprise
  • VIMAGE-71 - Generating an initial guest password requires guest customizations

Example

List tasks on a virtual machine template


Displays the tasks on the VM template. Tasks are a set of jobs (operations on the provider or datacenter repository). Any of these tasks may still be in progress.

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/tasks

Roles : [ROLE_APPLIB_VIEW, ROLE_APPLIB_ALLOW_MODIFY, ROLE_VDC_MANAGE_VAPP]

Accept : tasks

Example

Get a task on a virtual machine template


Displays a specific task on a VM template. Tasks are a set of jobs (operations on the provider or datacenter repository). Any of these tasks may still be in progress. Each task has a UUID.

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/tasks/{id}

Roles : [ROLE_APPLIB_VIEW, ROLE_APPLIB_ALLOW_MODIFY, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CREATE_STATEFUL]

Accept : task

Example

Get an extended task on a virtual machine template


Displays a specific task on a VM template including additional job info (progress, errorCause) Tasks are a set of jobs (operations on the provider or datacenter repository). Any of these tasks may still be in progress. Each task has a UUID.

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/tasks/{id}

Roles : [ROLE_APPLIB_VIEW, ROLE_APPLIB_ALLOW_MODIFY, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CREATE_STATEFUL]

Accept : taskextended

Make unavailable a virtual machine template


Only if cannot use ''delete a virtual machine template'' because the virtual machine template is in use (has instances or virtual machines using it) cannot delete it but can mark it as unavailable to prevent the creation of new virtual machines using it.
The request remove all the disk files from the datacenter repository filesystem but keep the reference to the virtual machine template in the API (state = UNAVAILABLE)

POST https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/action/deletefile

Roles : [ROLE_APPLIB_ALLOW_MODIFY, ROLE_VAPP_CREATE_STATEFUL]

Example

List instances of a virtual machine template


Retrieves virtual machine templates instances of a master virtual machine template

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/action/instances

Roles : [ROLE_APPLIB_VIEW, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Parameter Type Default Value Description
allenterprises Boolean false If true, also includes instances in other enterprises.
cloudadmin can see all the virtual machine templates in all enterprises (by * default only see those in its current enterprise)
stateful String If true, also includes the persistent virtual machine templates created from the current virutal machine template

Error Codes

  • GEN-15 - Not enough privileges to perform this operation
  • GEN-4 - Not enough permissions to perform this action

Example

Move a persistent virtual machine template into a virtual datacenter


Move the persistent template to the given virtual datacenter.
Requires no virtual machine is using it.

PUT https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/action/move

Roles : [ROLE_APPLIB_ALLOW_MODIFY, ROLE_VAPP_CREATE_STATEFUL]

Content-Type : links Accept : virtualmachinetemplate

Error Codes

  • VIMAGE-52 - A non persistent template cannot be moved between virtual datacenters

Example

List virtual machines using a virtual machine template


Retrieve virtual machines with relation to the current virtual machine template

GET https://example.com/api/admin/enterprises/{enterprise}/datacenterrepositories/{datacenterrepository}/virtualmachinetemplates/{virtualmachinetemplate}/action/virtualmachines

Roles : [ROLE_APPLIB_VIEW, ROLE_VDC_MANAGE_VAPP, ROLE_VAPP_CUSTOMISE_SETTINGS]

Parameter Type Default Value Description
hashypervisor Boolean If true only returns VMs assigned to hypervisor (deployed). If false only returns VMs without hypervisor (not deployed)
allenterprises Boolean false If true, also includes instances in other enterprises.
cloudadmin can see all the virtual machine templates in all enterprises (by * default only see those in its current enterprise)

Accept : virtualmachines

Error Codes

  • GEN-15 - Not enough privileges to perform this operation

Example