Connecting Ansible to Windows

Once WinRM is configured, getting Ansible talking to Windows is fairly straightforward, provided you bear two caveats in mind—it expects to use the SSH protocol, and if you don't specify a user account, it will attempt to use the same user account that Ansible is being run under to connect. This is almost certainly not going to work with a Windows username.

Also, note that Ansible requires the winrm Python module installed to connect successfully. This is not always installed by default, so it is worth testing for it on your Ansible system before you start working with Windows hosts. If it's not present, you will see something like the error shown in the following screenshot:

If you see this error, you will need to install the module before proceeding any further. There may be a prepackaged version available for your OS—for example, on CentOS 7, you can install it with the following command:

sudo yum install python2-winrm

If a packaged version is not available, install it directly from pip using the following command:

sudo pip install "pywinrm>=0.3.0"

Once this is complete, we can test to see whether our earlier WinRM configuration work was successful. For SSH-based connectivity, there is an Ansible module called ping, which performs a full end-to-end test to ensure connectivity, successful authentication, and a usable Python environment on the remote system. Similarly, there exists a module called win_ping, which performs an analogous test on Windows.

In my test environment, I would prepare an inventory as follows to connect to my newly configured Windows host:

[windows]
192.168.81.150

[windows:vars]
ansible_user=Administrator
ansible_password="password"
ansible_port=5986
ansible_connection=winrm
ansible_winrm_server_cert_validation=ignore

Note the connection specific variables beginning ansible_ that are being set in the windows:vars section of the playbook. At this stage, they should be fairly self-explanatory, as they were covered earlier in the book, but, in particular, note the ansible_winrm_server_cert_validation variable, which needs to be set to ignore when working with self-signed certificates. Obviously, in a real-world example, you would not leave the ansible_password parameter in clear text—it would either be placed in an Ansible vault, or prompted for upon launch using the --ask-pass parameter.

Certificate-based authentication is also possible with WinRM, which carries with it more or less the same benefits and risks as SSH key-based authentication.

Using the previous inventory (with appropriate changes for your environment such as hostname/IP addresses and authentication details), we can run the following command to test connectivity:

ansible -i windows-hosts -m win_ping all

If all goes well, you should see some output like the following:

That completes a successful end-to-end setup of an Ansible host to a Windows one! From such a setup, you can author and run playbooks just as you would on any other system, except that you must work with Ansible modules that specifically support Windows. Next, we will work on improving the security of our connection between Ansible and Windows, before finally moving on to some examples of Windows playbooks.