1.. _vmware_guest_rename_virtual_machine: 2 3********************************** 4Rename an existing virtual machine 5********************************** 6 7.. contents:: Topics 8 9Introduction 10============ 11 12This guide will show you how to utilize Ansible to rename an existing virtual machine. 13 14Scenario Requirements 15===================== 16 17* Software 18 19 * Ansible 2.5 or later must be installed. 20 21 * The Python module ``Pyvmomi`` must be installed on the Ansible control node (or Target host if not executing against localhost). 22 23 * We recommend installing the latest version with pip: ``pip install Pyvmomi`` (as the OS packages are usually out of date and incompatible). 24 25* Hardware 26 27 * At least one standalone ESXi server or 28 29 * vCenter Server with at least one ESXi server 30 31* Access / Credentials 32 33 * Ansible (or the target server) must have network access to the either vCenter server or the ESXi server 34 35 * Username and Password for vCenter or ESXi server 36 37 * Hosts in the ESXi cluster must have access to the datastore that the template resides on. 38 39Caveats 40======= 41 42- All variable names and VMware object names are case sensitive. 43- You need to use Python 2.7.9 version in order to use ``validate_certs`` option, as this version is capable of changing the SSL verification behaviours. 44 45 46Example Description 47=================== 48 49With the following Ansible playbook you can rename an existing virtual machine by changing the UUID. 50 51.. code-block:: yaml 52 53 --- 54 - name: Rename virtual machine from old name to new name using UUID 55 gather_facts: no 56 vars_files: 57 - vcenter_vars.yml 58 vars: 59 ansible_python_interpreter: "/usr/bin/env python3" 60 hosts: localhost 61 tasks: 62 - set_fact: 63 vm_name: "old_vm_name" 64 new_vm_name: "new_vm_name" 65 datacenter: "DC1" 66 cluster_name: "DC1_C1" 67 68 - name: Get VM "{{ vm_name }}" uuid 69 vmware_guest_facts: 70 hostname: "{{ vcenter_server }}" 71 username: "{{ vcenter_user }}" 72 password: "{{ vcenter_pass }}" 73 validate_certs: False 74 datacenter: "{{ datacenter }}" 75 folder: "/{{datacenter}}/vm" 76 name: "{{ vm_name }}" 77 register: vm_facts 78 79 - name: Rename "{{ vm_name }}" to "{{ new_vm_name }}" 80 vmware_guest: 81 hostname: "{{ vcenter_server }}" 82 username: "{{ vcenter_user }}" 83 password: "{{ vcenter_pass }}" 84 validate_certs: False 85 cluster: "{{ cluster_name }}" 86 uuid: "{{ vm_facts.instance.hw_product_uuid }}" 87 name: "{{ new_vm_name }}" 88 89Since Ansible utilizes the VMware API to perform actions, in this use case it will be connecting directly to the API from localhost. 90 91This means that playbooks will not be running from the vCenter or ESXi Server. 92 93Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost. 94 95You can run these modules against another server that would then connect to the API if localhost does not have access to vCenter. If so, the required Python modules will need to be installed on that target server. We recommend installing the latest version with pip: ``pip install Pyvmomi`` (as the OS packages are usually out of date and incompatible). 96 97Before you begin, make sure you have: 98 99- Hostname of the ESXi server or vCenter server 100- Username and password for the ESXi or vCenter server 101- The UUID of the existing Virtual Machine you want to rename 102 103For now, you will be entering these directly, but in a more advanced playbook this can be abstracted out and stored in a more secure fashion using :ref:`ansible-vault` or using `Ansible Tower credentials <https://docs.ansible.com/ansible-tower/latest/html/userguide/credentials.html>`_. 104 105If your vCenter or ESXi server is not setup with proper CA certificates that can be verified from the Ansible server, then it is necessary to disable validation of these certificates by using the ``validate_certs`` parameter. To do this you need to set ``validate_certs=False`` in your playbook. 106 107Now you need to supply the information about the existing virtual machine which will be renamed. For renaming virtual machine, ``vmware_guest`` module uses VMware UUID, which is unique across vCenter environment. This value is autogenerated and can not be changed. You will use ``vmware_guest_facts`` module to find virtual machine and get information about VMware UUID of the virtual machine. 108 109This value will be used input for ``vmware_guest`` module. Specify new name to virtual machine which conforms to all VMware requirements for naming conventions as ``name`` parameter. Also, provide ``uuid`` as the value of VMware UUID. 110 111What to expect 112-------------- 113 114Running this playbook can take some time, depending on your environment and network connectivity. When the run is complete you will see 115 116.. code-block:: yaml 117 118 { 119 "changed": true, 120 "instance": { 121 "annotation": "", 122 "current_snapshot": null, 123 "customvalues": {}, 124 "guest_consolidation_needed": false, 125 "guest_question": null, 126 "guest_tools_status": "guestToolsNotRunning", 127 "guest_tools_version": "10247", 128 "hw_cores_per_socket": 1, 129 "hw_datastores": ["ds_204_2"], 130 "hw_esxi_host": "10.x.x.x", 131 "hw_eth0": { 132 "addresstype": "assigned", 133 "ipaddresses": [], 134 "label": "Network adapter 1", 135 "macaddress": "00:50:56:8c:b8:42", 136 "macaddress_dash": "00-50-56-8c-b8-42", 137 "portgroup_key": "dvportgroup-31", 138 "portgroup_portkey": "15", 139 "summary": "DVSwitch: 50 0c 3a 69 df 78 2c 7b-6e 08 0a 89 e3 a6 31 17" 140 }, 141 "hw_files": ["[ds_204_2] old_vm_name/old_vm_name.vmx", "[ds_204_2] old_vm_name/old_vm_name.nvram", "[ds_204_2] old_vm_name/old_vm_name.vmsd", "[ds_204_2] old_vm_name/vmware.log", "[ds_204_2] old_vm_name/old_vm_name.vmdk"], 142 "hw_folder": "/DC1/vm", 143 "hw_guest_full_name": null, 144 "hw_guest_ha_state": null, 145 "hw_guest_id": null, 146 "hw_interfaces": ["eth0"], 147 "hw_is_template": false, 148 "hw_memtotal_mb": 1024, 149 "hw_name": "new_vm_name", 150 "hw_power_status": "poweredOff", 151 "hw_processor_count": 1, 152 "hw_product_uuid": "420cbebb-835b-980b-7050-8aea9b7b0a6d", 153 "hw_version": "vmx-13", 154 "instance_uuid": "500c60a6-b7b4-8ae5-970f-054905246a6f", 155 "ipv4": null, 156 "ipv6": null, 157 "module_hw": true, 158 "snapshots": [] 159 } 160 } 161 162confirming that you've renamed the virtual machine. 163 164 165Troubleshooting 166--------------- 167 168If your playbook fails: 169 170- Check if the values provided for username and password are correct. 171- Check if the datacenter you provided is available. 172- Check if the virtual machine specified exists and you have permissions to access the datastore. 173- Ensure the full folder path you specified already exists. 174