archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

vmware: Migrate VMware Scenario Guides (#76640)

Browse Source 
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
pull/76946/head
Abhijeet Kasurde 4 years ago committed by GitHub
parent 0ca19a5b73
commit a1af1d94cd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 2 additions and 2919 deletions
Show Stats Download Patch File Download Diff File

2
changelogs/fragments/vmware_sceanrio.yml
Unescape Escape View File

@ -0,0 +1,2 @@
minor_changes:
- vmware - migrated vmware scenario guides to `community.vmware` repo.

33
docs/docsite/rst/scenario_guides/guide_vmware.rst
Unescape Escape View File

@ -1,33 +0,0 @@
.. _vmware_ansible:
************
VMware Guide
************
Welcome to the Ansible for VMware Guide!
The purpose of this guide is to teach you everything you need to know about using Ansible with VMware.
To get started, please select one of the following topics.
.. toctree::
:maxdepth: 1
vmware_scenarios/vmware_intro
vmware_scenarios/vmware_concepts
vmware_scenarios/vmware_requirements
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
vmware_scenarios/faq
.. comments look like this - start with two dots
.. getting_started content not ready
.. vmware_scenarios/vmware_getting_started
.. module index page not ready
.. vmware_scenarios/vmware_module_reference
.. always exclude the template file
.. vmware_scenarios/vmware_scenario_1

1
docs/docsite/rst/scenario_guides/guides.rst
Unescape Escape View File

@ -42,4 +42,3 @@ We are migrating these guides into collections. Please update your links for the
:caption: Virtualization & Containerization Guides
guide_vagrant
guide_vmware

1
docs/docsite/rst/scenario_guides/virt_guides.rst
Unescape Escape View File

@ -11,5 +11,4 @@ The guides in this section cover integrating Ansible with popular tools for crea
guide_docker
guide_vagrant
guide_vmware
guide_vmware_rest

26
docs/docsite/rst/scenario_guides/vmware_scenarios/faq.rst
Unescape Escape View File

@ -1,26 +0,0 @@
.. _vmware_faq:
******************
Ansible VMware FAQ
******************
vmware_guest
============
Can I deploy a virtual machine on a standalone ESXi server ?
------------------------------------------------------------
Yes. ``vmware_guest`` can deploy a virtual machine with required settings on a standalone ESXi server.
However, you must have a paid license to deploy virtual machines this way. If you are using the free version, the API is read-only.
Is ``/vm`` required for ``vmware_guest`` module ?
-------------------------------------------------
Prior to Ansible version 2.5, ``folder`` was an optional parameter with a default value of ``/vm``.
The folder parameter was used to discover information about virtual machines in the given infrastructure.
Starting with Ansible version 2.5, ``folder`` is still an optional parameter with no default value.
This parameter will be now used to identify a user's virtual machine, if multiple virtual machines or virtual
machine templates are found with same name. VMware does not restrict the system administrator from creating virtual
machines with same name.

223
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_clone_template.rst
Unescape Escape View File

@ -1,223 +0,0 @@
.. _vmware_guest_from_template:
****************************************
Deploy a virtual machine from a template
****************************************
.. 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
=====================
* Software
* Ansible 2.5 or later must be installed
* The Python module ``Pyvmomi`` must be installed on the Ansible (or Target host if not executing against localhost)
* Installing the latest ``Pyvmomi`` via ``pip`` is recommended [as the OS provided packages are usually out of date and incompatible]
* Hardware
* vCenter Server with at least one ESXi server
* Access / Credentials
* Ansible (or the target server) must have network access to the either vCenter server or the ESXi server you will be deploying to
* Username and Password
* Administrator user with following privileges
- ``Datastore.AllocateSpace`` on the destination datastore or datastore folder
- ``Network.Assign`` on the network to which the virtual machine will be assigned
- ``Resource.AssignVMToPool`` on the destination host, cluster, or resource pool
- ``VirtualMachine.Config.AddNewDisk`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.AddRemoveDevice`` on the datacenter or virtual machine folder
- ``VirtualMachine.Interact.PowerOn`` on the datacenter or virtual machine folder
- ``VirtualMachine.Inventory.CreateFromExisting`` on the datacenter or virtual machine folder
- ``VirtualMachine.Provisioning.Clone`` on the virtual machine you are cloning
- ``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:
- ``VirtualMachine.Config.CPUCount`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.Memory`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.DiskExtend`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.Annotation`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.AdvancedConfig`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.EditDevice`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.Resource`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.Settings`` on the datacenter or virtual machine folder
- ``VirtualMachine.Config.UpgradeVirtualHardware`` on the datacenter or virtual machine folder
- ``VirtualMachine.Interact.SetCDMedia`` on the datacenter or virtual machine folder
- ``VirtualMachine.Interact.SetFloppyMedia`` on the datacenter or virtual machine folder
- ``VirtualMachine.Interact.DeviceConnection`` on the datacenter or virtual machine folder
Assumptions
===========
- All variable names and VMware object names are case sensitive
- VMware allows creation of virtual machine and templates with same name across datacenters and within datacenters
- 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
Caveats
=======
- Hosts in the ESXi cluster must have access to the datastore that the template resides on.
- Multiple templates with the same name will cause module failures.
- 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
===================
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.
.. code-block:: yaml
---
- name: Create a VM from a template
hosts: localhost
gather_facts: no
tasks:
- name: Clone the template
vmware_guest:
hostname: "{{ vcenter_ip }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
validate_certs: False
name: testvm_2
template: template_el7
datacenter: "{{ datacenter_name }}"
folder: /DC1/vm
state: poweredon
cluster: "{{ cluster_name }}"
wait_for_ip_address: yes
Since Ansible utilizes the VMware API to perform actions, in this use case we will be connecting directly to the API from our localhost. This means that our playbooks will not be running from the vCenter or ESXi Server. We do not necessarily need to collect facts about our localhost, so the ``gather_facts`` parameter will be disabled. You can run these modules against another server that would then connect to the API if your localhost does not have access to vCenter. If so, the required Python modules will need to be installed on that target server.
To begin, there are a few bits of information we will need. First and foremost is the hostname of the ESXi server or vCenter server. After this, you will need the username and password for this server. For 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>`_. If 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.
Now you need to supply the information about the virtual machine which will be created. Give your virtual machine a name, one that conforms to all VMware requirements for naming conventions. Next, select the display name of the template from which you want to clone new virtual machine. This must match what's displayed in VMware Web UI exactly. Then you can specify a folder to place this new virtual machine in. This path can either be a relative path or a full path to the folder including the Datacenter. You may need to specify a state for the virtual machine. This simply tells the module which action you want to take, in this case you will be ensure that the virtual machine exists and is powered on. An optional parameter is ``wait_for_ip_address``, this will tell Ansible to wait for the virtual machine to fully boot up and VMware Tools is running before completing this task.
What to expect
--------------
- You will see a bit of JSON output after this playbook completes. This output shows various parameters that are returned from the module and from vCenter about the newly created VM.
.. code-block:: yaml
{
"changed": true,
"instance": {
"annotation": "",
"current_snapshot": null,
"customvalues": {},
"guest_consolidation_needed": false,
"guest_question": null,
"guest_tools_status": "guestToolsNotRunning",
"guest_tools_version": "0",
"hw_cores_per_socket": 1,
"hw_datastores": [
"ds_215"
],
"hw_esxi_host": "192.0.2.44",
"hw_eth0": {
"addresstype": "assigned",
"ipaddresses": null,
"label": "Network adapter 1",
"macaddress": "00:50:56:8c:19:f4",
"macaddress_dash": "00-50-56-8c-19-f4",
"portgroup_key": "dvportgroup-17",
"portgroup_portkey": "0",
"summary": "DVSwitch: 50 0c 5b 22 b6 68 ab 89-fc 0b 59 a4 08 6e 80 fa"
},
"hw_files": [
"[ds_215] testvm_2/testvm_2.vmx",
"[ds_215] testvm_2/testvm_2.vmsd",
"[ds_215] testvm_2/testvm_2.vmdk"
],
"hw_folder": "/DC1/vm",
"hw_guest_full_name": null,
"hw_guest_ha_state": null,
"hw_guest_id": null,
"hw_interfaces": [
"eth0"
],
"hw_is_template": false,
"hw_memtotal_mb": 512,
"hw_name": "testvm_2",
"hw_power_status": "poweredOff",
"hw_processor_count": 2,
"hw_product_uuid": "420cb25b-81e8-8d3b-dd2d-a439ee54fcc5",
"hw_version": "vmx-13",
"instance_uuid": "500cd53b-ed57-d74e-2da8-0dc0eddf54d5",
"ipv4": null,
"ipv6": null,
"module_hw": true,
"snapshots": []
},
"invocation": {
"module_args": {
"annotation": null,
"cdrom": {},
"cluster": "DC1_C1",
"customization": {},
"customization_spec": null,
"customvalues": [],
"datacenter": "DC1",
"disk": [],
"esxi_hostname": null,
"folder": "/DC1/vm",
"force": false,
"guest_id": null,
"hardware": {},
"hostname": "192.0.2.44",
"is_template": false,
"linked_clone": false,
"name": "testvm_2",
"name_match": "first",
"networks": [],
"password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
"port": 443,
"resource_pool": null,
"snapshot_src": null,
"state": "present",
"state_change_timeout": 0,
"template": "template_el7",
"username": "administrator@vsphere.local",
"uuid": null,
"validate_certs": false,
"vapp_properties": [],
"wait_for_ip_address": true
}
}
}
- State is changed to ``True`` which notifies that the virtual machine is built using given template. The module will not complete until the clone task in VMware is finished. This can take some time depending on your environment.
- If you utilize the ``wait_for_ip_address`` parameter, then it will also increase the clone time as it will wait until virtual machine boots into the OS and an IP Address has been assigned to the given NIC.
Troubleshooting
---------------
Things to inspect
- Check if the values provided for username and password are correct
- Check if the datacenter you provided is available
- Check if the template specified exists and you have permissions to access the datastore
- Ensure the full folder path you specified already exists. It will not create folders automatically for you

121
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_find_vm_folder.rst
Unescape Escape View File

@ -1,121 +0,0 @@
.. _vmware_guest_find_folder:
******************************************************
Find folder path of an existing VMware virtual machine
******************************************************
.. contents::
:local:
Introduction
============
This guide will show you how to utilize Ansible to find folder path of an existing VMware virtual machine.
Scenario requirements
=====================
* Software
* Ansible 2.5 or later must be installed.
* The Python module ``Pyvmomi`` must be installed on the Ansible control node (or Target host if not executing against localhost).
* We recommend installing the latest version with pip: ``pip install Pyvmomi`` (as the OS packages are usually out of date and incompatible).
* Hardware
* At least one standalone ESXi server or
* vCenter Server with at least one ESXi server
* Access / Credentials
* Ansible (or the target server) must have network access to the either vCenter server or the ESXi server
* Username and Password for vCenter or ESXi server
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 behaviours.
Example description
===================
With the following Ansible playbook you can find the folder path of an existing virtual machine using name.
.. code-block:: yaml
---
- name: Find folder path of an existing virtual machine
hosts: localhost
gather_facts: False
vars_files:
- vcenter_vars.yml
vars:
ansible_python_interpreter: "/usr/bin/env python3"
tasks:
- set_fact:
vm_name: "DC0_H0_VM0"
- name: "Find folder for VM - {{ vm_name }}"
vmware_guest_find:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
validate_certs: False
name: "{{ vm_name }}"
delegate_to: localhost
register: vm_facts
Since Ansible utilizes the VMware API to perform actions, in this use case it will be connecting directly to the API from localhost.
This means that playbooks will not be running from the vCenter or ESXi Server.
Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost.
You 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).
Before you begin, make sure you have:
- Hostname of the ESXi server or vCenter server
- Username and password for the ESXi or vCenter server
- Name of the existing Virtual Machine for which you want to collect folder path
For 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>`_.
If 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.
The name of existing virtual machine will be used as input for ``vmware_guest_find`` module via ``name`` parameter.
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
"vm_facts": {
"changed": false,
"failed": false,
...
"folders": [
"/F0/DC0/vm/F0"
]
}
Troubleshooting
---------------
If your playbook fails:
- Check if the values provided for username and password are correct.
- Check if the datacenter you provided is available.
- Check if the virtual machine specified exists and you have respective permissions to access VMware object.
- Ensure the full folder path you specified already exists.

127
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst
Unescape Escape View File

@ -1,127 +0,0 @@
.. _vmware_guest_remove_virtual_machine:
*****************************************
Remove an existing VMware virtual machine
*****************************************
.. contents::
:local:
Introduction
============
This guide will show you how to utilize Ansible to remove an existing VMware virtual machine.
Scenario requirements
=====================
* Software
* Ansible 2.5 or later must be installed.
* The Python module ``Pyvmomi`` must be installed on the Ansible control node (or Target host if not executing against localhost).
* We recommend installing the latest version with pip: ``pip install Pyvmomi`` (as the OS packages are usually out of date and incompatible).
* Hardware
* At least one standalone ESXi server or
* vCenter Server with at least one ESXi server
* Access / Credentials
* Ansible (or the target server) must have network access to the either vCenter server or the ESXi server
* Username and Password for vCenter or ESXi server
* Hosts in the ESXi cluster must have access to the datastore that the template resides on.
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 behaviours.
- ``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.
.. warning::
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
===================
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.
.. code-block:: yaml
---
- name: Remove virtual machine
gather_facts: no
vars_files:
- vcenter_vars.yml
vars:
ansible_python_interpreter: "/usr/bin/env python3"
hosts: localhost
tasks:
- set_fact:
vm_name: "VM_0003"
datacenter: "DC1"
- name: Remove "{{ vm_name }}"
vmware_guest:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
validate_certs: no
cluster: "DC1_C1"
name: "{{ vm_name }}"
state: absent
delegate_to: localhost
register: facts
Since Ansible utilizes the VMware API to perform actions, in this use case it will be connecting directly to the API from localhost.
This means that playbooks will not be running from the vCenter or ESXi Server.
Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost.
You 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).
Before you begin, make sure you have:
- Hostname of the ESXi server or vCenter server
- Username and password for the ESXi or vCenter server
- Name of the existing Virtual Machine you want to remove
For 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>`_.
If 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.
The name of existing virtual machine will be used as input for ``vmware_guest`` module via ``name`` parameter.
What to expect
--------------
- You will not see any JSON output after this playbook completes as compared to other operations performed using ``vmware_guest`` module.
.. code-block:: yaml
{
"changed": true
}
- 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.
Troubleshooting
---------------
If your playbook fails:
- Check if the values provided for username and password are correct.
- Check if the datacenter you provided is available.
- Check if the virtual machine specified exists and you have permissions to access the datastore.
- Ensure the full folder path you specified already exists. It will not create folders automatically for you.

174
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_rename_vm.rst
Unescape Escape View File

@ -1,174 +0,0 @@
.. _vmware_guest_rename_virtual_machine:
**********************************
Rename an existing virtual machine
**********************************
.. contents::
:local:
Introduction
============
This guide will show you how to utilize Ansible to rename an existing virtual machine.
Scenario requirements
=====================
* Software
* Ansible 2.5 or later must be installed.
* The Python module ``Pyvmomi`` must be installed on the Ansible control node (or Target host if not executing against localhost).
* We recommend installing the latest version with pip: ``pip install Pyvmomi`` (as the OS packages are usually out of date and incompatible).
* Hardware
* At least one standalone ESXi server or
* vCenter Server with at least one ESXi server
* Access / Credentials
* Ansible (or the target server) must have network access to the either vCenter server or the ESXi server
* Username and Password for vCenter or ESXi server
* Hosts in the ESXi cluster must have access to the datastore that the template resides on.
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 behaviours.
Example description
===================
With the following Ansible playbook you can rename an existing virtual machine by changing the UUID.
.. code-block:: yaml
---
- name: Rename virtual machine from old name to new name using UUID
gather_facts: no
vars_files:
- vcenter_vars.yml
vars:
ansible_python_interpreter: "/usr/bin/env python3"
hosts: localhost
tasks:
- set_fact:
vm_name: "old_vm_name"
new_vm_name: "new_vm_name"
datacenter: "DC1"
cluster_name: "DC1_C1"
- name: Get VM "{{ vm_name }}" uuid
vmware_guest_facts:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
validate_certs: False
datacenter: "{{ datacenter }}"
folder: "/{{datacenter}}/vm"
name: "{{ vm_name }}"
register: vm_facts
- name: Rename "{{ vm_name }}" to "{{ new_vm_name }}"
vmware_guest:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
validate_certs: False
cluster: "{{ cluster_name }}"
uuid: "{{ vm_facts.instance.hw_product_uuid }}"
name: "{{ new_vm_name }}"
Since Ansible utilizes the VMware API to perform actions, in this use case it will be connecting directly to the API from localhost.
This means that playbooks will not be running from the vCenter or ESXi Server.
Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost.
You 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).
Before you begin, make sure you have:
- Hostname of the ESXi server or vCenter server
- Username and password for the ESXi or vCenter server
- The UUID of the existing Virtual Machine you want to rename
For 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>`_.
If 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.
Now you need to supply the information about the existing virtual machine which will be renamed. For renaming virtual machine, ``vmware_guest`` module uses VMware UUID, which is unique across vCenter environment. This value is autogenerated and can not be changed. You will use ``vmware_guest_facts`` module to find virtual machine and get information about VMware UUID of the virtual machine.
This value will be used input for ``vmware_guest`` module. Specify new name to virtual machine which conforms to all VMware requirements for naming conventions as ``name`` parameter. Also, provide ``uuid`` as the value of VMware UUID.
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,
"instance": {
"annotation": "",
"current_snapshot": null,
"customvalues": {},
"guest_consolidation_needed": false,
"guest_question": null,
"guest_tools_status": "guestToolsNotRunning",
"guest_tools_version": "10247",
"hw_cores_per_socket": 1,
"hw_datastores": ["ds_204_2"],
"hw_esxi_host": "10.x.x.x",
"hw_eth0": {
"addresstype": "assigned",
"ipaddresses": [],
"label": "Network adapter 1",
"macaddress": "00:50:56:8c:b8:42",
"macaddress_dash": "00-50-56-8c-b8-42",
"portgroup_key": "dvportgroup-31",
"portgroup_portkey": "15",
"summary": "DVSwitch: 50 0c 3a 69 df 78 2c 7b-6e 08 0a 89 e3 a6 31 17"
},
"hw_files": ["[ds_204_2] old_vm_name/old_vm_name.vmx", "[ds_204_2] old_vm_name/old_vm_name.nvram", "[ds_204_2] old_vm_name/old_vm_name.vmsd", "[ds_204_2] old_vm_name/vmware.log", "[ds_204_2] old_vm_name/old_vm_name.vmdk"],
"hw_folder": "/DC1/vm",
"hw_guest_full_name": null,
"hw_guest_ha_state": null,
"hw_guest_id": null,
"hw_interfaces": ["eth0"],
"hw_is_template": false,
"hw_memtotal_mb": 1024,
"hw_name": "new_vm_name",
"hw_power_status": "poweredOff",
"hw_processor_count": 1,
"hw_product_uuid": "420cbebb-835b-980b-7050-8aea9b7b0a6d",
"hw_version": "vmx-13",
"instance_uuid": "500c60a6-b7b4-8ae5-970f-054905246a6f",
"ipv4": null,
"ipv6": null,
"module_hw": true,
"snapshots": []
}
}
confirming that you've renamed the virtual machine.
Troubleshooting
---------------
If your playbook fails:
- Check if the values provided for username and password are correct.
- Check if the datacenter you provided is available.
- Check if the virtual machine specified exists and you have permissions to access the datastore.
- Ensure the full folder path you specified already exists.

