No additional software needs to be installed on the remote machines for Ansible to manage them, it still maintains the agentless properties that make it popular on Linux/Unix.
Ansible's windows support relies on a few standard variables to indicate the username, password, and connection type (windows) of the remote hosts. These variables are most easily set up in inventory. This is used instead of SSH-keys or passwords as normally fed into Ansible.
Notice that the ssh_port is not actually for SSH, but this is a holdover from how Ansible is mostly an SSH-oriented system. Again, Windows management will not happen over SSH.
When using your playbook, don't forget to specify --ask-vault-pass to provide the password to unlock the file.
Test your configuration like so, by trying to contact your Windows nodes. Note this is not an ICMP ping, but tests the Ansible
communication channel that leverages Windows remoting::
ansible windows [-i inventory] -m ping --ask-vault-pass
.._windows_what_modules_are_available:
What modules are available
``````````````````````````
Most of the Ansible modules in core Ansible are written for a combination of Linux/Unix machines and arbitrary web services, though there are various
Windows modules as listed in the "windows" subcategory of the Ansible module index.
Browse this index to see what is available.
In many cases, it may not be neccessary to even write or use an Ansible module.
In particular, the "win_script" module can be used to run arbitrary powershell scripts, allowing Windows administrators familiar with powershell a very
native way to do things, as in the following playbook:
- hosts: windows
tasks:
- win_script: foo.ps1 --argument --other-argument
.._windows_developers_developers_developers:
Developers: Supported modules and how it works
``````````````````````````````````````````````
Developing ansible modules are covered in a later section, with a focus on Linux/Unix.
For Windows, ansible modules are implemented in Powershell. Skim the module development chapters before proceeding.
Windows modules live in a "windows/" subfolder in the Ansible "library/" subtree. For example, if a module is named
"library/windows/win_ping", there will be embedded documentation in the "win_ping" file, and the actual powershell code will
live in a "win_ping.ps1" file.
Modules (ps1 files) should start as follows::
#!powershell
# WANT_JSON
# POWERSHELL_COMMON
# <license>
# code goes here, reading in stdin as JSON and outputting JSON
The above magic is neccessary to tell Ansible to mix in some common code and also know how to push modules out.
Taking a look at the sources for win_ping and the equivalent will make it easier to understand how things work by following
the existing patterns.
Additional modules may be submitted as pull requests to github.
.._windows_system_prep:
System Prep
```````````
In order for Ansible to manage your windows machines you will have to enable powershell remoting first::
How to do it goes here
.._windows_and_linux_control_machine:
You Must Have a Linux Control Machine
`````````````````````````````````````
Note running Ansible from a Windows control machine is NOT a goal of the project. Refrain from asking for this feature,
as it limits what technologies, features, and code we can use in the main project in the future. A Linux control machine
will be required to manage Windows hosts.
Cygwin is not supported, so please do not ask questions about Ansible running from Cygwin.
Just as with Linux/Unix, facts can be gathered for windows hosts, which will return things such as the operating system version. To see what variables are available about a windows host, run the following::
ansible winhost.example.com -m setup
Note that this command invocation is exactly the same as the Linux/Unix equivalent.
.._windows_playbook_example:
Windows Playbook Examples
`````````````````````````
Look to the list of windows modules for most of what is possible, though also some modules like "raw" and "script" also work on Windows, as do "fetch" and "slurp".
Here is an example of pushing and running a powershell script::
- name: test script module
hosts: windows
tasks:
- name: run test script
script: files/test_script.ps1
Running individual commands uses the 'raw' module, as opposed to the shell or command module as is common on Linux/Unix operating systems::
- name: test raw module
hosts: windows
tasks:
- name: run ipconfig
raw: ipconfig
register: ipconfig
- debug: var=ipconfig
And for a final example, here's how to use the win_stat module to test for file existance. Note that the data returned byt he win_stat module is slightly different than what is provided by the Linux equivalent.
- name: test stat module
hosts: windows
tasks:
- name: test stat module on file
win_stat: path="C:/Windows/win.ini"
register: stat_file
- debug: var=stat_file
- name: check stat_file result
assert:
that:
- "stat_file.stat.exists"
- "not stat_file.stat.isdir"
- "stat_file.stat.size > 0"
- "stat_file.stat.md5"
Again, recall that the Windows modules are all listed in the Windows category of modules, with the exception that the "raw", "script", and "fetch" modules are also available. These modules do not start with a "win_" prefix.
.._windows_contributions:
Windows Contributions
`````````````````````
Windows support in Ansible is still very new, and contributions are quite welcome, whether this is in the
form of new modules, tweaks to existing modules, documentation, or something else. Please stop by the ansible-devel mailing list if you would like to get involved and say hi.
