vmware.vmware.vm_custom_attributes module – Manage custom attributes from VMware for the given virtual machine

Note

This module is part of the vmware.vmware collection (version 2.12.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.

To use it in a playbook, specify: vmware.vmware.vm_custom_attributes.

Synopsis

• This module can be used to add, remove and update custom attributes for the given virtual machine.

Parameters

Parameter	Comments
attributes dictionary	A dictionary of custom attributes to manage. The keys are the attribute names, the values are the attribute values. Values are not required and will be ignored if state=absent. Default: {}
datacenter string	Datacenter name where the virtual machine is located in.
folder string	Destination folder, absolute or relative path to find an existing guest. Should be the full folder path, with or without the ‘datacenter/vm/’ prefix. For example ‘datacenter_name/vm/path/to/folder’ or ‘path/to/folder’. This is required parameter, if name is supplied and multiple virtual machines with same name are found.
folder_paths_are_absolute boolean	If true, any folder path parameters are treated as absolute paths. If false, modules will try to intelligently determine if the path is absolute or relative. This option is useful when your environment has a complex folder structure. By default, modules will try to intelligently determine if the path is absolute or relative. They may mistakenly prepend the datacenter name or other folder names, and this option can be used to avoid this. Choices: false ← (default) true
hostname string	The hostname or IP address of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.
moid string	Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance. This is required if name or uuid is not supplied.
name string	Name of the virtual machine to work with. This is required parameter, if uuid or moid is not supplied.
password aliases: pass, pwd string	The password of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.
port integer	The port number of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead. Default: 443
proxy_host string	The address of a proxy that will receive all HTTPS requests and relay them. The format is a hostname or a IP. If the value is not specified in the task, the value of environment variable VMWARE_PROXY_HOST will be used instead.
proxy_port integer	The port of the HTTP proxy that will receive all HTTPS requests and relay them. If the value is not specified in the task, the value of environment variable VMWARE_PROXY_PORT will be used instead.
state string	The action to take. If set to present, then custom attribute is added or updated. If set to absent, then custom attribute value is removed. Choices: "present" ← (default) "absent"
use_instance_uuid boolean	Whether to use the VMware instance UUID rather than the BIOS UUID. Choices: false ← (default) true
username aliases: admin, user string	The username of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.
uuid string	UUID of the virtual machine to manage if known. This is VMware’s unique identifier. This is required parameter, if name or moid is not supplied.
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)

Notes

Note

• All modules require API write access and hence are not supported on a free ESXi license.

• All variables and VMware object names are case sensitive.

• Modules may rely on the ‘requests’ python library, which does not use the system certificate store by default. You can specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable. Note having this variable set may cause a ‘false’ value for the ‘validate_certs’ option to be ignored in some cases. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’

Examples

- name: Add virtual machine custom attributes
  vmware.vmware.vm_custom_attributes:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    uuid: 421e4592-c069-924d-ce20-7e7533fab926
    state: present
    attributes:
      MyAttribute: MyValue
  delegate_to: localhost
  register: attributes

- name: Add multiple virtual machine custom attributes
  vmware.vmware.vm_custom_attributes:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    uuid: 421e4592-c069-924d-ce20-7e7533fab926
    state: present
    attributes:
      MyAttribute: MyValue
      MyAttribute2: MyValue2
  delegate_to: localhost
  register: attributes

- name: Remove virtual machine custom attribute
  vmware.vmware.vm_custom_attributes:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    uuid: 421e4592-c069-924d-ce20-7e7533fab926
    state: absent
    attributes:
      MyAttribute:
  delegate_to: localhost
  register: attributes

- name: Remove virtual machine custom attribute using Virtual Machine MoID
  vmware.vmware.vm_custom_attributes:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    moid: vm-42
    state: absent
    attributes:
      MyAttribute:
  delegate_to: localhost
  register: attributes

Return Values

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

Key	Description
custom_attributes dictionary	metadata about the virtual machine custom attributes Returned: always Sample: {"mycustom": "my_custom_value", "mycustom_2": "my_custom_value_2", "sample_1": "sample_1_value", "sample_2": "sample_2_value", "sample_3": "sample_3_value"}

Authors

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

• Lorenzo Andreasi (@lollo03)

• Mike Morency (@mikemorency)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication