From 13de8686e5195995508c3e4f95c472569a3885fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gon=C3=A9ri=20Le=20Bouder?= Date: Wed, 22 May 2019 16:01:36 -0400 Subject: [PATCH] vmware: vmware_guidelines.rst VMware specific documentation that explains: - how to run the functional tests - and the conventions. - clarify the difference between govcsim and vcsim Co-Authored-By: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-Authored-By: Abhijeet Kasurde --- docs/docsite/rst/dev_guide/index.rst | 2 + .../dev_guide/platforms/vmware_guidelines.rst | 189 ++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index 645bc4fba5f..9ccc1e87346 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -28,6 +28,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 `. * 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, etc.). * I want to refine my code: @@ -69,6 +70,7 @@ If you prefer to read the entire guide, here's a list of the pages in order. platforms/aws_guidelines platforms/openstack_guidelines platforms/ovirt_dev_guide + platforms/vmware_guidelines developing_modules_in_groups testing module_lifecycle diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst new file mode 100644 index 00000000000..b8411cde92a --- /dev/null +++ b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst @@ -0,0 +1,189 @@ +.. _VMware_module_development: + +**************************************** +Guidelines for VMware module development +**************************************** + +The VMware modules and these guidelines are maintained by the VMware Working Group. For +further 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 in the :file:`test/integration/targets/`. + +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's much more fast that than a regular test environment. However, it does not +support all the ESXi or vCenter features. + +.. note:: + + Do not confuse ``govcsim`` with ``vcsim``. It's old outdated version of vCenter simulator whereas govcsim is new and written in go lang + +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/integration/cloud-config-vcenter.ini.template`. For instance, if you've 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_username: root + esxi1_hostname: esxi1.test + esxi1_password: root + esxi2_username: root + esxi2_hostname: test2.test + esxi2_password: root + +If you use an HTTP proxy +------------------------- +Support for hosting test infrastructure behind an HTTP proxy is currently in development. See the following pull requests for more information: + +- ansible-test: vcenter behind an HTTP proxy +- pyvmomi: proxy support +- VMware: add support for HTTP proxy in connection API + +Once you have incorporated the code from those PRs, 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 file to match the configuration of your lab: +:file:`test/integration/targets/prepare_vmware_tests/vars/real_lab.yml`. If you use `vmware-on-libvirt ` to prepare you lab, you don't 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. + +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 --tox --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.") + +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.