162
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst
Unescape Escape View File

@ -1,162 +0,0 @@
.. _vmware_http_api_usage:
***********************************
Using VMware HTTP API using Ansible
***********************************
.. contents::
:local:
Introduction
============
This guide will show you how to utilize Ansible to use VMware HTTP APIs to automate various tasks.
Scenario requirements
=====================
* Software
* Ansible 2.5 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 with at least one ESXi server
* Access / Credentials
* Ansible (or the target server) must have network access to either the vCenter server or the ESXi server
* Username and Password for vCenter
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 behaviours.
- VMware HTTP APIs are introduced in vSphere 6.5 and above so minimum level required in 6.5.
- There are very limited number of APIs exposed, so you may need to rely on XMLRPC based VMware modules.
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.
This is a generic example to show how Ansible can be utilized to consume VMware HTTP APIs.
.. code-block:: yaml
---
- name: Example showing VMware HTTP API utilization
hosts: localhost
gather_facts: no
vars_files:
- vcenter_vars.yml
vars:
ansible_python_interpreter: "/usr/bin/env python3"
tasks:
- name: Login into vCenter and get cookies
uri:
url: https://{{ vcenter_server }}/rest/com/vmware/cis/session
force_basic_auth: yes
validate_certs: no
method: POST
user: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
register: login
- name: Get all hosts from vCenter using cookies from last task
uri:
url: https://{{ vcenter_server }}/rest/vcenter/host
force_basic_auth: yes
validate_certs: no
headers:
Cookie: "{{ login.set_cookie }}"
register: vchosts
- name: Change Log level configuration of the given hostsystem
vmware_host_config_manager:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
esxi_hostname: "{{ item.name }}"
options:
'Config.HostAgent.log.level': 'error'
validate_certs: no
loop: "{{ vchosts.json.value }}"
register: host_config_results
Since Ansible utilizes the VMware HTTP API using the ``uri`` module to perform actions, in this use case it will be connecting directly to the VMware HTTP API from localhost.
This means that playbooks will not be running from the vCenter or ESXi Server.
Note that this play disables the ``gather_facts`` parameter, since you don't want to collect facts about localhost.
Before you begin, make sure you have:
- Hostname of the vCenter server
- Username and password for the vCenter server
- Version of vCenter is at least 6.5
For 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>`_.
If your vCenter 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.
As you can see, we are using the ``uri`` module in first task to login into the vCenter server and storing result in the ``login`` variable using register. In the second task, using cookies from the first task we are gathering information about the ESXi host system.
Using this information, we are changing the ESXi host system's advance configuration.
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
"results": [
{
...
"invocation": {
"module_args": {
"cluster_name": null,
"esxi_hostname": "10.76.33.226",
"hostname": "10.65.223.114",
"options": {
"Config.HostAgent.log.level": "error"
},
"password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
"port": 443,
"username": "administrator@vsphere.local",
"validate_certs": false
}
},
"item": {
"connection_state": "CONNECTED",
"host": "host-21",
"name": "10.76.33.226",
"power_state": "POWERED_ON"
},
"msg": "Config.HostAgent.log.level changed."
...
}
]
Troubleshooting
---------------
If your playbook fails:
- Check if the values provided for username and password are correct.
- Check if you are using vCenter 6.5 and onwards to use this HTTP APIs.
.. seealso::
`VMware vSphere and Ansible From Zero to Useful by @arielsanchezmor <https://www.youtube.com/watch?v=0_qwOKlBlo8>`_
vBrownBag session video related to VMware HTTP APIs
`Sample Playbooks for using VMware HTTP APIs <https://github.com/Akasurde/ansible-vmware-http>`_
GitHub repo for examples of Ansible playbook to manage VMware using HTTP APIs

