diff options
Diffstat (limited to 'ansible_collections/community/vmware/docs/docsite/rst')
21 files changed, 3164 insertions, 0 deletions
diff --git a/ansible_collections/community/vmware/docs/docsite/rst/dev_guide.rst b/ansible_collections/community/vmware/docs/docsite/rst/dev_guide.rst new file mode 100644 index 000000000..5a74c9fe0 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/dev_guide.rst @@ -0,0 +1,239 @@ +.. _ansible_collections.community.vmware.docsite.vmware_ansible_devguide: + +**************************************** +Guidelines for VMware module development +**************************************** + +The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, source code `repository <https://github.com/ansible-collections/community.vmware>`_) is maintained by the VMware Working Group. For more information see the `team community page <https://github.com/ansible/community/wiki/VMware>`_. + +.. contents:: + :local: + +Testing with your own infrastructure +==================================== + +You can target a regular VMware environment. This paragraph explains step by step how you can run the test-suite yourself. + +Requirements +------------ + +- 2 ESXi hosts (6.5 or 6.7) + - with 2 NIC, the second ones should be available for the test +- a VCSA host +- a NFS server +- Python dependencies: + - `pyvmomi <https://github.com/vmware/pyvmomi/tree/master/pyVmomi>`_ + - `requests <https://2.python-requests.org/en/master/>`_ + +If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https://github.com/goneri/vmware-on-libvirt>`_ work well. + +NFS server configuration +^^^^^^^^^^^^^^^^^^^^^^^^ + +Your NFS server must expose the following directory structure: + +.. code-block:: shell + + $ tree /srv/share/ + /srv/share/ + ├── isos + │ ├── base.iso + │ ├── centos.iso + │ └── fedora.iso + └── vms + 2 directories, 3 files + +On a Linux system, you can expose the directory over NFS with the following export file: + +.. code-block:: shell + + $ cat /etc/exports + /srv/share 192.168.122.0/255.255.255.0(rw,anonuid=1000,anongid=1000) + +.. note:: + + With this configuration all the new files will be owned by the user with the UID and GID 1000/1000. + Adjust the configuration to match your user's UID/GID. + +The service can be enabled with: + +.. code-block:: shell + + $ sudo systemctl enable --now nfs-server + + +Configure your installation +--------------------------- + +Prepare a configuration file that describes your set-up. The file +should be called `test/integration/cloud-config-vcenter.ini` and based on +`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with +`vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_: + +.. code-block:: ini + + [DEFAULT] + vcenter_username: administrator@vsphere.local + vcenter_password: !234AaAa56 + vcenter_hostname: vcenter.test + vmware_validate_certs: false + esxi1_hostname: esxi1.test + esxi1_username: root + esxi1_password: root + esxi2_hostname: test2.test + esxi2_username: root + esxi2_password: root + +Using an HTTP proxy +------------------- +Hosting test infrastructure behind an HTTP proxy is supported. You can specify the location of the proxy server with the two extra keys: + +.. code-block:: ini + + vmware_proxy_host: esxi1-gw.ws.testing.ansible.com + vmware_proxy_port: 11153 + +In addition, you may need to adjust the variables of the following `var files <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ to match the configuration of your lab. If you use vmware-on-libvirt to prepare your lab, you do not have anything to change. + +Run the test-suite +------------------ + +Once your configuration is ready, you can trigger a run with the following command: + +.. code-block:: shell + + source hacking/env-setup + VMWARE_TEST_PLATFORM=static ansible-test integration --python 3.7 vmware_host_firewall_manager + +``vmware_host_firewall_manager`` is the name of the module to test. + +``vmware_guest`` is much larger than any other test role and is rather slow. You can enable or disable some of its test playbooks in `main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_. + + +Unit-test +========= + +The VMware modules have limited unit-test coverage. You can run the test suite with the +following commands: + +.. code-block:: shell + + source hacking/env-setup + ansible-test units --venv --python 3.7 '.*vmware.*' + +Code style and best practice +============================ + +datacenter argument with ESXi +----------------------------- + +The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because the user may +not realize that Ansible silently targets the wrong data center. + +esxi_hostname should not be mandatory +------------------------------------- + +Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly work with both. In this case, +``esxi_hostname`` parameter should be optional. + +.. code-block:: python + + if self.is_vcenter(): + esxi_hostname = module.params.get('esxi_hostname') + if not esxi_hostname: + self.module.fail_json("esxi_hostname parameter is mandatory") + self.host = self.get_all_host_objs(cluster_name=cluster_name, esxi_host_name=esxi_hostname)[0] + else: + self.host = find_obj(self.content, [vim.HostSystem], None) + if self.host is None: + self.module.fail_json(msg="Failed to find host system.") + +Example should use the fully qualified collection name (FQCN) +------------------------------------------------------------- + +Use FQCN for examples within module documentation. For instance, you should use ``community.vmware.vmware_guest`` instead of just +``vmware_guest``. + +This way, the examples do not depend on the ``collections`` directive of the +playbook. + +Functional tests +---------------- + +Writing new tests +^^^^^^^^^^^^^^^^^ + +If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyond +the standard Ansible :ref:`integration testing<testing_integration>` process. + +The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ role. +The resources defined there are automatically created by importing that role at the start of your test: + +.. code-block:: yaml + + - import_role: + name: prepare_vmware_tests + vars: + setup_datacenter: true + +This will give you a ready to use cluster, datacenter, datastores, folder, switch, dvswitch, ESXi hosts, and VMs. + +No need to create too much resources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By avoiding it, +you speed up the test execution and you simplify the clean up afterwards. + +VM names should be predictable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or ``test_vm3``. This +way it will be automatically clean up for you. + +Avoid the common boiler plate code in your test playbook +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From Ansible 2.10, the test suite uses `modules_defaults`. This module +allow us to preinitialize the following default keys of the VMware modules: + +- hostname +- username +- password +- validate_certs + +For example, the following block: + +.. code-block:: yaml + + - name: Add a VMware vSwitch + community.vmware.vmware_vswitch: + hostname: '{{ vcenter_hostname }}' + username: '{{ vcenter_username }}' + password: '{{ vcenter_password }}' + validate_certs: 'no' + esxi_hostname: 'esxi1' + switch_name: "boby" + state: present + +should be simplified to just: + +.. code-block:: yaml + + - name: Add a VMware vSwitch + community.vmware.vmware_vswitch: + esxi_hostname: 'esxi1' + switch_name: "boby" + state: present + + +Typographic convention +====================== + +Nomenclature +------------ + +We try to enforce the following rules in our documentation: + +- VMware, not VMWare or vmware +- ESXi, not esxi or ESXI +- vCenter, not vcenter or VCenter diff --git a/ansible_collections/community/vmware/docs/docsite/rst/scenario_guide.rst b/ansible_collections/community/vmware/docs/docsite/rst/scenario_guide.rst new file mode 100644 index 000000000..270af08cd --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/scenario_guide.rst @@ -0,0 +1,33 @@ +.. _ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/faq.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/faq.rst new file mode 100644 index 000000000..52f4f729e --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/faq.rst @@ -0,0 +1,26 @@ +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_clone_template.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_clone_template.rst new file mode 100644 index 000000000..1139a2523 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_clone_template.rst @@ -0,0 +1,223 @@ +.. _ansible_collections.community.vmware.docsite.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. + diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_find_vm_folder.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_find_vm_folder.rst new file mode 100644 index 000000000..fccd47e26 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_find_vm_folder.rst @@ -0,0 +1,121 @@ +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_remove_vm.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_remove_vm.rst new file mode 100644 index 000000000..59b2bf974 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_remove_vm.rst @@ -0,0 +1,127 @@ +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_rename_vm.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_rename_vm.rst new file mode 100644 index 000000000..5d72d6aea --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_rename_vm.rst @@ -0,0 +1,174 @@ +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_http.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_http.rst new file mode 100644 index 000000000..a831114d3 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_http.rst @@ -0,0 +1,162 @@ +.. _ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_tools_connection.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_tools_connection.rst new file mode 100644 index 000000000..08a4df114 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/scenario_vmware_tools_connection.rst @@ -0,0 +1,120 @@ +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_concepts.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_concepts.rst new file mode 100644 index 000000000..2829624ac --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_concepts.rst @@ -0,0 +1,45 @@ +.. _ansible_collections.community.vmware.docsite.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. + +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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_external_doc_links.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_external_doc_links.rst new file mode 100644 index 000000000..afd2275e9 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_external_doc_links.rst @@ -0,0 +1,10 @@ +.. _ansible_collections.community.vmware.docsite.vmware_external_doc_links: + +***************************** +Other useful VMware resources +***************************** + +* `VMware API and SDK Documentation <https://www.vmware.com/support/pubs/sdk_pubs.html>`_ +* `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>`_ diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_getting_started.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_getting_started.rst new file mode 100644 index 000000000..1b2d34a8f --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_getting_started.rst @@ -0,0 +1,9 @@ +:orphan: + +.. _ansible_collections.community.vmware.docsite.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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_intro.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_intro.rst new file mode 100644 index 000000000..ddc1433c6 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_intro.rst @@ -0,0 +1,54 @@ +.. _ansible_collections.community.vmware.docsite.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<ansible_collections.community.vmware.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 + diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory.rst new file mode 100644 index 000000000..becd718aa --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory.rst @@ -0,0 +1,91 @@ +.. _ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_filters.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_filters.rst new file mode 100644 index 000000000..eb309cf0e --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_filters.rst @@ -0,0 +1,216 @@ +.. _ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_hostnames.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_hostnames.rst new file mode 100644 index 000000000..d89639506 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_hostnames.rst @@ -0,0 +1,128 @@ +.. _ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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:`ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_vm_attributes.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_vm_attributes.rst new file mode 100644 index 000000000..eda856ee3 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_inventory_vm_attributes.rst @@ -0,0 +1,1184 @@ +.. _ansible_collections.community.vmware.docsite.vmware_inventory_vm_attributes: + +******************************************************************* +Using Virtual machine attributes in VMware dynamic inventory plugin +******************************************************************* + +.. contents:: + :local: + +Virtual machine attributes +========================== + +You can use virtual machine properties which can be used to populate ``hostvars`` for the given +virtual machine in a VMware dynamic inventory plugin. + +capability +---------- + +This section describes settings for the runtime capabilities of the virtual machine. + +snapshotOperationsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports snapshot operations. + +multipleSnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports multiple snapshots. + This value is not set when the virtual machine is unavailable, for instance, when it is being created or deleted. + +snapshotConfigSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports snapshot config. + +poweredOffSnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports snapshot operations in ``poweredOff`` state. + +memorySnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports memory snapshots. + +revertToSnapshotSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports reverting to a snapshot. + +quiescedSnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports quiesced snapshots. + +disableSnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not snapshots can be disabled. + +lockSnapshotsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not the snapshot tree can be locked. + +consolePreferencesSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether console preferences can be set for the virtual machine. + +cpuFeatureMaskSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether CPU feature requirements masks can be set for the virtual machine. + +s1AcpiManagementSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not a virtual machine supports ACPI S1 settings management. + +settingScreenResolutionSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not the virtual machine supports setting the screen resolution of the console window. + +toolsAutoUpdateSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Supports tools auto-update. + +vmNpivWwnSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^ + + Supports virtual machine NPIV WWN. + +npivWwnOnNonRdmVmSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Supports assigning NPIV WWN to virtual machines that do not have RDM disks. + +vmNpivWwnDisableSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the NPIV disabling operation is supported on the virtual machine. + +vmNpivWwnUpdateSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the update of NPIV WWNs are supported on the virtual machine. + +swapPlacementSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Flag indicating whether the virtual machine has a configurable (swapfile placement policy). + +toolsSyncTimeSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether asking tools to sync time with the host is supported. + +virtualMmuUsageSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not the use of nested page table hardware support can be explicitly set. + +diskSharesSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether resource settings for disks can be applied to the virtual machine. + +bootOptionsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether boot options can be configured for the virtual machine. + +bootRetryOptionsSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether automatic boot retry can be configured for the virtual machine. + +settingVideoRamSizeSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Flag indicating whether the video RAM size of the virtual machine can be configured. + +settingDisplayTopologySupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not the virtual machine supports setting the display topology of the console window. + +recordReplaySupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether record and replay functionality is supported on the virtual machine. + +changeTrackingSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates that change tracking is supported for virtual disks of the virtual machine. + However, even if change tracking is supported, it might not be available for all disks of the virtual machine. + For example, passthru raw disk mappings or disks backed by any Ver1BackingInfo cannot be tracked. + +multipleCoresPerSocketSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether multiple virtual cores per socket is supported on the virtual machine. + +hostBasedReplicationSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates that host based replication is supported on the virtual machine. + However, even if host based replication is supported, it might not be available for all disk types. + For example, passthru raw disk mappings can not be replicated. + +guestAutoLockSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not guest autolock is supported on the virtual machine. + +memoryReservationLockSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether :ref:`ansible_collections.community.vmware.docsite.memory_reservation_locked_to_max` may be set to true for the virtual machine. + +featureRequirementSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the featureRequirement feature is supported. + +poweredOnMonitorTypeChangeSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether a monitor type change is supported while the virtual machine is in the ``poweredOn`` state. + +seSparseDiskSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the virtual machine supports the Flex-SE (space-efficent, sparse) format for virtual disks. + +nestedHVSupported (bool) +^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the virtual machine supports nested hardware-assisted virtualization. + +vPMCSupported (bool) +^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the virtual machine supports virtualized CPU performance counters. + + +config +------ + +This section describes the configuration settings of the virtual machine, including the name and UUID. +This property is set when a virtual machine is created or when the ``reconfigVM`` method is called. +The virtual machine configuration is not guaranteed to be available. +For example, the configuration information would be unavailable if the server is unable to access the virtual machine files on disk, and is often also unavailable during the initial phases of virtual machine creation. + +changeVersion (str) +^^^^^^^^^^^^^^^^^^^ + + The changeVersion is a unique identifier for a given version of the configuration. + Each change to the configuration updates this value. This is typically implemented as an ever increasing count or a time-stamp. + However, a client should always treat this as an opaque string. + +modified (datetime) +^^^^^^^^^^^^^^^^^^^ + + Last time a virtual machine's configuration was modified. + +name (str) +^^^^^^^^^^ + + Display name of the virtual machine. Any / (slash), \ (backslash), character used in this name element is escaped. Similarly, any % (percent) character used in this name element is escaped, unless it is used to start an escape sequence. A slash is escaped as %2F or %2f. A backslash is escaped as %5C or %5c, and a percent is escaped as %25. + +.. _ansible_collections.community.vmware.docsite.guest_full_name: + +guestFullName (str) +^^^^^^^^^^^^^^^^^^^ + + This is the full name of the guest operating system for the virtual machine. For example: Windows 2000 Professional. See :ref:`ansible_collections.community.vmware.docsite.alternate_guest_name`. + +version (str) +^^^^^^^^^^^^^ + + The version string for the virtual machine. + +uuid (str) +^^^^^^^^^^ + + 128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format. + +instanceUuid (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + VirtualCenter-specific 128-bit UUID of a virtual machine, represented as a hexademical string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that may share the same SMBIOS UUID. + +npivNodeWorldWideName (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A 64-bit node WWN (World Wide Name). + +npivPortWorldWideName (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A 64-bit port WWN (World Wide Name). + +npivWorldWideNameType (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The source that provides/generates the assigned WWNs. + +npivDesiredNodeWwns (short, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The NPIV node WWNs to be extended from the original list of WWN numbers. + +npivDesiredPortWwns (short, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The NPIV port WWNs to be extended from the original list of WWN numbers. + +npivTemporaryDisabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This property is used to enable or disable the NPIV capability on a desired virtual machine on a temporary basis. + +npivOnNonRdmDisks (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + This property is used to check whether the NPIV can be enabled on the Virtual machine with non-rdm disks in the configuration, so this is potentially not enabling npiv on vmfs disks. + Also this property is used to check whether RDM is required to generate WWNs for a virtual machine. + +locationId (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Hash incorporating the virtual machine's config file location and the UUID of the host assigned to run the virtual machine. + +template (bool) +^^^^^^^^^^^^^^^ + + Flag indicating whether or not a virtual machine is a template. + +guestId (str) +^^^^^^^^^^^^^ + + Guest operating system configured on a virtual machine. + +.. _ansible_collections.community.vmware.docsite.alternate_guest_name: + +alternateGuestName (str) +^^^^^^^^^^^^^^^^^^^^^^^^ + + Used as display name for the operating system if guestId isotherorother-64. See :ref:`ansible_collections.community.vmware.docsite.guest_full_name`. + +annotation (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Description for the virtual machine. + +files (vim.vm.FileInfo) +^^^^^^^^^^^^^^^^^^^^^^^ + + Information about the files associated with a virtual machine. + This information does not include files for specific virtual disks or snapshots. + +tools (vim.vm.ToolsConfigInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration of VMware Tools running in the guest operating system. + +flags (vim.vm.FlagInfo) +^^^^^^^^^^^^^^^^^^^^^^^ + + Additional flags for a virtual machine. + +consolePreferences (vim.vm.ConsolePreferences, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Legacy console viewer preferences when doing power operations. + +defaultPowerOps (vim.vm.DefaultPowerOpInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration of default power operations. + +hardware (vim.vm.VirtualHardware) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Processor, memory, and virtual devices for a virtual machine. + +cpuAllocation (vim.ResourceAllocationInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Resource limits for CPU. + +memoryAllocation (vim.ResourceAllocationInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Resource limits for memory. + +latencySensitivity (vim.LatencySensitivity, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The latency-sensitivity of the virtual machine. + +memoryHotAddEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Whether memory can be added while the virtual machine is running. + +cpuHotAddEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Whether virtual processors can be added while the virtual machine is running. + +cpuHotRemoveEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Whether virtual processors can be removed while the virtual machine is running. + +hotPlugMemoryLimit (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The maximum amount of memory, in MB, than can be added to a running virtual machine. + +hotPlugMemoryIncrementSize (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Memory, in MB that can be added to a running virtual machine. + +cpuAffinity (vim.vm.AffinityInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Affinity settings for CPU. + +memoryAffinity (vim.vm.AffinityInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Affinity settings for memory. + +networkShaper (vim.vm.NetworkShaperInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Resource limits for network. + +extraConfig (vim.option.OptionValue, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Additional configuration information for the virtual machine. + +cpuFeatureMask (vim.host.CpuIdInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Specifies CPU feature compatibility masks that override the defaults from the ``GuestOsDescriptor`` of the virtual machine's guest OS. + +datastoreUrl (vim.vm.ConfigInfo.DatastoreUrlPair, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Enumerates the set of datastores that the virtual machine is stored on, as well as the URL identification for each of these. + +swapPlacement (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Virtual machine swapfile placement policy. + +bootOptions (vim.vm.BootOptions, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration options for the boot behavior of the virtual machine. + +ftInfo (vim.vm.FaultToleranceConfigInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Fault tolerance settings for the virtual machine. + +vAppConfig (vim.vApp.VmConfigInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + vApp meta-data for the virtual machine. + +vAssertsEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether user-configured virtual asserts will be triggered during virtual machine replay. + +changeTrackingEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether changed block tracking for the virtual machine's disks is active. + +firmware (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^ + + Information about firmware type for the virtual machine. + +maxMksConnections (int, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates the maximum number of active remote display connections that the virtual machine will support. + +guestAutoLockEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the guest operating system will logout any active sessions whenever there are no remote display connections open to the virtual machine. + +managedBy (vim.ext.ManagedByInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Specifies that the virtual machine is managed by a VC Extension. + +.. _ansible_collections.community.vmware.docsite.memory_reservation_locked_to_max: + +memoryReservationLockedToMax (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + If set true, memory resource reservation for the virtual machine will always be equal to the virtual machine's memory size; increases in memory size will be rejected when a corresponding reservation increase is not possible. + +initialOverhead (vim.vm.ConfigInfo.OverheadInfo), optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Set of values to be used only to perform admission control when determining if a host has sufficient resources for the virtual machine to power on. + +nestedHVEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the virtual machine is configured to use nested hardware-assisted virtualization. + +vPMCEnabled (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether the virtual machine have virtual CPU performance counters enabled. + +scheduledHardwareUpgradeInfo (vim.vm.ScheduledHardwareUpgradeInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration of scheduled hardware upgrades and result from last attempt to run scheduled hardware upgrade. + +vFlashCacheReservation (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Specifies the total vFlash resource reservation for the vFlash caches associated with the virtual machine's virtual disks, in bytes. + +layout +------ + +Detailed information about the files that comprise the virtual machine. + +configFile (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A list of files that makes up the configuration of the virtual machine (excluding the .vmx file, since that file is represented in the FileInfo). + These are relative paths from the configuration directory. + A slash is always used as a separator. + This list will typically include the NVRAM file, but could also include other meta-data files. + +logFile (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^ + + A list of files stored in the virtual machine's log directory. + These are relative paths from the ``logDirectory``. + A slash is always used as a separator. + +disk (vim.vm.FileLayout.DiskLayout, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Files making up each virtual disk. + +snapshot (vim.vm.FileLayout.SnapshotLayout, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Files of each snapshot. + +swapFile (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^ + + The swapfile specific to the virtual machine, if any. This is a complete datastore path, not a relative path. + + +layoutEx +-------- + +Detailed information about the files that comprise the virtual machine. + +file (vim.vm.FileLayoutEx.FileInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Information about all the files that constitute the virtual machine including configuration files, disks, swap file, suspend file, log files, core files, memory file and so on. + +disk (vim.vm.FileLayoutEx.DiskLayout, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Layout of each virtual disk attached to the virtual machine. + For a virtual machine with snaphots, this property gives only those disks that are attached to it at the current point of running. + +snapshot (vim.vm.FileLayoutEx.SnapshotLayout, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Layout of each snapshot of the virtual machine. + +timestamp (datetime) +^^^^^^^^^^^^^^^^^^^^ + + Time when values in this structure were last updated. + +storage (vim.vm.StorageInfo) +---------------------------- + +Storage space used by the virtual machine, split by datastore. + +perDatastoreUsage (vim.vm.StorageInfo.UsageOnDatastore, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Storage space used by the virtual machine on all datastores that it is located on. + Total storage space committed to the virtual machine across all datastores is simply an aggregate of the property ``committed`` + +timestamp (datetime) +^^^^^^^^^^^^^^^^^^^^ + + Time when values in this structure were last updated. + +environmentBrowser (vim.EnvironmentBrowser) +------------------------------------------- + +The current virtual machine's environment browser object. +This contains information on all the configurations that can be used on the virtual machine. +This is identical to the environment browser on the ComputeResource to which the virtual machine belongs. + +datastoreBrowser (vim.host.DatastoreBrowser) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + DatastoreBrowser to browse datastores that are available on this entity. + +resourcePool (vim.ResourcePool) +------------------------------- + +The current resource pool that specifies resource allocation for the virtual machine. +This property is set when a virtual machine is created or associated with a different resource pool. +Returns null if the virtual machine is a template or the session has no access to the resource pool. + +summary (vim.ResourcePool.Summary) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Basic information about a resource pool. + +runtime (vim.ResourcePool.RuntimeInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Runtime information about a resource pool. + +owner (vim.ComputeResource) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The ComputeResource to which this set of one or more nested resource pools belong. + +resourcePool (vim.ResourcePool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The set of child resource pools. + +vm (vim.VirtualMachine) +^^^^^^^^^^^^^^^^^^^^^^^ + + The set of virtual machines associated with this resource pool. + +config (vim.ResourceConfigSpec) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration of this resource pool. + +childConfiguration (vim.ResourceConfigSpec) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The resource configuration of all direct children (VirtualMachine and ResourcePool) of this resource group. + +parentVApp (vim.ManagedEntity) +------------------------------ + +Reference to the parent vApp. + +parent (vim.ManagedEntity) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Parent of this entity. + This value is null for the root object and for (VirtualMachine) objects that are part of a (VirtualApp). + +customValue (vim.CustomFieldsManager.Value) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Custom field values. + +overallStatus (vim.ManagedEntity.Status) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + General health of this managed entity. + +configStatus (vim.ManagedEntity.Status) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The configStatus indicates whether or not the system has detected a configuration issue involving this entity. + For example, it might have detected a duplicate IP address or MAC address, or a host in a cluster might be out of ``compliance.property``. + +configIssue (vim.event.Event) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current configuration issues that have been detected for this entity. + +effectiveRole (int) +^^^^^^^^^^^^^^^^^^^ + + Access rights the current session has to this entity. + +permission (vim.AuthorizationManager.Permission) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + List of permissions defined for this entity. + +name (str) +^^^^^^^^^^ + + Name of this entity, unique relative to its parent. + Any / (slash), \ (backslash), character used in this name element will be escaped. + Similarly, any % (percent) character used in this name element will be escaped, unless it is used to start an escape sequence. + A slash is escaped as %2F or %2f. A backslash is escaped as %5C or %5c, and a percent is escaped as %25. + +disabledMethod (str) +^^^^^^^^^^^^^^^^^^^^ + + List of operations that are disabled, given the current runtime state of the entity. + For example, a power-on operation always fails if a virtual machine is already powered on. + +recentTask (vim.Task) +^^^^^^^^^^^^^^^^^^^^^ + + The set of recent tasks operating on this managed entity. + A task in this list could be in one of the four states: pending, running, success or error. + +declaredAlarmState (vim.alarm.AlarmState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A set of alarm states for alarms that apply to this managed entity. + +triggeredAlarmState (vim.alarm.AlarmState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A set of alarm states for alarms triggered by this entity or by its descendants. + +alarmActionsEnabled (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Whether alarm actions are enabled for this entity. True if enabled; false otherwise. + +tag (vim.Tag) +^^^^^^^^^^^^^ + + The set of tags associated with this managed entity. Experimental. Subject to change. + +resourceConfig (vim.ResourceConfigSpec) +--------------------------------------- + + The resource configuration for a virtual machine. + +entity (vim.ManagedEntity, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Reference to the entity with this resource specification: either a VirtualMachine or a ResourcePool. + +changeVersion (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The changeVersion is a unique identifier for a given version of the configuration. Each change to the configuration will update this value. + This is typically implemented as an ever increasing count or a time-stamp. + + +lastModified (datetime, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Timestamp when the resources were last modified. This is ignored when the object is used to update a configuration. + +cpuAllocation (vim.ResourceAllocationInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Resource allocation for CPU. + +memoryAllocation (vim.ResourceAllocationInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Resource allocation for memory. + +runtime (vim.vm.RuntimeInfo) +---------------------------- + +Execution state and history for the virtual machine. + +device (vim.vm.DeviceRuntimeInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Per-device runtime info. This array will be empty if the host software does not provide runtime info for any of the device types currently in use by the virtual machine. + +host (vim.HostSystem, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The host that is responsible for running a virtual machine. + This property is null if the virtual machine is not running and is not assigned to run on a particular host. + +connectionState (vim.VirtualMachine.ConnectionState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Indicates whether or not the virtual machine is available for management. + +powerState (vim.VirtualMachine.PowerState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The current power state of the virtual machine. + +faultToleranceState (vim.VirtualMachine.FaultToleranceState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The fault tolerance state of the virtual machine. + +dasVmProtection (vim.vm.RuntimeInfo.DasProtectionState, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The vSphere HA protection state for a virtual machine. + Property is unset if vSphere HA is not enabled. + +toolsInstallerMounted (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Flag to indicate whether or not the VMware Tools installer is mounted as a CD-ROM. + +suspendTime (datetime, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The timestamp when the virtual machine was most recently suspended. + This property is updated every time the virtual machine is suspended. + +bootTime (datetime, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The timestamp when the virtual machine was most recently powered on. + This property is updated when the virtual machine is powered on from the poweredOff state, and is cleared when the virtual machine is powered off. + This property is not updated when a virtual machine is resumed from a suspended state. + +suspendInterval (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The total time the virtual machine has been suspended since it was initially powered on. + This time excludes the current period, if the virtual machine is currently suspended. + This property is updated when the virtual machine resumes, and is reset to zero when the virtual machine is powered off. + +question (vim.vm.QuestionInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The current question, if any, that is blocking the virtual machine's execution. + +memoryOverhead (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The amount of memory resource (in bytes) that will be used by the virtual machine above its guest memory requirements. + This value is set if and only if the virtual machine is registered on a host that supports memory resource allocation features. + For powered off VMs, this is the minimum overhead required to power on the VM on the registered host. + For powered on VMs, this is the current overhead reservation, a value which is almost always larger than the minimum overhead, and which grows with time. + +maxCpuUsage (int, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current upper-bound on CPU usage. + The upper-bound is based on the host the virtual machine is current running on, as well as limits configured on the virtual machine itself or any parent resource pool. + Valid while the virtual machine is running. + +maxMemoryUsage (int, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current upper-bound on memory usage. + The upper-bound is based on memory configuration of the virtual machine, as well as limits configured on the virtual machine itself or any parent resource pool. + Valid while the virtual machine is running. + +numMksConnections (int) +^^^^^^^^^^^^^^^^^^^^^^^ + + Number of active MKS connections to the virtual machine. + +recordReplayState (vim.VirtualMachine.RecordReplayState) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Record / replay state of the virtual machine. + +cleanPowerOff (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + For a powered off virtual machine, indicates whether the virtual machine's last shutdown was an orderly power off or not. + Unset if the virtual machine is running or suspended. + +needSecondaryReason (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + If set, indicates the reason the virtual machine needs a secondary. + +onlineStandby (bool) +^^^^^^^^^^^^^^^^^^^^ + + This property indicates whether the guest has gone into one of the s1, s2 or s3 standby modes. False indicates the guest is awake. + +minRequiredEVCModeKey (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + For a powered-on or suspended virtual machine in a cluster with Enhanced VMotion Compatibility (EVC) enabled, this identifies the least-featured EVC mode (among those for the appropriate CPU vendor) that could admit the virtual machine. + This property will be unset if the virtual machine is powered off or is not in an EVC cluster. + This property may be used as a general indicator of the CPU feature baseline currently in use by the virtual machine. + However, the virtual machine may be suppressing some of the features present in the CPU feature baseline of the indicated mode, either explicitly (in the virtual machine's configured ``cpuFeatureMask``) or implicitly (in the default masks for the ``GuestOsDescriptor`` appropriate for the virtual machine's configured guest OS). + +consolidationNeeded (bool) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Whether any disk of the virtual machine requires consolidation. + This can happen for example when a snapshot is deleted but its associated disk is not committed back to the base disk. + +offlineFeatureRequirement (vim.vm.FeatureRequirement, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + These requirements must have equivalent host capabilities ``featureCapability`` in order to power on. + +featureRequirement (vim.vm.FeatureRequirement, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + These requirements must have equivalent host capabilities ``featureCapability`` in order to power on, resume, or migrate to the host. + +featureMask (vim.host.FeatureMask, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The masks applied to an individual virtual machine as a result of its configuration. + +vFlashCacheAllocation (long, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Specifies the total allocated vFlash resource for the vFlash caches associated with VM's VMDKs when VM is powered on, in bytes. + + +guest (vim.vm.GuestInfo) +------------------------ + +Information about VMware Tools and about the virtual machine from the perspective of VMware Tools. +Information about the guest operating system is available in VirtualCenter. +Guest operating system information reflects the last known state of the virtual machine. +For powered on machines, this is current information. +For powered off machines, this is the last recorded state before the virtual machine was powered off. + +toolsStatus (vim.vm.GuestInfo.ToolsStatus, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current status of VMware Tools in the guest operating system, if known. + +toolsVersionStatus (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current version status of VMware Tools in the guest operating system, if known. + +toolsVersionStatus2 (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current version status of VMware Tools in the guest operating system, if known. + +toolsRunningStatus (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current running status of VMware Tools in the guest operating system, if known. + +toolsVersion (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current version of VMware Tools, if known. + +guestId (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^ + + Guest operating system identifier (short name), if known. + +guestFamily (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest operating system family, if known. + +guestFullName (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + See :ref:`ansible_collections.community.vmware.docsite.guest_full_name`. + +hostName (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^ + + Hostname of the guest operating system, if known. + +ipAddress (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^ + + Primary IP address assigned to the guest operating system, if known. + +net (vim.vm.GuestInfo.NicInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest information about network adapters, if known. + +ipStack (vim.vm.GuestInfo.StackInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest information about IP networking stack, if known. + +disk (vim.vm.GuestInfo.DiskInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest information about disks. + You can obtain Linux guest disk information for the following file system types only: Ext2, Ext3, Ext4, ReiserFS, ZFS, NTFS, VFAT, UFS, PCFS, HFS, and MS-DOS. + +screen (vim.vm.GuestInfo.ScreenInfo, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest screen resolution info, if known. + +guestState (str) +^^^^^^^^^^^^^^^^ + + Operation mode of guest operating system. + +appHeartbeatStatus (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Application heartbeat status. + +appState (str, optional) +^^^^^^^^^^^^^^^^^^^^^^^^ + + Application state. + If vSphere HA is enabled and the vm is configured for Application Monitoring and this field's value is ``appStateNeedReset`` then HA will attempt immediately reset the virtual machine. + There are some system conditions which may delay the immediate reset. + The immediate reset will be performed as soon as allowed by vSphere HA and ESX. + If during these conditions the value is changed to ``appStateOk`` the reset will be cancelled. + +guestOperationsReady (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest Operations availability. If true, the vitrual machine is ready to process guest operations. + +interactiveGuestOperationsReady (bool, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Interactive Guest Operations availability. If true, the virtual machine is ready to process guest operations as the user interacting with the guest desktop. + +generationInfo (vim.vm.GuestInfo.NamespaceGenerationInfo, privilege: VirtualMachine.Namespace.EventNotify, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A list of namespaces and their corresponding generation numbers. Only namespaces with non-zero ``maxSizeEventsFromGuest`` are guaranteed to be present here. + + +summary (vim.vm.Summary) +------------------------ + + Basic information about the virtual machine. + +vm (vim.VirtualMachine, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Reference to the virtual machine managed object. + +runtime (vim.vm.RuntimeInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Runtime and state information of a running virtual machine. + Most of this information is also available when a virtual machine is powered off. + In that case, it contains information from the last run, if available. + +guest (vim.vm.Summary.GuestSummary, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Guest operating system and VMware Tools information. + +config (vim.vm.Summary.ConfigSummary) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Basic configuration information about the virtual machine. + This information is not available when the virtual machine is unavailable, for instance, when it is being created or deleted. + +storage (vim.vm.Summary.StorageSummary, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Storage information of the virtual machine. + +quickStats (vim.vm.Summary.QuickStats) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + A set of statistics that are typically updated with near real-time regularity. + +overallStatus (vim.ManagedEntity.Status) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Overall alarm status on this node. + +customValue (vim.CustomFieldsManager.Value, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Custom field values. + + +datastore (vim.Datastore) +------------------------- + + A collection of references to the subset of datastore objects in the datacenter that is used by the virtual machine. + +info (vim.Datastore.Info) +^^^^^^^^^^^^^^^^^^^^^^^^^ + + Specific information about the datastore. + +summary (vim.Datastore.Summary) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Global properties of the datastore. + +host (vim.Datastore.HostMount) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Hosts attached to this datastore. + +vm (vim.VirtualMachine) +^^^^^^^^^^^^^^^^^^^^^^^ + + Virtual machines stored on this datastore. + +browser (vim.host.DatastoreBrowser) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + DatastoreBrowser used to browse this datastore. + +capability (vim.Datastore.Capability) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Capabilities of this datastore. + +iormConfiguration (vim.StorageResourceManager.IORMConfigInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Configuration of storage I/O resource management for the datastore. + Currently VMware only support storage I/O resource management on VMFS volumes of a datastore. + This configuration may not be available if the datastore is not accessible from any host, or if the datastore does not have VMFS volume. + +network (vim.Network) +--------------------- + + A collection of references to the subset of network objects in the datacenter that is used by the virtual machine. + +name (str) +^^^^^^^^^^ + + Name of this network. + +summary (vim.Network.Summary) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Properties of a network. + +host (vim.HostSystem) +^^^^^^^^^^^^^^^^^^^^^ + + Hosts attached to this network. + +vm (vim.VirtualMachine) +^^^^^^^^^^^^^^^^^^^^^^^ + + Virtual machines using this network. + + +snapshot (vim.vm.SnapshotInfo) +------------------------------- + +Current snapshot and tree. +The property is valid if snapshots have been created for the virtual machine. + +currentSnapshot (vim.vm.Snapshot, optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Current snapshot of the virtual machineThis property is set by calling ``Snapshot.revert`` or ``VirtualMachine.createSnapshot``. + This property will be empty when the working snapshot is at the root of the snapshot tree. + +rootSnapshotList (vim.vm.SnapshotTree) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Data for the entire set of snapshots for one virtual machine. + +rootSnapshot (vim.vm.Snapshot) +------------------------------ + +The roots of all snapshot trees for the virtual machine. + +config (vim.vm.ConfigInfo) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Information about the configuration of the virtual machine when this snapshot was taken. + The datastore paths for the virtual machine disks point to the head of the disk chain that represents the disk at this given snapshot. + +childSnapshot (vim.vm.Snapshot) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + All snapshots for which this snapshot is the parent. + +guestHeartbeatStatus (vim.ManagedEntity.Status) +----------------------------------------------- + + The guest heartbeat. + +.. 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 + rst/scenario_guides/guide_vmware.rst + 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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_module_reference.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_module_reference.rst new file mode 100644 index 000000000..9a9a36e98 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_module_reference.rst @@ -0,0 +1,9 @@ +:orphan: + +.. _ansible_collections.community.vmware.docsite.vmware_ansible_module_index: + +*************************** +Ansible VMware Module Guide +*************************** + +This will be a listing similar to the module index in our core docs. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_requirements.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_requirements.rst new file mode 100644 index 000000000..8244afe2f --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_requirements.rst @@ -0,0 +1,73 @@ +.. _ansible_collections.community.vmware.docsite.vmware_requirements: + +******************** +VMware Prerequisites +******************** + +.. contents:: + :local: + +ESXi License +============ + +Access to the vSphere API is governed by the various vSphere Editions which provides both read and write access to the API. +If you are using vSphere Hypervisor (free edition of ESXi), the vSphere API will only be available as read-only. +All modules requires API write access to perform various actions. Hence, a free ESXi license will not be supported. +Please check `this blog post <https://blogs.vmware.com/vsphere/2012/02/introduction-to-the-vsphere-api-part-1.html>`_ for more details. + + +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. diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_scenarios.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_scenarios.rst new file mode 100644 index 000000000..e34aa43d5 --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_scenarios.rst @@ -0,0 +1,17 @@ +.. _ansible_collections.community.vmware.docsite.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 diff --git a/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_troubleshooting.rst b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_troubleshooting.rst new file mode 100644 index 000000000..b0243c28c --- /dev/null +++ b/ansible_collections/community/vmware/docs/docsite/rst/vmware_scenarios/vmware_troubleshooting.rst @@ -0,0 +1,103 @@ +.. _ansible_collections.community.vmware.docsite.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`` |