From 0055673c704afd555053d6e2239ac2666ad60e56 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 5 Aug 2020 00:00:33 +0530 Subject: [PATCH] VMware: Inventory scenario guide for hostnames (#71055) Added a scenario guide for ``hostnames`` parameter for vmware_vm_inventory. Signed-off-by: Abhijeet Kasurde --- .../rst/scenario_guides/guide_vmware.rst | 1 + .../vmware_inventory_hostnames.rst | 127 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst diff --git a/docs/docsite/rst/scenario_guides/guide_vmware.rst b/docs/docsite/rst/scenario_guides/guide_vmware.rst index 92e458b75f0..3a257e0b36b 100644 --- a/docs/docsite/rst/scenario_guides/guide_vmware.rst +++ b/docs/docsite/rst/scenario_guides/guide_vmware.rst @@ -18,6 +18,7 @@ To get started, please select one of the following topics. vmware_scenarios/vmware_requirements vmware_scenarios/vmware_inventory vmware_scenarios/vmware_inventory_vm_attributes + vmware_scenarios/vmware_inventory_hostnames vmware_scenarios/vmware_scenarios vmware_scenarios/vmware_troubleshooting vmware_scenarios/vmware_external_doc_links diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst new file mode 100644 index 00000000000..ac8dfaf1bcc --- /dev/null +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst @@ -0,0 +1,127 @@ +.. _vmware_ansible_inventory_using_hostnames: + +************************************************* +Using VMware dynamic inventory plugin - Hostnames +************************************************* + +.. contents:: Topics + +VMware dynamic inventory plugin - Customizing hostnames +======================================================= + + +VMware inventory plugin allows you to configure hostnames using the ``hostnames`` configuration parameter. + +In this scenario guide we will see how you configure hostnames from the given VMware guest in the inventory. + +Requirements +------------ + +To use the VMware dynamic inventory plugins, you must install `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 `_, 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 `_. + +.. 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. +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. + +Here's an example of a valid inventory file with custom hostname for the given VMware guest: + +.. 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 + + +Here, we have configured a custom hostname by setting the ``hostnames`` parameter to ``config.name``. This will retrieve +the ``config.name`` property from the virtual machine and populate it in the inventory. + +You can check all allowed properties for the given virtual machine at :ref:`vmware_inventory_vm_attributes`. + +Executing ``ansible-inventory --list -i .vmware.yml`` will create a list of the virtual machines that are ready to be configured using Ansible. + +What to expect +-------------- + +You will notice that instead of default behavior of representing the hostname as ``config.name + _ + config.uuid``, +the inventory hosts show value as ``config.name``. + + +.. code-block:: yaml + + { + "_meta": { + "hostvars": { + "template_001": { + "config.name": "template_001", + "guest.toolsRunningStatus": "guestToolsNotRunning", + ... + "guest.toolsStatus": "toolsNotInstalled", + "name": "template_001" + }, + "vm_8046": { + "config.name": "vm_8046", + "guest.toolsRunningStatus": "guestToolsNotRunning", + ... + "guest.toolsStatus": "toolsNotInstalled", + "name": "vm_8046" + }, + ... + } + +Troubleshooting +--------------- + +If the custom property specified in ``hostnames`` 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 VMware collection. + + +.. seealso:: + + `pyVmomi `_ + The GitHub Page of pyVmomi + `pyVmomi Issue Tracker `_ + The issue tracker for the pyVmomi project + `vSphere Automation SDK GitHub Page `_ + The GitHub Page of vSphere Automation SDK for Python + `vSphere Automation SDK Issue Tracker `_ + 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