vmware.vmware_rest.vcenter_vmtemplate_libraryitems module – Manage virtual machine templates in vCenter content libraries.

Note

This module is part of the vmware.vmware_rest collection (version 5.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install vmware.vmware_rest.

To use it in a playbook, specify: vmware.vmware_rest.vcenter_vmtemplate_libraryitems.

New in vmware.vmware_rest 5.0.0

DEPRECATED

Removed in:

version 6.0.0

Why:

This functionality has been moved to vmware.vmware.

Alternative:

Use vmware.vmware.deploy_content_library_template or vmware.vmware.content_template instead.

Synopsis

  • Create and deploy virtual machine template library items in VMware vCenter content libraries.

  • Use state=present to create a new library item by capturing an existing virtual machine as a virtual machine template.

  • Use state=deploy to deploy a new virtual machine from an existing virtual machine template library item onto a target resource pool, host, or cluster.

  • This module will always report a change in check mode.

  • Library items cannot be updated due to API limitations

Parameters

Parameter

Comments

description

string

Description for the new library item.

If not set, the new library item inherits the description of the source virtual machine.

This property was added in vSphere API 6.8.

disk_storage

dictionary

Default storage specification for the virtual machine template’s disks.

Applies to any disk not listed in disk_storage_overrides.

If neither disk_storage nor disk_storage_overrides is set, the disks are placed on the default storage backing associated with the library given in library.

This property was added in vSphere API 6.8.

datastore

string

Identifier of the datastore for the template’s disks.

Must be an identifier (MOID) for a Datastore resource.

This suboption is currently required.

If storage_policy is also set and is incompatible with this datastore, the disk is flagged as out of compliance with that storage policy.

This property was added in vSphere API 6.8.

storage_policy

dictionary

Storage policy for the template’s disks.

If not set, datastore must be specified and the disks use the default storage policy of that datastore.

This property was added in vSphere API 6.8.

policy

string

Identifier of the storage policy to use.

Must be an identifier (MOID) for a com.vmware.spbm.StorageProfile resource.

Only relevant when type is USE_SPECIFIED_POLICY.

This property was added in vSphere API 6.8.

type

string / required

Policy type to apply to the template’s disks.

USE_SPECIFIED_POLICY - Use the storage policy given in policy.

This property was added in vSphere API 6.8.

Choices:

  • "USE_SPECIFIED_POLICY"

disk_storage_overrides

dictionary

Per-disk storage specifications for the virtual machine template.

Specified as a mapping of source virtual machine disk identifiers (MOIDs of com.vmware.vcenter.vm.hardware.Disk resources) to their storage specifications.

Disks not listed here fall back to disk_storage, or to the library’s default storage backing if disk_storage is also unset.

This property was added in vSphere API 6.8.

guest_customization

dictionary

Guest customization to apply to the deployed virtual machine.

Applies when state=deploy. If not set, the guest operating system is not customized.

This property was added in vSphere API 6.8.

name

string

Name of an existing guest customization specification to apply.

If not set, no guest customization is performed.

This property was added in vSphere API 6.8.

hardware_customization

dictionary

Hardware changes to apply to the deployed virtual machine.

Applies when state=deploy. If not set, the deployed virtual machine keeps the same hardware configuration as the template.

This property was added in vSphere API 6.8.

cpu_update

dictionary

CPU changes to apply to the deployed virtual machine.

If not set, the deployed virtual machine keeps the template’s CPU settings.

This property was added in vSphere API 6.8.

num_cores_per_socket

integer

Number of cores per socket for the deployed virtual machine.

If not set, the deployed virtual machine keeps the template’s cores-per-socket value.

This property was added in vSphere API 6.8.

num_cpus

integer

Number of virtual processors for the deployed virtual machine.

If not set, the deployed virtual machine keeps the template’s CPU count.

This property was added in vSphere API 6.8.

disks_to_remove

list / elements=string

Identifiers of disks to remove from the deployed virtual machine.

Each entry must be an identifier (MOID) for a com.vmware.vcenter.vm.hardware.Disk resource.

If not set, all disks are copied to the deployed virtual machine.

This property was added in vSphere API 6.8.

disks_to_update

dictionary

Per-disk update specifications for the deployed virtual machine, keyed by disk identifier (MOID of a com.vmware.vcenter.vm.hardware.Disk resource).

If not set, disks keep the same settings as the corresponding disks in the template.

This property was added in vSphere API 6.8.

memory_update

dictionary

Memory changes to apply to the deployed virtual machine.

If not set, the deployed virtual machine keeps the template’s memory settings.

This property was added in vSphere API 6.8.

memory

integer

Memory size for the deployed virtual machine, in MB.

If not set, the deployed virtual machine keeps the template’s memory size.

This property was added in vSphere API 6.8.

nics

dictionary

Mapping of Ethernet adapters to update, keyed by adapter identifier (MOID of a com.vmware.vcenter.vm.hardware.Ethernet resource).

If not set, all adapters stay connected to the same networks as in the template. An adapter with a manual MAC address keeps its address; adapters with generated or assigned MAC addresses receive new addresses.

This property was added in vSphere API 6.8.

library

string

Identifier of the content library in which the new library item should be created.

Must be an identifier (MOID) for a com.vmware.content.Library resource.

Required when state=present.

This property was added in vSphere API 6.8.

name

string

When state=present, the name of the new library item to create.

When state=deploy, the name of the new virtual machine to deploy.

Required for both present and deploy.

This property was added in vSphere API 6.8.

placement

dictionary

Placement information for the virtual machine template.

This suboption is currently required.

Each specified value is used for placement. If the values, or the values combined with the placement of the source virtual machine, are contradictory, the operation fails.

This property was added in vSphere API 6.8.

cluster

string

Identifier of the cluster to place the template on.

Must be an identifier (MOID) for a ClusterComputeResource resource.

If resource_pool is also set, it must belong to this cluster. If host is also set, it must be a member of this cluster.

It is recommended to leave this unset when resource_pool or host is specified.

This property was added in vSphere API 6.8.

folder

string

Identifier of the virtual machine folder to place the template in.

Must be an identifier (MOID) for a Folder resource.

If not set, the template is placed in the same folder as the source virtual machine.

This property was added in vSphere API 6.8.

host

string

Identifier of the host to place the template on.

Must be an identifier (MOID) for a HostSystem resource.

If resource_pool is also set, it must belong to this host. If cluster is also set, this host must be a member of that cluster.

May be omitted if resource_pool or cluster is set. If not set, the system attempts to choose a suitable host; the operation fails if one cannot be chosen.

This property was added in vSphere API 6.8.

resource_pool

string

Identifier of the resource pool to place the template in.

Must be an identifier (MOID) for a ResourcePool resource.

If not set, the system attempts to choose a suitable resource pool; the operation fails if one cannot be chosen.

This property was added in vSphere API 6.8.

powered_on

boolean

Whether the deployed virtual machine should be powered on after deployment.

Applies when state=deploy. If not set, the virtual machine is left powered off.

This property was added in vSphere API 6.8.

Choices:

  • false

  • true

session_timeout

float

Timeout in seconds for the whole operation including connection establishment, request sending, and response.

Default: 300.0

source_vm

string

Identifier of the source virtual machine to create the library item from.

Must be an identifier (MOID) for a VirtualMachine resource.

Required when state=present.

This property was added in vSphere API 6.8.

state

string

The desired state of the resource.

Use present to create a virtual machine template library item from a source virtual machine.

Use deploy to deploy a new virtual machine from a template library item.

Only present supports idempotence.

Choices:

  • "present" ← (default)

  • "deploy"

tags

list / elements=dictionary

Tags to attach to the deployed virtual machine.

Applies when state=deploy.

This property was added in vSphere API 9.1.0.0.

tag_id

string

Identifier of the vSphere tag to attach.

If both tag_id and tag_name_spec are set, they must refer to the same vSphere tag.

Required if tag_name_spec is not set.

This property was added in vSphere API 9.1.0.0.

tag_name_spec

dictionary

Identifies the tag to attach by its name and category.

If both tag_id and tag_name_spec are set, they must refer to the same vSphere tag.

Required if tag_id is not set.

This property was added in vSphere API 9.1.0.0.

category_name

string / required

The name of the vSphere category that the tag belongs to.

This property was added in vSphere API 9.1.0.0.

tag_name

string / required

The name of the tag to attach.

This property was added in vSphere API 9.1.0.0.

template_library_item

string

Identifier of the template library item to deploy from.

Must be an identifier (MOID) for a TemplateLibraryItem resource.

Required when state=deploy.

vcenter_hostname

string / required

The hostname or IP address of the vSphere vCenter.

If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.

vcenter_password

string / required

The vSphere vCenter password.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

vcenter_port

integer

The port number of the vSphere vCenter.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

vcenter_rest_log_file

string

Optional path to a log file for HTTP REST interaction.

If the value is not specified in the task, the value of environment variable VMWARE_REST_LOG_FILE will be used instead.

vcenter_username

string / required

The vSphere vCenter username.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

vcenter_validate_certs

boolean

Allows connection when SSL certificates are not valid.

Set to false when certificates are not trusted.

If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead.

Choices:

  • false

  • true ← (default)

vm_home_storage

dictionary

Storage location for the virtual machine template’s configuration and log files.

If not set, the configuration and log files are placed on the default storage backing associated with the library given in library.

This property was added in vSphere API 6.8.

datastore

string

Identifier of the datastore that holds the template’s configuration and log files.

Must be an identifier (MOID) for a Datastore resource.

This suboption is currently required.

If storage_policy is also set and is incompatible with this datastore, the template is flagged as out of compliance with that storage policy.

This property was added in vSphere API 6.8.

storage_policy

dictionary

Storage policy for the template’s configuration and log files.

If not set, datastore must be specified and the configuration and log files use the default storage policy of that datastore.

This property was added in vSphere API 6.8.

policy

string

Identifier of the storage policy to use.

Must be an identifier (MOID) for a com.vmware.spbm.StorageProfile resource.

Only relevant when type is USE_SPECIFIED_POLICY.

This property was added in vSphere API 6.8.

type

string / required

Policy type to apply to the template’s configuration and log files.

USE_SPECIFIED_POLICY - Use the storage policy given in policy.

This property was added in vSphere API 6.8.

Choices:

  • "USE_SPECIFIED_POLICY"

Notes

Note

  • Generated from vSphere API spec 9.1.0.

  • Not compatible with vSphere API 7.0.3.

  • Not compatible with vSphere API 8.0.2.

Examples

- name: Create a VM template library item from an existing virtual machine
  vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
    name: my-vm-template
    source_vm: vm-1001
    library: 570bdaa2-5f0a-45c8-8bb5-1234567890ab
    placement:
      folder: group-v1002
      resource_pool: resgroup-1003
    state: present

- name: Create a VM template library item with a specific home datastore
  vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
    name: my-vm-template
    description: Golden image for web servers
    source_vm: vm-1001
    library: 570bdaa2-5f0a-45c8-8bb5-1234567890ab
    vm_home_storage:
      datastore: datastore-1004
    disk_storage:
      datastore: datastore-1004
    placement:
      resource_pool: resgroup-1003
    state: present

- name: Deploy a virtual machine from a template library item
  vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
    template_library_item: 8a5f1c2d-9b3e-4f6a-8c7d-abcdef012345
    name: deployed-vm
    powered_on: true
    placement:
      folder: group-v1002
      resource_pool: resgroup-1003
    state: deploy

- name: Deploy a virtual machine with CPU and memory customization
  vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
    template_library_item: 8a5f1c2d-9b3e-4f6a-8c7d-abcdef012345
    name: deployed-vm-custom
    powered_on: true
    placement:
      resource_pool: resgroup-1003
    hardware_customization:
      cpu_update:
        num_cpus: 4
        num_cores_per_socket: 2
      memory_update:
        memory: 8192
    state: deploy

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

id

string

Identifier of the managed resource.

When state=present, this is the identifier of the created virtual machine template library item.

When state=deploy, this is the identifier of the source template library item that was deployed from. The identifier of the newly deployed virtual machine is returned in value.

Returned: When state is present, or when state is set to a supported action

Sample: "vm-1010"

value

any

The raw API response body from the vCenter operation.

When state=present, the identifier of the created library item.

When state=deploy, the identifier of the deployed virtual machine.

Returned: On success

Sample: "vm-1010"

Status

  • This module will be removed in version 6.0.0. [deprecated]

  • For more information see DEPRECATED.

Authors

  • Ansible Eco Content Team (@eco-ansible-content)