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 <akasurde@redhat.com>

2 files changed, 191 insertions, 0 deletions

diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst
index 645bc4fba5..9ccc1e8734 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 <AWS_module_development>`.
       * an :ref:`OpenStack module <OpenStack_module_development>`.
       * an :ref:`oVirt/RHV module <oVirt_module_development>`.
+      * a :ref:`VMware module <VMware_module_development>`.
    * I want to :ref:`write a series of related modules <developing_modules_in_groups>` 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 0000000000..b8411cde92
--- /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 <https://github.com/ansible/community/wiki/VMware>`_.
+
+.. 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 <https://github.com/vmware/govmomi/tree/master/vcsim>`_. ``ansible-test`` will automatically pull a `govcsim container <https://quay.io/repository/ansible/vcenter-test-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 <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 :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 <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_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 <https://github.com/ansible/ansible/pull/58208>
+- pyvmomi: proxy support <https://github.com/vmware/pyvmomi/pull/799>
+- VMware: add support for HTTP proxy in connection API <https://github.com/ansible/ansible/pull/52936>
+
+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 <https://github.com/goneri/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.