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.

Testing with your own infrastructure 

You can 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:

$ 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:

$ 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:

$ sudo systemctl enable --now nfs-server

Prepare a configuration file that describes your set-up. The file should be called test/integration/cloud-config-vcenter.ini and based on test/lib/ansible_test/config/cloud-config-vcenter.ini.template. For instance, if you have deployed your lab with vmware-on-libvirt:

[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:

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:

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:

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.

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 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:

- 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.

hostname
username
password
validate_certs

For example, the following block:

- 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:

- 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