vmware: Add docs for filters (#71670)

Add a scenario guide for filters in VMware documentation

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

docs/docsite/rst/scenario_guides/guide_vmware.rst

@@ -19,6 +19,7 @@ To get started, please select one of the following topics.
    vmware_scenarios/vmware_inventory
    vmware_scenarios/vmware_inventory_vm_attributes
    vmware_scenarios/vmware_inventory_hostnames
+   vmware_scenarios/vmware_inventory_filters
    vmware_scenarios/vmware_scenarios
    vmware_scenarios/vmware_troubleshooting
    vmware_scenarios/vmware_external_doc_links

docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_filters.rst

@@ -0,0 +1,216 @@
+.. _vmware_ansible_inventory_using_filters:
+
+***********************************************
+Using VMware dynamic inventory plugin - Filters
+***********************************************
+
+.. contents::
+  :local:
+
+VMware dynamic inventory plugin - filtering VMware guests
+=========================================================
+
+
+VMware inventory plugin allows you to filter VMware guests using the ``filters`` configuration parameter.
+
+This section shows how you configure ``filters`` for the given VMware guest in the inventory.
+
+Requirements
+------------
+
+To use the VMware dynamic inventory plugins, you must install `pyVmomi <https://github.com/vmware/pyvmomi>`_
+on your control node (the host running Ansible).
+
+To include tag-related information for the virtual machines in your dynamic inventory, you also need the `vSphere Automation SDK <https://code.vmware.com/web/sdk/65/vsphere-automation-python>`_, which supports REST API features such as tagging and content libraries, on your control node.
+You can install the ``vSphere Automation SDK`` following `these instructions <https://github.com/vmware/vsphere-automation-sdk-python#installing-required-python-packages>`_.
+
+.. code-block:: bash
+
+    $ pip install pyvmomi
+
+Starting in Ansible 2.10, the VMware dynamic inventory plugin is available in the ``community.vmware`` collection included Ansible.
+Alternately, to install the latest ``community.vmware`` collection:
+
+.. code-block:: bash
+
+    $ ansible-galaxy collection install community.vmware
+
+To use this VMware dynamic inventory plugin:
+
+1. Enable it first by specifying the following in the ``ansible.cfg`` file:
+
+.. code-block:: ini
+
+  [inventory]
+  enable_plugins = community.vmware.vmware_vm_inventory
+
+2. Create a file that ends in ``vmware.yml`` or ``vmware.yaml`` in your working directory.
+
+The ``vmware_vm_inventory`` inventory plugin takes in the same authentication information as any other VMware modules does.
+
+Let us assume we want to list all RHEL7 VMs with the power state as "poweredOn". A valid inventory file with filters for the given VMware guest looks as follows:
+
+.. code-block:: yaml
+
+    plugin: community.vmware.vmware_vm_inventory
+    strict: False
+    hostname: 10.65.223.31
+    username: administrator@vsphere.local
+    password: Esxi@123$%
+    validate_certs: False
+    with_tags: False
+    hostnames:
+    - config.name
+    filters:
+    - config.guestId == "rhel7_64Guest"
+    - summary.runtime.powerState == "poweredOn"
+
+
+Here, we have configured two filters -
+
+* ``config.guestId`` is equal to ``rhel7_64Guest``
+* ``summary.runtime.powerState`` is equal to ``poweredOn``
+
+This retrieves all the VMs which satisfy these two conditions and populates them in the inventory.
+Notice that the conditions are combined using an ``and`` operation.
+
+Using ``or`` conditions in filters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let us assume you want filter RHEL7 and Ubuntu VMs. You can use multiple filters using ``or`` condition in your inventory file.
+
+A valid filter in the VMware inventory file for this example is:
+
+.. code-block:: yaml
+
+    plugin: community.vmware.vmware_vm_inventory
+    strict: False
+    hostname: 10.65.223.31
+    username: administrator@vsphere.local
+    password: Esxi@123$%
+    validate_certs: False
+    with_tags: False
+    hostnames:
+    - config.name
+    filters:
+    - config.guestId == "rhel7_64Guest" or config.guestId == "ubuntu64Guest"
+
+
+You can check all allowed properties for filters for the given virtual machine at :ref:`vmware_inventory_vm_attributes`.
+
+If you are using the ``properties`` parameter with custom VM properties, make sure that you include all the properties used by filters as well in your VM property list.
+
+For example, if we want all RHEL7 and Ubuntu VMs that are poweredOn, you can use inventory file:
+
+.. code-block:: yaml
+
+    plugin: community.vmware.vmware_vm_inventory
+    strict: False
+    hostname: 10.65.223.31
+    username: administrator@vsphere.local
+    password: Esxi@123$%
+    validate_certs: False
+    with_tags: False
+    hostnames:
+    - 'config.name'
+    properties:
+    - 'config.name'
+    - 'config.guestId'
+    - 'guest.ipAddress'
+    - 'summary.runtime.powerState'
+    filters:
+    - config.guestId == "rhel7_64Guest" or config.guestId == "ubuntu64Guest"
+    - summary.runtime.powerState == "poweredOn"
+
+Here, we are using minimum VM properties, that is ``config.name``, ``config.guestId``, ``summary.runtime.powerState``, and ``guest.ipAddress``.
+
+* ``config.name`` is used by the ``hostnames`` parameter.
+* ``config.guestId`` and ``summary.runtime.powerState`` are used by the ``filters`` parameter.
+* ``guest.guestId`` is used by ``ansible_host`` internally by the inventory plugin.
+
+Using regular expression in filters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Let us assume you want filter VMs with specific IP range. You can use regular expression in ``filters`` in your inventory file.
+
+For example, if we want all RHEL7 and Ubuntu VMs that are poweredOn, you can use inventory file:
+
+.. code-block:: yaml
+
+    plugin: community.vmware.vmware_vm_inventory
+    strict: False
+    hostname: 10.65.223.31
+    username: administrator@vsphere.local
+    password: Esxi@123$%
+    validate_certs: False
+    with_tags: False
+    hostnames:
+    - 'config.name'
+    properties:
+    - 'config.name'
+    - 'config.guestId'
+    - 'guest.ipAddress'
+    - 'summary.runtime.powerState'
+    filters:
+    - guest.ipAddress is defined and guest.ipAddress is match('192.168.*')
+
+Here, we are using ``guest.ipAddress`` VM property. This property is optional and depended upon VMware tools installed on VMs.
+We are using ``match`` to validate the regular expression for the given IP range.
+
+Executing ``ansible-inventory --list -i <filename>.vmware.yml`` creates a list of the virtual machines that are ready to be configured using Ansible.
+
+What to expect
+--------------
+
+You will notice that the inventory hosts are filtered depending on your ``filters`` section.
+
+
+.. code-block:: yaml
+
+    {
+      "_meta": {
+        "hostvars": {
+            "template_001": {
+                "config.name": "template_001",
+                "config.guestId": "ubuntu64Guest",
+                ...
+                "guest.toolsStatus": "toolsNotInstalled",
+                "summary.runtime.powerState": "poweredOn",
+            },
+            "vm_8046": {
+                "config.name": "vm_8046",
+                "config.guestId": "rhel7_64Guest",
+                ...
+                "guest.toolsStatus": "toolsNotInstalled",
+                "summary.runtime.powerState": "poweredOn",
+            },
+        ...
+    }
+
+Troubleshooting filters
+-----------------------
+
+If the custom property specified in ``filters`` fails:
+
+- Check if the values provided for username and password are correct.
+- Make sure it is a valid property, see :ref:`vmware_inventory_vm_attributes`.
+- Use ``strict: True`` to get more information about the error.
+- Please make sure that you are using latest version of the VMware collection.
+
+
+.. seealso::
+
+    `pyVmomi <https://github.com/vmware/pyvmomi>`_
+        The GitHub Page of pyVmomi
+    `pyVmomi Issue Tracker <https://github.com/vmware/pyvmomi/issues>`_
+        The issue tracker for the pyVmomi project
+    `vSphere Automation SDK GitHub Page <https://github.com/vmware/vsphere-automation-sdk-python>`_
+        The GitHub Page of vSphere Automation SDK for Python
+    `vSphere Automation SDK Issue Tracker <https://github.com/vmware/vsphere-automation-sdk-python/issues>`_
+        The issue tracker for vSphere Automation SDK for Python
+    :ref:`vmware_inventory_vm_attributes`
+        Using Virtual machine attributes in VMware dynamic inventory plugin
+    :ref:`working_with_playbooks`
+        An introduction to playbooks
+    :ref:`playbooks_vault`
+        Using Vault in playbooks

docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst

@@ -4,9 +4,10 @@
 Using VMware dynamic inventory plugin - Hostnames
 *************************************************
 
-.. contents:: Topics
+.. contents::
+  :local:
 
-VMware dynamic inventory plugin - Customizing hostnames
+VMware dynamic inventory plugin - customizing hostnames
 =======================================================
 
 
@@ -36,14 +37,14 @@ To install the latest ``community.vmware`` collection:
 
 To use this VMware dynamic inventory plugin:
 
- 1. Enable it first by specifying the following in the ``ansible.cfg`` file:
+1. Enable it first by specifying the following in the ``ansible.cfg`` file:
 
 .. code-block:: ini
 
   [inventory]
   enable_plugins = community.vmware.vmware_vm_inventory
 
- 2. Create a file that ends in ``.vmware.yml`` or ``.vmware.yaml`` in your working directory.
+2. Create a file that ends in ``vmware.yml`` or ``vmware.yaml`` in your working directory.
 
 The ``vmware_vm_inventory`` inventory plugin takes in the same authentication information as any other VMware modules does.
 
@@ -67,7 +68,7 @@ the ``config.name`` property from the virtual machine and populate it in the inv
 
 You can check all allowed properties for the given virtual machine at :ref:`vmware_inventory_vm_attributes`.
 
-Executing ``ansible-inventory --list -i <filename>.vmware.yml`` will create a list of the virtual machines that are ready to be configured using Ansible.
+Executing ``ansible-inventory --list -i <filename>.vmware.yml`` creates a list of the virtual machines that are ready to be configured using Ansible.
 
 What to expect
 --------------