120
docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_tools_connection.rst
Unescape Escape View File

@ -1,120 +0,0 @@
.. _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.

45
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_concepts.rst
Unescape Escape View File

@ -1,45 +0,0 @@
.. _vmware_concepts:
***************************
Ansible for VMware Concepts
***************************
Some of these concepts are common to all uses of Ansible, including VMware automation; some are specific to VMware. You need to understand them to use Ansible for VMware automation. This introduction provides the background you need to follow the :ref:`scenarios<vmware_scenarios>` in this guide.
.. contents::
:local:
Control Node
============
Any machine with Ansible installed. You can run commands and playbooks, invoking ``/usr/bin/ansible`` or ``/usr/bin/ansible-playbook``, from any control node. You can use any computer that has Python installed on it as a control node - laptops, shared desktops, and servers can all run Ansible. However, you cannot use a Windows machine as a control node. You can have multiple control nodes.
Delegation
==========
Delegation allows you to select the system that executes a given task. If you do not have ``pyVmomi`` installed on your control node, use the ``delegate_to`` keyword on VMware-specific tasks to execute them on any host where you have ``pyVmomi`` installed.
Modules
=======
The units of code Ansible executes. Each module has a particular use, from creating virtual machines on vCenter to managing distributed virtual switches in the vCenter environment. You can invoke a single module with a task, or invoke several different modules in a playbook. For an idea of how many modules Ansible includes, take a look at the :ref:`list of cloud modules<cloud_modules>`, which includes VMware modules.
Playbooks
=========
Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks can include variables as well as tasks. Playbooks are written in YAML and are easy to read, write, share and understand.
pyVmomi
=======
Ansible VMware modules are written on top of `pyVmomi <https://github.com/vmware/pyvmomi>`_. ``pyVmomi`` is the official Python SDK for the VMware vSphere API that allows user to manage ESX, ESXi, and vCenter infrastructure.
You need to install this Python SDK on host from where you want to invoke VMware automation. For example, if you are using control node then ``pyVmomi`` must be installed on control node.
If you are using any ``delegate_to`` host which is different from your control node then you need to install ``pyVmomi`` on that ``delegate_to`` node.
You can install pyVmomi using pip:
.. code-block:: bash
$ pip install pyvmomi

