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 <akasurde@redhat.com>

* review comments

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

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.

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.

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.

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.

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.

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 <https://docs.ansible.com/ansible-tower/latest/html/userguide/credentials.html>`_.
+
+
+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.

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
 ===================
 

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
 ===============================

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
 ==========================

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

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.