How to start using Ansible for Windows management

Set up the control machine

To configure the Ansible control machine to manage hosts, enable PowerShell remoting on the host and give the appropriate credentials to Ansible for Windows administration, usually with a Secure Socket Shell key.

Make sure the Ansible control machine runs on a valid version of Python with an updated version of pip, then run the following command to install the pywinrm module:

$ pip install "pywinrm>=0.2.2"

Being able to copy and run your current PowerShell scripts is a quick way to get started with the Ansible console before learning how to dive deep into the Ansible playbook management approach.

Use the following code to add the Windows machine you want to control to the /etc/ansible/hosts file so Ansible registers the Windows machine:

[groupname]
192.168.1.1

Next, add the following configuration to Ansible in the /etc/ansible/group_vars/groupname.yaml file for basic authentication:

ansible_user: 'YourHostsUsername'
ansible_password: 'YourHostsPassword'
ansible_connection: 'winrm'
ansible_winrm_transport: basic
ansible_port: '5986'
ansible_winrm_server_cert_validation: ignore
validate_certs: false

Set up the host

Be sure the Windows machine you want to manage is on a supported version of Windows -- version 7 or later for desktops and 2008 or later for Windows Server -- and PowerShell 3.0 or later.

Next, enable PSRemoting with this command:

Enable-PSRemoting -force

Then, set up the WinRM service -- required to use PowerShell remoting -- to start automatically.

Set-Service WinRM -StartMode Automatic

On the local machine, confirm you've started the WinRM service with the following cmdlet:

Test-WSMan

From a remote computer, add the -ComputerName parameter:

Test-WSMan -ComputerName "server123"

Next, set up a WinRM Listener with the PowerShell script below from Ansible. It sets up an HTTP and HTTPS listener, as well as configure basic authentication on the host. It might require some adjustments to use in a production environment.

$url="https://raw.githubusercontent.com/ansible/ansible/devel/ examples/scripts/ConfigureRemotingForAnsible.ps1"
$file="$env:temp\ConfigureRemotingForAnsible.ps1"

(New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file)

powershell.exe -ExecutionPolicy ByPass -File $file

For this tutorial, we use basic authentication, which you enable with the following command:

Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true

Lastly, complete the host configuration for Ansible by creating the WinRM listener.

winrm quickconfig

This Ansible for Windows tutorial is tailored for managing an individual server. To deploy this configuration on many machines, create a group policy and deploy that to the Windows servers. The group policy should set the WinRM service to start automatically, run the configuration script and configure the WinRM listeners.

How to work with Ansible for Windows machine management

After finalizing the configuration from the Ansible server to the remote managed machine, you can run tasks remotely from the Ansible server.

First, test connectivity with a ping from the Ansible host.

$ ansible groupname -m win_ping

192.168.1.158 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

To run ad hoc commands on Windows from Ansible, you can easily create one-liners by calling the win_shell module. A simple example is stopping a service remotely for a group of machines from the Ansible console:

$ ansible groupname -m win_shell -a "Get-Service -Name servicename | Stop-Service"

You also have access to the win_command module to run executables remotely.

$ ansible groupname -m win_command -a whoami.exe

How to run an Ansible for Windows script

Another example of Ansible management of remote Windows servers is to copy a local PowerShell script to the remote managed machine.

$ ansible groupname -m win_copy -a "src=/path/to/script.ps1 dest=C:\temp\script.ps1"

You can then run the script with the win_command module.

$ ansible groupname -m win_command -a "powershell.exe -ExecutionPolicy ByPass -File C:\temp\script.ps1"

Ansible opens the door to advanced management capabilities

Ansible is worth learning due to its cross-platform capabilities that scale to manage a large number of devices. Once you've learned the basics, you can perform more in-depth tasks, such as using PowerShell Desired State Configuration with Ansible and working with custom modules.