From b69eb28ed2fdcdfd41cea8cf487c43e7af4260e1 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Wed, 1 Jun 2022 18:23:10 +0200 Subject: [PATCH] Migrate community.vmware Dev Guide to collection (#77723) --- docs/docsite/rst/dev_guide/ansible_index.rst | 2 +- .../dev_guide/platforms/vmware_guidelines.rst | 261 +----------------- 2 files changed, 4 insertions(+), 259 deletions(-) diff --git a/docs/docsite/rst/dev_guide/ansible_index.rst b/docs/docsite/rst/dev_guide/ansible_index.rst index 46507fb4dcb..a62b446b70f 100644 --- a/docs/docsite/rst/dev_guide/ansible_index.rst +++ b/docs/docsite/rst/dev_guide/ansible_index.rst @@ -38,7 +38,7 @@ Find the task that best describes what you want to do: * an :ref:`Amazon module `. * an :ref:`OpenStack module `. * an :ref:`oVirt/RHV module `. - * a :ref:`VMware module `. + * a :ref:`VMware module `. * I want to :ref:`write a series of related modules ` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on). * I want to refine my code: diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst index 2865321e5c4..dc05302d6f5 100644 --- a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst @@ -1,262 +1,7 @@ .. _VMware_module_development: -**************************************** +****************************************************** Guidelines for VMware module development -**************************************** +****************************************************** -The Ansible VMware collection (on `Galaxy `_, source code `repository `_) is maintained by the VMware Working Group. For more information see the `team community page `_. - -.. contents:: - :local: - -Testing with govcsim -==================== - -Most of the existing modules are covered by functional tests. The tests are located `here `_. - -By default, the tests run against a vCenter API simulator called `govcsim `_. ``ansible-test`` will automatically pull a `govcsim container `_ and use it to set-up the test environment. - -You can trigger the test of a module manually with the ``ansible-test`` command. For example, to trigger ``vcenter_folder`` tests: - -.. code-block:: shell - - source hacking/env-setup - ansible-test integration --python 3.7 vcenter_folder - -``govcsim`` is handy because it is much faster than a regular test environment. However, ``govcsim`` does not -support all the ESXi or vCenter features. - -.. note:: - - Do not confuse ``govcsim`` with ``vcsim``. ``vcsim`` is an older and outdated version of vCenter simulator, whereas ``govcsim`` is new and written in Go language. - -Testing with your own infrastructure -==================================== - -You can also 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 `_ - - `requests `_ - -If you want to deploy your test environment in a hypervisor, both `VMware or 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 :file:`test/integration/cloud-config-vcenter.ini` and based on -:file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with -`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 `_ 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 `_. - - -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` process. - -The test-suite uses a set of common, pre-defined vars located `in 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 - -We also refer to vcsim's Go implementation with ``govcsim``. This to avoid any confusion with the outdated implementation. +This guide has moved to :ref:`ansible_collections.community.vmware.docsite.vmware_ansible_devguide`.