How to Use Ansible to Manage Windows Machines

Ansible is the popular free open-source configuration management system used primarily to manage Linux hosts. This article describes how to use Ansible to remotely manage the configuration of Windows servers and workstation hosts.

Configuring Windows Hosts for Ansible

Ansible allows you to remotely manage Windows hosts with all supported OS versions, starting from Windows 7/Windows Server 2008 and up to the latest Windows 11/Windows Server 2022. On Windows, you must have PowerShell 3.0 (or newer) and .NET 4.0+ installed.

Ansible uses WinRM to connect to the Windows operating system. Therefore, you need to enable and configure the WinRM listener on all managed Windows hosts.

• Group Policies can be used to configure WinRM on domain computers in AD;
• Run the following PowerShell command to enable WinRM on a standalone Windows host: Enable-PSRemoting –Force

If you have WinRM enabled and configured on Windows hosts, check that the TCP/5985 or TCP/5986 port (if using HTTPS) is accessible from the management Ansible server:

$ nc -zv 192.168.13.122 5985

Then you need to choose the authentication method. This will depend on the environment you are using Ansible.

• For a standalone computer or workgroup environment, you can use HTTPS for WinRM with self-signed certificates and authentication using a local Windows account with administrator privileges. For quick configuration of a Windows host, you can use the ConfigureRemotingForAnsible.ps1 (https://github.com/ansible/ansible-documentation/blob/devel/examples/scripts/ConfigureRemotingForAnsible.ps1 );
• In my case, all Windows hosts are joined to the Active Directory domain, so I’ll use my AD account to authenticate to Ansible. This requires configuring Kerberos authentication on the Ansible server (see below).

Install the packages required for Kerberos authentication:

• For RHEL/Rocky Linux/CentOS via yum/dnf package manager:
  $ sudo yum -y install python-devel krb5-devel krb5-libs krb5-workstation
• For Ubuntu/Debian:
  $ sudo apt-get -y install python-dev libkrb5-dev krb5-user

Then install the Python package via pip:

$ sudo pip3 install requests-kerberos

Specify the connection settings for your domain in the Kerberos conf file:

$ sudo mcedit /etc/krb5.conf

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log
[libdefaults]
 dns_lookup_realm = false
 ticket_lifetime = 24h
 renew_lifetime = 7d
 forwardable = true
 rdns = false
default_realm = WOSHUB.LOC
[realms]
  WOSHUB.LOC = {
    admin_server = dc01.woshub.loc
    kdc = dc01.woshub.loc
  }
[domain_realm]
 woshub.loc = WOSHUB.LOC
 .WOSHUB.LOC = WOSHUB.LOC

Check that you can authenticate to your AD domain and get a Kerberos ticket:

kinit -C [email protected]
Enter your AD user password and see if the ticket is received.

klist

Managing Windows Hosts with Ansible

Next, add all your Windows hosts to the Ansible inventory file:

$ sudo mcedit /etc/ansible/hosts

mun-rds1.woshub.loc
mun-dc02.woshub.loc
wks-test1.woshub.loc
[windows_all:vars]
ansible_port=5985
[email protected]
ansible_connection=winrm
ansible_winrm_transport=kerberos
ansible_winrm_scheme=http
ansible_winrm_server_cert_validation=ignore

Check that all your Windows hosts (my list includes two Windows Server 2019 and one Windows 11 machine) are accessible from Ansible:

$ ansible windows_all -m win_ping

"msg": "kerberos: Bad HTTP response returned from server. Code 500",
"unreachable": true

Now you can use Ansible to run an arbitrary command on all of your Windows hosts. For example, I want to reset the DNS cache on all my Windows machines:

$ ansible windows_all -m win_shell -a "ipconfig /flushdns"

Ansible Playbook Examples for Windows Administration

Your Windows hosts are now ready to run Ansible playbooks.

For example, you need to run a PowerShell script on all hosts using Ansible (in this example, we will use PowerShell to get the current IP or DNS settings on the hosts). Create a playbook file:

$ sudo mcedit /etc/ansible/playbooks/win-exec-powershell.yml

---
- name: win_powershell_exec
  hosts: windows_all
  tasks:
    - name: check DNS
      win_shell: |
        Get-DnsClientServerAddress -InterfaceIndex (Get-NetAdapter|where Status -eq "Up").ifindex -ErrorAction SilentlyContinue
      register: command_output
    - name: command output
      ansible.builtin.debug:

Run the playbook:

$ ansible-playbook /etc/ansible/playbooks/win-exec-powershell.yml

In this example, the playbook was successfully executed on all of the Windows hosts and the current DNS settings were returned.

Let’s take a look at some typical Ansible playbooks for standard Windows host management tasks.

Copy a file:

  - name: Copy a single file
    win_copy:
      src: /home/sysops/files/test.ps1"
      dest: C:\Temp\test.ps1

Create a file:

- name: Create file
  win_file:
    path: C:\Temp\file.txt
    state: touch

Delete a file:

- name: Delete file
  win_file:
    path: C:\Temp\file.txt
    state: absent

Create a registry parameter:

- name: Create reg dword 
  win_regedit: 
    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\DataCollection
    name: AllowTelemetry
    data: 0
    type: dword

Install a program from MSI:

- name: Install MSI package
  win_package:
    path: C:\Distr\adobereader.msi
    arguments:
      - /install
      - /passive
      - /norestart

Run a Windows service:

- name: Run Windows Service
  win_service: 
    name: wuauserv
    state: started

Install a Windows Server role:

  - name: Install Windows Feature
    win_feature:
      name: SNMP-Service
      state: present

Open a port in Windows Defender Firewall:

- name: Open SSH Port
  win_firewall_rule:
    name: port 22
    localport: 22
    action: allow
    direction: in
    protocol: tcp
    state: present
    enabled: yes

Run a PowerShell script:

- name: Run PowerShell Script
  win_command: powershell.exe -ExecutionPolicy ByPass -File C:/temp/powershellscript.ps1

Throughout this article, you have learned how to manage the configuration of your Windows hosts through Ansible. If your Windows hosts are not joined to an Active Directory domain (they are in a workgroup), then remote configuration management of Windows hosts using Ansible can be a good alternative to configuration using domain Group Policies.