From b6360dc5e068288dcdf9513dba732f1d823d1dfe Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Fri, 23 Oct 2020 20:14:12 +0530 Subject: [PATCH] VMware: scenario guide for vmware_tools connection plugin (#72080) * VMware: scenario guide for vmware_tools connection plugin Scenario doc to guide user about the usage of vmware_tools using connection plugin. Signed-off-by: Abhijeet Kasurde * review comments Signed-off-by: Abhijeet Kasurde --- .../scenario_clone_template.rst | 11 +- .../scenario_find_vm_folder.rst | 7 +- .../vmware_scenarios/scenario_remove_vm.rst | 7 +- .../vmware_scenarios/scenario_rename_vm.rst | 7 +- .../vmware_scenarios/scenario_vmware_http.rst | 7 +- .../scenario_vmware_tools_connection.rst | 120 ++++++++++++++++++ .../vmware_scenarios/vmware_intro.rst | 5 +- .../vmware_scenarios/vmware_inventory.rst | 3 +- .../vmware_inventory_vm_attributes.rst | 3 +- .../vmware_scenarios/vmware_scenarios.rst | 1 + .../vmware_troubleshooting.rst | 3 +- 11 files changed, 152 insertions(+), 22 deletions(-) create mode 100644 docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_tools_connection.rst diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst index 2c7647ef811..00820404ab8 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst @@ -4,14 +4,15 @@ Deploy a virtual machine from a template **************************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ This guide will show you how to utilize Ansible to clone a virtual machine from already existing VMware template or existing VMware guest. -Scenario Requirements +Scenario requirements ===================== * Software @@ -45,8 +46,8 @@ Scenario Requirements - ``VirtualMachine.Provisioning.Customize`` on the virtual machine or virtual machine folder if you are customizing the guest operating system - ``VirtualMachine.Provisioning.DeployTemplate`` on the template you are using - ``VirtualMachine.Provisioning.ReadCustSpecs`` on the root vCenter Server if you are customizing the guest operating system - - Depending on your requirements, you could also need one or more of the following privileges: + + Depending on your requirements, you could also need one or more of the following privileges: - ``VirtualMachine.Config.CPUCount`` on the datacenter or virtual machine folder - ``VirtualMachine.Config.Memory`` on the datacenter or virtual machine folder @@ -76,7 +77,7 @@ Caveats - In order to utilize Guest Customization, VMware Tools must be installed on the template. For Linux, the ``open-vm-tools`` package is recommended, and it requires that ``Perl`` be installed. -Example Description +Example description =================== In this use case / example, we will be selecting a virtual machine template and cloning it into a specific folder in our Datacenter / Cluster. The following Ansible playbook showcases the basic parameters that are needed for this. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst index 62758867c4d..a31dde32ddb 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst @@ -4,14 +4,15 @@ Find folder path of an existing VMware virtual machine ****************************************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ This guide will show you how to utilize Ansible to find folder path of an existing VMware virtual machine. -Scenario Requirements +Scenario requirements ===================== * Software @@ -41,7 +42,7 @@ Caveats - 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. -Example Description +Example description =================== With the following Ansible playbook you can find the folder path of an existing virtual machine using name. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst index 620f8e0aafe..35e863b1689 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst @@ -4,14 +4,15 @@ Remove an existing VMware virtual machine ***************************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ This guide will show you how to utilize Ansible to remove an existing VMware virtual machine. -Scenario Requirements +Scenario requirements ===================== * Software @@ -47,7 +48,7 @@ Caveats 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. -Example Description +Example description =================== In 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. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst index 812728979fd..7741d1b9210 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst @@ -4,14 +4,15 @@ Rename an existing virtual machine ********************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ This guide will show you how to utilize Ansible to rename an existing virtual machine. -Scenario Requirements +Scenario requirements ===================== * Software @@ -43,7 +44,7 @@ Caveats - 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. -Example Description +Example description =================== With the following Ansible playbook you can rename an existing virtual machine by changing the UUID. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst index e893c9d0458..3bd9be26e21 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst @@ -4,14 +4,15 @@ Using VMware HTTP API using Ansible *********************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ This guide will show you how to utilize Ansible to use VMware HTTP APIs to automate various tasks. -Scenario Requirements +Scenario requirements ===================== * Software @@ -40,7 +41,7 @@ Caveats - There are very limited number of APIs exposed, so you may need to rely on XMLRPC based VMware modules. -Example Description +Example description =================== With the following Ansible playbook you can find the VMware ESXi host system(s) and can perform various tasks depending on the list of host systems. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_tools_connection.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_tools_connection.rst new file mode 100644 index 00000000000..177516d2250 --- /dev/null +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_tools_connection.rst @@ -0,0 +1,120 @@ +.. _vmware_tools_connection: + +************************************ +Using vmware_tools connection plugin +************************************ + +.. contents:: + :local: + +Introduction +============ + +This guide will show you how to utilize VMware Connection plugin to communicate and automate various tasks on VMware guest machines. + +Scenario requirements +===================== + +* Software + + * Ansible 2.9 or later must be installed. + + * We recommend installing the latest version with pip: ``pip install Pyvmomi`` on the Ansible control node + (as the OS packages are usually out of date and incompatible) if you are planning to use any existing VMware modules. + +* Hardware + + * vCenter Server 6.5 and above + +* Access / Credentials + + * Ansible (or the target server) must have network access to either the vCenter server + + * Username and Password for vCenter with required permissions + + * VMware tools or openvm-tools with required dependencies like Perl installed on the given virtual machine + +Caveats +======= + +- All variable names and VMware object names are case sensitive. +- 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 behaviors. + + +Example description +=================== + +User can run playbooks against VMware virtual machines using ``vmware_tools`` connection plugin. + +In order work with ``vmware_tools`` connection plugin, you will need to specify hostvars for the given virtual machine. + +For example, if you want to run a playbook on a virtual machine called ``centos_7`` located at ``/Asia-Datacenter1/prod/centos_7`` in the given vCenter, you will need to specify hostvars as follows: + +.. code-block:: ini + + [centos7] + host1 + + [centos7:vars] + # vmware_tools related variables + ansible_connection=vmware_tools + ansible_vmware_host=10.65.201.128 + ansible_vmware_user=administrator@vsphere.local + ansible_vmware_password=Esxi@123$% + ansible_vmware_validate_certs=no + + # Location of the virtual machine + ansible_vmware_guest_path=Asia-Datacenter1/vm/prod/centos_7 + + # Credentials + ansible_vmware_tools_user=root + ansible_vmware_tools_password=Secret123 + +Here, we are providing vCenter details and credentials for the given virtual machine to run the playbook on. +If your virtual machine path is ``Asia-Datacenter1/prod/centos_7``, you specify ``ansible_vmware_guest_path`` as ``Asia-Datacenter1/vm/prod/centos_7``. Please take a note that ``/vm`` is added in the virtual machine path, since this is a logical folder structure in the VMware inventory. + +Let us now run following playbook, + +.. code-block:: yaml + + --- + - name: Example showing VMware Connection plugin + hosts: centos7 + tasks: + - name: Gather information about temporary directory inside VM + shell: ls /tmp + + +Since Ansible utilizes the ``vmware-tools`` or ``openvm-tools`` service capabilities running in the virtual machine to perform actions, in this use case it will be connecting directly to the guest machine. + + +For now, you will be entering credentials in plain text, 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 `_. + + +What to expect +-------------- + +Running this playbook can take some time, depending on your environment and network connectivity. When the run is complete you will see: + +.. code-block:: yaml + + { + "changed": true, + "cmd": "ls /tmp", + "delta": "0:00:00.005440", + "end": "2020-10-01 07:30:56.940813", + "rc": 0, + "start": "2020-10-01 07:30:56.935373", + "stderr": "", + "stderr_lines": [], + "stdout": "ansible_command_payload_JzWiL9\niso", + "stdout_lines": ["ansible_command_payload_JzWiL9", "iso", "vmware-root"] + } + +Troubleshooting +--------------- + +If your playbook fails: + +- Check if the values provided for username and password are correct. +- Check if the path of virtual machine is correct. Please mind that ``/vm/`` needs to be provided while specifying virtual machine location. diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst index 7006e66514e..1f6a0f0fd60 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst @@ -4,7 +4,8 @@ Introduction to Ansible for VMware ********************************** -.. contents:: Topics +.. contents:: + :local: Introduction ============ @@ -33,7 +34,7 @@ You can install vSphere Automation Python SDK using pip: Note: Installing vSphere Automation Python SDK also installs ``pyvmomi``. A separate installation of ``pyvmomi`` is not required. - + vmware_guest module =================== diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst index f942dd00ffd..1e41fd8dd9e 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst @@ -4,7 +4,8 @@ Using VMware dynamic inventory plugin ************************************* -.. contents:: Topics +.. contents:: + :local: VMware Dynamic Inventory Plugin =============================== diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst index 089c13d7e55..d88b045d22a 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst @@ -4,7 +4,8 @@ Using Virtual machine attributes in VMware dynamic inventory plugin ******************************************************************* -.. contents:: Topics +.. contents:: + :local: Virtual machine attributes ========================== diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst index b044740baf7..72fd03cd005 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst @@ -14,3 +14,4 @@ These scenarios teach you how to accomplish common VMware tasks using Ansible. T scenario_remove_vm scenario_find_vm_folder scenario_vmware_http + scenario_vmware_tools_connection diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst index 3ca5eac2842..08990e4a656 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst @@ -4,7 +4,8 @@ Troubleshooting Ansible for VMware ********************************** -.. contents:: Topics +.. contents:: + :local: This section lists things that can go wrong and possible ways to fix them.