<commit_before>.. _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: <EMAIL>
    vcenter_password: <PASSWORD>
    vcenter_hostname: vcenter.test
    vmware_validate_certs: false
    esxi1_username: root
    esxi1_hostname: esxi1.test
    esxi1_password: <PASSWORD>
    esxi2_username: root
    esxi2_hostname: test2.test
    esxi2_password: <PASSWORD><commit_msg>vmware guidlines: adjust the location of cloud-config-vcenter.ini.template (#62970)<commit_after>.. _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/lib/ansible_test/config/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: <PASSWORD>
    vcenter_hostname: vcenter.test
    vmware_validate_certs: false
    esxi1_username: root
    esxi1_hostname: esxi1.test
    esxi1_password: <PASSWORD>
    esxi2_username: root
    esxi2_hostname: test2.test
    esxi2_password: <PASSWORD>
{'fraction_non_alphanumeric': 0.143646408839779, 'fraction_numerical': 0.015883977900552487, 'mean_word_length': 3.6928062216461437, 'pattern_counts': {'":': 0, '<': 24, '<?xml version=': 0, '>': 24, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 5, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2366737', 'n_tokens_mistral': 2237, 'n_tokens_neox': 2092, 'n_words': 770}