Using VMware HTTP API using Ansible¶
Introduction¶
This guide will show you how to utilize Ansible to use VMware HTTP APIs to automate various tasks.
Scenario requirements¶
Software
- Ansible 2.5 or later must be installed.
- We recommend installing the latest version with pip:
pip install Pyvmomi
on the Ansible control node (as the OS packages are usually out of date and incompatible) if you are planning to use any existing VMware modules.
Hardware
- vCenter Server 6.5 and above with at least one ESXi server
Access / Credentials
- Ansible (or the target server) must have network access to either the vCenter server or the ESXi server
- Username and Password for vCenter
Caveats¶
- All variable names and VMware object names are case sensitive.
- You need to use Python 2.7.9 version in order to use
validate_certs
option, as this version is capable of changing the SSL verification behaviours. - VMware HTTP APIs are introduced in vSphere 6.5 and above so minimum level required in 6.5.
- There are very limited number of APIs exposed, so you may need to rely on XMLRPC based VMware modules.
Example description¶
With the following Ansible playbook you can find the VMware ESXi host system(s) and can perform various tasks depending on the list of host systems. This is a generic example to show how Ansible can be utilized to consume VMware HTTP APIs.
---
- name: Example showing VMware HTTP API utilization
hosts: localhost
gather_facts: no
vars_files:
- vcenter_vars.yml
vars:
ansible_python_interpreter: "/usr/bin/env python3"
tasks:
- name: Login into vCenter and get cookies
uri:
url: https://{{ vcenter_server }}/rest/com/vmware/cis/session
force_basic_auth: yes
validate_certs: no
method: POST
user: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
register: login
- name: Get all hosts from vCenter using cookies from last task
uri:
url: https://{{ vcenter_server }}/rest/vcenter/host
force_basic_auth: yes
validate_certs: no
headers:
Cookie: "{{ login.set_cookie }}"
register: vchosts
- name: Change Log level configuration of the given hostsystem
vmware_host_config_manager:
hostname: "{{ vcenter_server }}"
username: "{{ vcenter_user }}"
password: "{{ vcenter_pass }}"
esxi_hostname: "{{ item.name }}"
options:
'Config.HostAgent.log.level': 'error'
validate_certs: no
loop: "{{ vchosts.json.value }}"
register: host_config_results
Since Ansible utilizes the VMware HTTP API using the uri
module to perform actions, in this use case it will be connecting directly to the VMware HTTP API from localhost.
This means that playbooks will not be running from the vCenter or ESXi Server.
Note that this play disables the gather_facts
parameter, since you don’t want to collect facts about localhost.
Before you begin, make sure you have:
- Hostname of the vCenter server
- Username and password for the vCenter server
- Version of vCenter is at least 6.5
For now, you will be entering these directly, but in a more advanced playbook this can be abstracted out and stored in a more secure fashion using ansible-vault or using Ansible Tower credentials.
If your vCenter server is not setup with proper CA certificates that can be verified from the Ansible server, then it is necessary to disable validation of these certificates by using the validate_certs
parameter. To do this you need to set validate_certs=False
in your playbook.
As you can see, we are using the uri
module in first task to login into the vCenter server and storing result in the login
variable using register. In the second task, using cookies from the first task we are gathering information about the ESXi host system.
Using this information, we are changing the ESXi host system’s advance configuration.
What to expect¶
Running this playbook can take some time, depending on your environment and network connectivity. When the run is complete you will see
"results": [
{
...
"invocation": {
"module_args": {
"cluster_name": null,
"esxi_hostname": "10.76.33.226",
"hostname": "10.65.223.114",
"options": {
"Config.HostAgent.log.level": "error"
},
"password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
"port": 443,
"username": "administrator@vsphere.local",
"validate_certs": false
}
},
"item": {
"connection_state": "CONNECTED",
"host": "host-21",
"name": "10.76.33.226",
"power_state": "POWERED_ON"
},
"msg": "Config.HostAgent.log.level changed."
...
}
]
Troubleshooting¶
If your playbook fails:
- Check if the values provided for username and password are correct.
- Check if you are using vCenter 6.5 and onwards to use this HTTP APIs.
See also
- VMware vSphere and Ansible From Zero to Useful by @arielsanchezmor
- vBrownBag session video related to VMware HTTP APIs
- Sample Playbooks for using VMware HTTP APIs
- GitHub repo for examples of Ansible playbook to manage VMware using HTTP APIs