1.. _vmware_guest_remove_virtual_machine: 2 3***************************************** 4Remove an existing VMware virtual machine 5***************************************** 6 7.. contents:: Topics 8 9Introduction 10============ 11 12This guide will show you how to utilize Ansible to remove an existing VMware 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- ``vmware_guest`` module tries to mimic VMware Web UI and workflow, so the virtual machine must be in powered off state in order to remove it from the VMware inventory. 45 46.. warning:: 47 48 The removal VMware virtual machine using ``vmware_guest`` module is destructive operation and can not be reverted, so it is strongly recommended to take the backup of virtual machine and related files (vmx and vmdk files) before proceeding. 49 50Example Description 51=================== 52 53In this use case / example, user will be removing a virtual machine using name. The following Ansible playbook showcases the basic parameters that are needed for this. 54 55.. code-block:: yaml 56 57 --- 58 - name: Remove virtual machine 59 gather_facts: no 60 vars_files: 61 - vcenter_vars.yml 62 vars: 63 ansible_python_interpreter: "/usr/bin/env python3" 64 hosts: localhost 65 tasks: 66 - set_fact: 67 vm_name: "VM_0003" 68 datacenter: "DC1" 69 70 - name: Remove "{{ vm_name }}" 71 vmware_guest: 72 hostname: "{{ vcenter_server }}" 73 username: "{{ vcenter_user }}" 74 password: "{{ vcenter_pass }}" 75 validate_certs: no 76 cluster: "DC1_C1" 77 name: "{{ vm_name }}" 78 state: absent 79 delegate_to: localhost 80 register: facts 81 82 83Since Ansible utilizes the VMware API to perform actions, in this use case it will be connecting directly to the API from localhost. 84 85This means that playbooks will not be running from the vCenter or ESXi Server. 86 87Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost. 88 89You 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). 90 91Before you begin, make sure you have: 92 93- Hostname of the ESXi server or vCenter server 94- Username and password for the ESXi or vCenter server 95- Name of the existing Virtual Machine you want to remove 96 97For 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>`_. 98 99If 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. 100 101The name of existing virtual machine will be used as input for ``vmware_guest`` module via ``name`` parameter. 102 103 104What to expect 105-------------- 106 107- You will not see any JSON output after this playbook completes as compared to other operations performed using ``vmware_guest`` module. 108 109.. code-block:: yaml 110 111 { 112 "changed": true 113 } 114 115- State is changed to ``True`` which notifies that the virtual machine is removed from the VMware inventory. This can take some time depending upon your environment and network connectivity. 116 117 118Troubleshooting 119--------------- 120 121If your playbook fails: 122 123- Check if the values provided for username and password are correct. 124- Check if the datacenter you provided is available. 125- Check if the virtual machine specified exists and you have permissions to access the datastore. 126- Ensure the full folder path you specified already exists. It will not create folders automatically for you. 127