11
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_external_doc_links.rst
Unescape Escape View File

@ -1,11 +0,0 @@
.. _vmware_external_doc_links:
*****************************
Other useful VMware resources
*****************************
* `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_
* `VCSIM test container image <https://quay.io/repository/ansible/vcenter-test-container>`_
* `Ansible VMware community wiki page <https://github.com/ansible/community/wiki/VMware>`_
* `VMware's official Guest Operating system customization matrix <https://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf>`_
* `VMware Compatibility Guide <https://www.vmware.com/resources/compatibility/search.php>`_

9
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_getting_started.rst
Unescape Escape View File

@ -1,9 +0,0 @@
:orphan:
.. _vmware_ansible_getting_started:
***************************************
Getting Started with Ansible for VMware
***************************************
This will have a basic "hello world" scenario/walkthrough that gets the user introduced to the basics.

54
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst
Unescape Escape View File

@ -1,54 +0,0 @@
.. _vmware_ansible_intro:
**********************************
Introduction to Ansible for VMware
**********************************
.. contents::
:local:
Introduction
============
Ansible provides various modules to manage VMware infrastructure, which includes datacenter, cluster,
host system and virtual machine.
Requirements
============
Ansible VMware modules are written on top of `pyVmomi <https://github.com/vmware/pyvmomi>`_.
pyVmomi is the Python SDK for the VMware vSphere API that allows user to manage ESX, ESXi,
and vCenter infrastructure. You can install pyVmomi using pip (you may need to use pip3, depending on your OS/distro):
.. code-block:: bash
$ pip install pyvmomi
Ansible VMware modules leveraging latest vSphere(6.0+) features are using `vSphere Automation Python SDK <https://github.com/vmware/vsphere-automation-sdk-python>`_. The vSphere Automation Python SDK also has client libraries, documentation, and sample code for VMware Cloud on AWS Console APIs, NSX VMware Cloud on AWS integration APIs, VMware Cloud on AWS site recovery APIs, NSX-T APIs.
You can install vSphere Automation Python SDK using pip:
.. code-block:: bash
$ pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git
Note:
Installing vSphere Automation Python SDK also installs ``pyvmomi``. A separate installation of ``pyvmomi`` is not required.
vmware_guest module
===================
The :ref:`vmware_guest<vmware_guest_module>` module manages various operations related to virtual machines in the given ESXi or vCenter server.
.. 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
`govc <https://github.com/vmware/govmomi/tree/master/govc>`_
govc is a vSphere CLI built on top of govmomi
:ref:`working_with_playbooks`
An introduction to playbooks

