Ansible for Windows: Complete Guide to Managing Windows Hosts

Ansible can manage Windows hosts just as effectively as Linux. This guide covers setting up WinRM connectivity, essential Windows modules, and common automation patterns.

Prerequisites

Windows Host Requirements

• Windows Server 2016+ or Windows 10+ • PowerShell 5.1+ • .NET Framework 4.6+ • WinRM service configured and running

Enable WinRM on Windows

Run this PowerShell script as Administrator on the Windows host:

# Quick WinRM setup for Ansible
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$url = "https://raw.githubusercontent.com/ansible/ansible-documentation/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

Or manually:

winrm quickconfig
winrm set winrm/config/service '@{AllowUnencrypted="true"}'
winrm set winrm/config/service/auth '@{Basic="true"}'

See also: Ansible Windows Server 2025 Automation: WinRM, PSRP, Active Directory, IIS, Hyper-V Complete Guide

Inventory Configuration

[windows]
win-server1 ansible_host=192.168.1.100
win-server2 ansible_host=192.168.1.101
[windows:vars]
ansible_user=Administrator
ansible_password={{ vault_win_password }}
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore
ansible_port=5986

Essential Windows Modules

win_command — Run Commands

- name: Check Windows version
  ansible.windows.win_command: systeminfo
  register: sysinfo
- name: Run executable
  ansible.windows.win_command: C:\tools\setup.exe /silent

win_shell — Run PowerShell

- name: Get running services
  ansible.windows.win_shell: Get-Service | Where-Object {$_.Status -eq 'Running'} | Select-Object Name
  register: services
- name: Run PowerShell script
  ansible.windows.win_shell: |
    $disk = Get-WmiObject Win32_LogicalDisk -Filter "DeviceID='C:'"
    $freeGB = [math]::Round($disk.FreeSpace / 1GB, 2)
    Write-Output "Free space: $freeGB GB"

win_powershell — Advanced PowerShell (Ansible 2.11+)

- name: Use win_powershell with structured output
  ansible.windows.win_powershell:
    script: |
      $result = Get-Process | Measure-Object WorkingSet -Sum
      $output = @{
        count = $result.Count
        total_mb = [math]::Round($result.Sum / 1MB, 2)
      }
      $output
  register: ps_result

win_file — File Management

- name: Create directory
  ansible.windows.win_file:
    path: C:\Apps\MyApp
    state: directory
- name: Remove file
  ansible.windows.win_file:
    path: C:\temp\old-installer.exe
    state: absent

win_copy — Copy Files

- name: Copy config file to Windows
  ansible.windows.win_copy:
    src: files/app-config.json
    dest: C:\Apps\MyApp\config.json

win_service — Manage Services

- name: Ensure IIS is running
  ansible.windows.win_service:
    name: W3SVC
    state: started
    start_mode: auto

win_feature — Install Windows Features

- name: Install IIS
  ansible.windows.win_feature:
    name: Web-Server
    state: present
    include_management_tools: true
  register: iis_install
- name: Reboot if needed
  ansible.windows.win_reboot:
  when: iis_install.reboot_required

win_package — Install Software

- name: Install 7-Zip
  ansible.windows.win_package:
    path: https://www.7-zip.org/a/7z2301-x64.msi
    product_id: '{23170F69-40C1-2702-2301-000001000000}'
    state: present

win_chocolatey — Package Manager

- name: Install packages with Chocolatey
  chocolatey.chocolatey.win_chocolatey:
    name: "{{ item }}"
    state: present
  loop:
    - googlechrome
    - vscode
    - git
    - notepadplusplus

See also: Ansible on Windows Server 2022 Automation: WinRM, Active Directory, IIS, Hyper-V Complete Guide

Windows Reboot Management

- name: Reboot and wait for connection
  ansible.windows.win_reboot:
    reboot_timeout: 600
    post_reboot_delay: 30
    test_command: whoami

Windows Registry

- name: Set registry value
  ansible.windows.win_regedit:
    path: HKLM:\SOFTWARE\MyApp
    name: Version
    data: "2.0"
    type: string

See also: Automating Windows Installations with Ansible for IT Efficiency

Common Patterns

Deploy IIS Website

- name: Deploy web application
  hosts: windows
  tasks:
    - name: Install IIS
      ansible.windows.win_feature:
        name: Web-Server
        state: present
- name: Create site directory
      ansible.windows.win_file:
        path: C:\inetpub\mysite
        state: directory
- name: Copy website files
      ansible.windows.win_copy:
        src: website/
        dest: C:\inetpub\mysite\
- name: Configure IIS site
      community.windows.win_iis_website:
        name: MySite
        physical_path: C:\inetpub\mysite
        port: 80
        state: started

FAQ

Can I use SSH instead of WinRM?

Yes, since Ansible 2.8 with OpenSSH on Windows 10+ / Server 2019+. Set ansible_connection=ssh in your inventory. WinRM is still more widely used.

Why does my Windows task hang?

Common causes: WinRM timeout (increase ansible_winrm_operation_timeout_sec), firewall blocking port 5985/5986, or interactive prompts in scripts.

What's the difference between win_command, win_shell, and win_powershell?

win_command runs executables directly. win_shell runs through PowerShell. win_powershell (newer) supports structured output and error handling.

Related Articles

• managing Windows hosts with Ansible • vault password files in Ansible • when expressions and Jinja2 in Ansible • Ansible Inventory Guide • iterating tasks with Ansible loops • Ansible win_shell and win_command Guide • Can Ansible Manage Windows Hosts? • Automating Windows Installations with Ansible