Guidelines for VMware module development

The VMware modules and these guidelines are maintained by the VMware Working Group. Forfurther information see the team community page.

Testing with govcsim

Most of the existing modules are covered by functional tests. The tests are located in the test/integration/targets/.

By default, the tests run against a vCenter API simulator called govcsim. ansible-test will automatically pull a govcsim container <https://quay.io/repository/ansible/vcenter-test-container&gt; 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:

  1. source hacking/env-setup
  2. 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 notsupport 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

NFS server configuration

Your NFS server must expose the following directory structure:

  1. $ tree /srv/share/
  2. /srv/share/
  3. ├── isos
  4. │   ├── base.iso
  5. │   ├── centos.iso
  6. │   └── fedora.iso
  7. └── vms
  8. 2 directories, 3 files

On a Linux system, you can expose the directory over NFS with the following export file:

  1. $ cat /etc/exports
  2. /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:

  1. $ sudo systemctl enable --now nfs-server

Configure your installation

Prepare a configuration file that describes your set-up. The fileshould be called test/integration/cloud-config-vcenter.ini and based ontest/lib/ansibletest/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&gt;:

  1. [DEFAULT]
  2. vcenter_username: [email protected]
  3. vcenter_password: !234AaAa56
  4. vcenter_hostname: vcenter.test
  5. vmware_validate_certs: false
  6. esxi1_username: root
  7. esxi1_hostname: esxi1.test
  8. esxi1_password: root
  9. esxi2_username: root
  10. esxi2_hostname: test2.test
  11. 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:

Once you have incorporated the code from those PRs, specify the location of the proxy server with the two extra keys:

  1. vmware_proxy_host: esxi1-gw.ws.testing.ansible.com
  2. vmware_proxy_port: 11153

In addition, you may need to adjust the variables of the following file to match the configuration of your lab:test/integration/targets/preparevmware_tests/vars/real_lab.yml. If you use _vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt&gt; 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:

  1. source hacking/env-setup
  2. 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 intest/integration/targets/vmware_guest/defaults/main.yml.

Unit-test

The VMware modules have limited unit-test coverage. You can run the test suite with thefollowing commands:

  1. source hacking/env-setup
  2. 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 maynot 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.

  1. if self.is_vcenter():
  2.     esxi_hostname = module.params.get('esxi_hostname')
  3.     if not esxi_hostname:
  4.         self.module.fail_json("esxi_hostname parameter is mandatory")
  5.     self.host = self.get_all_host_objs(cluster_name=cluster_name, esxi_host_name=esxi_hostname)[0]
  6. else:
  7.     self.host = find_obj(self.content, [vim.HostSystem], None)
  8. if self.host is None:
  9.     self.module.fail_json(msg="Failed to find host system.")

Functional tests

Writing new tests

If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyondthe standard Ansible integration testing process.

The test-suite uses a set of common, pre-defined vars located in the test/integration/targets/prepare_vmware_tests/ role.The resources defined there are automatically created by importing that role at the start of your test:

  1. - import_role:
  2.     name: prepare_vmware_tests
  3.   vars:
  4.     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. Thisway it will be automatically clean up for you.

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.