91
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory.rst
Unescape Escape View File

@ -1,91 +0,0 @@
.. _vmware_ansible_inventory:
*************************************
Using VMware dynamic inventory plugin
*************************************
.. contents::
:local:
VMware Dynamic Inventory Plugin
===============================
The best way to interact with your hosts is to use the VMware dynamic inventory plugin, which dynamically queries VMware APIs and
tells Ansible what nodes can be managed.
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 like 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
To use this VMware dynamic inventory plugin, you need to enable it first by specifying the following in the ``ansible.cfg`` file:
.. code-block:: ini
[inventory]
enable_plugins = vmware_vm_inventory
Then, create a file that ends in ``.vmware.yml`` or ``.vmware.yaml`` in your working directory.
The ``vmware_vm_inventory`` script takes in the same authentication information as any VMware module.
Here's an example of a valid inventory file:
.. code-block:: yaml
plugin: vmware_vm_inventory
strict: False
hostname: 10.65.223.31
username: administrator@vsphere.local
password: Esxi@123$%
validate_certs: False
with_tags: True
Executing ``ansible-inventory --list -i <filename>.vmware.yml`` will create a list of VMware instances that are ready to be configured using Ansible.
Using vaulted configuration files
=================================
Since the inventory configuration file contains vCenter password in plain text, a security risk, you may want to
encrypt your entire inventory configuration file.
You can encrypt a valid inventory configuration file as follows:
.. code-block:: bash
$ ansible-vault encrypt <filename>.vmware.yml
New Vault password:
Confirm New Vault password:
Encryption successful
And you can use this vaulted inventory configuration file using:
.. code-block:: bash
$ ansible-inventory -i filename.vmware.yml --list --vault-password-file=/path/to/vault_password_file
.. 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:`working_with_playbooks`
An introduction to playbooks
:ref:`playbooks_vault`
Using Vault in playbooks

