We want to hear from you! Help us gain insights into the state of the Ansible ecosystem.
Take the Ansible Project Survey 2024

Introducing the VMware REST Ansible Content Collection

Source

Introducing the VMware REST Ansible Content Collection

The VMware Ansible modules as part of the current community.vmware Collection are extremely popular. According to GitHub, it's the second most forked Collection, just after community.general. The VMware modules and plugins for Ansible have benefited from a stream of contributions from dozens of users. Many IT infrastructure engineers rely on managing their VMware infrastructure by means of a simple Ansible Playbook. The vast majority of the current VMware modules are built on top of a dependent python library called pyVmomi, also known as vSphere Automation SDK for Python.

Why a new VMware Ansible Content Collection?

VMware has recently introduced the vSphere REST API for vSphere 6.0 and later, which will likely replace the existing SOAP SDK used in the community.vmware Collection.

Since the REST API's initial release, vSphere support for the REST API has only improved. Furthermore, there is no longer a need for any dependent python packages. In order to maintain the existing VMware modules in the community.vmware Collection, a set of modules specifically for interacting with the VMware REST API is now available in the newly created vmware.vmware_rest Collection.

If you compare modules used with the VMware vSphere API (SOAP) to the ones using the REST API, you'll notice the REST API modules are not yet feature complete, as this is an early release of the Collection. For example, there currently is no way to create a cluster or a folder using the modules in the vmware.vmware_rest Collection, but the API provides all you need for a VMware guest for future Collection enablement and much more.

Using the VMware REST API

In order to understand how the new modules function against the new REST API, let's take a look at the REST API itself first. For example, the com.vmware.vcenter.vm.power API endpoint changes the power state of a VM. It's equivalent to the following sample URL:

https://vcenter.test/rest/vcenter/vm/\$vm/power

With the vCenter 7.0 release, 723 total REST endpoints are exposed, which can be discovered using the following curl command:

$ curl -k https://vcenter.test/rest/com/vmware/vapi/metadata/cli/command|jq -r ".[][].path"|uniq|wc -l
723

The VMware REST APIs are documented in the Swagger 2.0 format. You can find the JSON files on your vCenter node in the following directory path:

root@vcenter [ /etc/vmware-vapi/apiexplorer/json ]# ls -lh
total 3.3M
-rw-r--r-- 1 vapiEndpoint users  145 Aug 31 15:37 api.json
-rw-r--r-- 1 vapiEndpoint users 396K Aug 31 15:36 appliance.json
-rw-r--r-- 1 vapiEndpoint users 153K Aug 31 15:36 cis.json
-rw-r--r-- 1 vapiEndpoint users 272K Aug 31 15:37 content.json
-rw-r--r-- 1 vapiEndpoint users 395K Aug 31 15:36 esx.json
-rw-r--r-- 1 vapiEndpoint users 153K Aug 31 15:36 stats.json
-rw-r--r-- 1 vapiEndpoint users 176K Aug 31 15:37 vapi.json
-rw-r--r-- 1 vapiEndpoint users 1.8M Aug 31 15:36 vcenter.json

To summarize, the vmware.vmware_rest Collection has all these REST endpoints ready to be consumed with the descriptions in a well documented format.

Building the vmware_rest Collection

The modules contained in this Collection are generated using a tool called  vmware_rest_code_generator, which was developed and open sourced by the Ansible team. It loads the Swagger files and then auto-generates a module per each resource, generating more than 300 modules this way. You'll notice that not every module has been released to the Collection. For purposes of starting small, we are only generating modules against a subset of the endpoints exposed, only those associated with guest management use cases. We may expand and extend the number of modules over time.

Using the vmware_rest Collection

The following tasks retrieve a list of the VM, shuts them down, and then deletes them:

- name: Collect the list of the existing VM
  vcenter_vm_info:
  register: existing_vms
  until: existing_vms is not failed

- name: Turn off the VM
  vcenter_vm_power:
    state: stop
    vm: '{{ item.vm }}'
  with_items: "{{ existing_vms.value }}"
  ignore_errors: yes

- name: Delete some VM
  vcenter_vm:
    state: absent
    vm: '{{ item.vm }}'
  with_items: "{{ existing_vms.value }}"

Refer to the following gist file for more information: https://gist.github.com/goneri/6afd05397390cf5a0976f3611814949a

Downloading the vmware_rest Collection

The goal of this early release is to get as much community feedback as possible.

The Collection is available on Ansible Galaxy, and requires the following:

  • Ansible 2.9 or later 
  • Python 3.6 or later
  • The aiohttp package

Use the ansible-galaxy command to retrieve the Collection:

# ansible-galaxy collection install vmware.vmware_rest

If you use a virtualenv, you can install aiohttp with following command:

# pip install aiohttp

Else, you will need to download and install the python3-aiohttp package.

To read the module documentation, use the ansible-doc command. For example, to read documentation for the vcenter_cluster_info module, refer to the following command:

# ansible-doc -t module vmware.vmware_rest.vcenter_cluster_info

vCenter-Managed Object Reference ID

If you are already using the community.vmware Collection, the main difference is that the newer modules rely on the MORef ID to identify the elements instead of the name of the object. For example, if the user creates a datacenter called dc1, the MORef ID using the new modules will be datacenter-2. The community.vmware Collection uses the name and the folder instead.

By using the MORef ID directly, the module is able to interact with the resource without any time consuming preliminary look up.

How can I contribute?

Because the modules are auto-generated, it GitHub pull requests should be raised against the code generator itself, and not the resulting Collection contents.

Don't hesitate to report any issues on the GitHub project at https://github.com/ansible-collections/vmware_rest/issues.

Reference:

The forks per collection can be found programmatically by accessing the Github API: https://api.github.com/orgs/ansible-collections/repos 

This can be sorted, for example:

method: curl -s https://api.github.com/orgs/ansible-collections/repos|jq -r -c --sort-keys '.|sort_by(.forks)|reverse|.[]|[.name, .forks]'
Powered by