216
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_filters.rst
Unescape Escape View File

@ -1,216 +0,0 @@
.. _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

128
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_hostnames.rst
Unescape Escape View File

@ -1,128 +0,0 @@
.. _vmware_ansible_inventory_using_hostnames:
*************************************************
Using VMware dynamic inventory plugin - Hostnames
*************************************************
.. contents::
:local:
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 <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.
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 <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 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 <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

1184
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst
View File

File diff suppressed because it is too large Load Diff

9
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_module_reference.rst
Unescape Escape View File

@ -1,9 +0,0 @@
:orphan:
.. _vmware_ansible_module_index:
***************************
Ansible VMware Module Guide
***************************
This will be a listing similar to the module index in our core docs.

64
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_requirements.rst
Unescape Escape View File

@ -1,64 +0,0 @@
.. _vmware_requirements:
********************
VMware Prerequisites
********************
.. contents::
:local:
Installing SSL Certificates
===========================
All vCenter and ESXi servers require SSL encryption on all connections to enforce secure communication. You must enable SSL encryption for Ansible by installing the server's SSL certificates on your Ansible control node or delegate node.
If the SSL certificate of your vCenter or ESXi server is not correctly installed on your Ansible control node, you will see the following warning when using Ansible VMware modules:
``Unable to connect to vCenter or ESXi API at xx.xx.xx.xx on TCP/443: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)``
To install the SSL certificate for your VMware server, and run your Ansible VMware modules in encrypted mode, please follow the instructions for the server you are running with VMware.
Installing vCenter SSL certificates for Ansible
-----------------------------------------------
* From any web browser, go to the base URL of the vCenter Server without port number like ``https://vcenter-domain.example.com``
* Click the "Download trusted root CA certificates" link at the bottom of the grey box on the right and download the file.
* Change the extension of the file to .zip. The file is a ZIP file of all root certificates and all CRLs.
* Extract the contents of the zip file. The extracted directory contains a ``.certs`` directory that contains two types of files. Files with a number as the extension (.0, .1, and so on) are root certificates.
* Install the certificate files are trusted certificates by the process that is appropriate for your operating system.
Installing ESXi SSL certificates for Ansible
--------------------------------------------
* Enable SSH Service on ESXi either by using Ansible VMware module `vmware_host_service_manager <https://github.com/ansible-collections/vmware/blob/main/plugins/modules/vmware_host_config_manager.py>`_ or manually using vSphere Web interface.
* SSH to ESXi server using administrative credentials, and navigate to directory ``/etc/vmware/ssl``
* Secure copy (SCP) ``rui.crt`` located in ``/etc/vmware/ssl`` directory to Ansible control node.
* Install the certificate file by the process that is appropriate for your operating system.
Using custom path for SSL certificates
--------------------------------------
If you need to use a custom path for SSL certificates, you can set the ``REQUESTS_CA_BUNDLE`` environment variable in your playbook.
For example, if ``/var/vmware/certs/vcenter1.crt`` is the SSL certificate for your vCenter Server, you can use the :ref:`environment <playbooks_environment>` keyword to pass it to the modules:
.. code-block:: yaml
- name: Gather all tags from vCenter
community.vmware.vmware_tag_info:
validate_certs: True
hostname: '{{ vcenter_hostname }}'
username: '{{ vcenter_username }}'
password: '{{ vcenter_password }}'
environment:
REQUESTS_CA_BUNDLE: /var/vmware/certs/vcenter1.crt
There is a `known issue <https://github.com/psf/requests/issues/3829>`_ in ``requests`` library (version 2) which you may want to consider when using this environment variable. Basically, setting ``REQUESTS_CA_BUNDLE`` environment variable on managed nodes overrides the ``validate_certs`` value. This may result in unexpected behavior while running the playbook. Please see `community.vmware issue 601 <https://github.com/ansible-collections/community.vmware/issues/601>`_ and `vmware issue 254 <https://github.com/vmware/vsphere-automation-sdk-python/issues/254>`_ for more information.

17
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_scenarios.rst
Unescape Escape View File

@ -1,17 +0,0 @@
.. _vmware_scenarios:
****************************
Ansible for VMware Scenarios
****************************
These scenarios teach you how to accomplish common VMware tasks using Ansible. To get started, please select the task you want to accomplish.
.. toctree::
:maxdepth: 1
scenario_clone_template
scenario_rename_vm
scenario_remove_vm
scenario_find_vm_folder
scenario_vmware_http
scenario_vmware_tools_connection

103
docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_troubleshooting.rst
Unescape Escape View File

@ -1,103 +0,0 @@
.. _vmware_troubleshooting:
**********************************
Troubleshooting Ansible for VMware
**********************************
.. contents::
:local:
This section lists things that can go wrong and possible ways to fix them.
Debugging Ansible for VMware
============================
When debugging or creating a new issue, you will need information about your VMware infrastructure. You can get this information using
`govc <https://github.com/vmware/govmomi/tree/master/govc>`_, For example:
.. code-block:: bash
$ export GOVC_USERNAME=ESXI_OR_VCENTER_USERNAME
$ export GOVC_PASSWORD=ESXI_OR_VCENTER_PASSWORD
$ export GOVC_URL=https://ESXI_OR_VCENTER_HOSTNAME:443
$ govc find /
Known issues with Ansible for VMware
====================================
Network settings with vmware_guest in Ubuntu 18.04
--------------------------------------------------
Setting the network with ``vmware_guest`` in Ubuntu 18.04 is known to be broken, due to missing support for ``netplan`` in the ``open-vm-tools``.
This issue is tracked via:
* https://github.com/vmware/open-vm-tools/issues/240
* https://github.com/ansible/ansible/issues/41133
Potential Workarounds
^^^^^^^^^^^^^^^^^^^^^
There are several workarounds for this issue.
1) Modify the Ubuntu 18.04 images and installing ``ifupdown`` in them via ``sudo apt install ifupdown``.
If so you need to remove ``netplan`` via ``sudo apt remove netplan.io`` and you need stop ``systemd-networkd`` via ``sudo systemctl disable systemctl-networkd``.
2) Generate the ``systemd-networkd`` files with a task in your VMware Ansible role:
.. code-block:: yaml
- name: make sure cache directory exists
file: path="{{ inventory_dir }}/cache" state=directory
delegate_to: localhost
- name: generate network templates
template: src=network.j2 dest="{{ inventory_dir }}/cache/{{ inventory_hostname }}.network"
delegate_to: localhost
- name: copy generated files to vm
vmware_guest_file_operation:
hostname: "{{ vmware_general.hostname }}"
username: "{{ vmware_username }}"
password: "{{ vmware_password }}"
datacenter: "{{ vmware_general.datacenter }}"
validate_certs: "{{ vmware_general.validate_certs }}"
vm_id: "{{ inventory_hostname }}"
vm_username: root
vm_password: "{{ template_password }}"
copy:
src: "{{ inventory_dir }}/cache/{{ inventory_hostname }}.network"
dest: "/etc/systemd/network/ens160.network"
overwrite: False
delegate_to: localhost
- name: restart systemd-networkd
vmware_vm_shell:
hostname: "{{ vmware_general.hostname }}"
username: "{{ vmware_username }}"
password: "{{ vmware_password }}"
datacenter: "{{ vmware_general.datacenter }}"
folder: /vm
vm_id: "{{ inventory_hostname}}"
vm_username: root
vm_password: "{{ template_password }}"
vm_shell: /bin/systemctl
vm_shell_args: " restart systemd-networkd"
delegate_to: localhost
- name: restart systemd-resolved
vmware_vm_shell:
hostname: "{{ vmware_general.hostname }}"
username: "{{ vmware_username }}"
password: "{{ vmware_password }}"
datacenter: "{{ vmware_general.datacenter }}"
folder: /vm
vm_id: "{{ inventory_hostname}}"
vm_username: root
vm_password: "{{ template_password }}"
vm_shell: /bin/systemctl
vm_shell_args: " restart systemd-resolved"
delegate_to: localhost
3) Wait for ``netplan`` support in ``open-vm-tools``
Write Preview
Loading…
Cancel
Save