Ansible WinRM Module: Manage Windows Hosts Remotely

The Ansible WinRM module for Windows allows you to automate and manage Windows systems remotely using WinRM. It enables you to run commands, deploy software, and configure settings on Windows servers without needing additional agents.

This module simplifies cross-platform automation by integrating Windows management into Ansible’s unified automation framework, making it easier to maintain consistency and enforce policies across both Windows and Linux environments.

In this guide, we’ll explain how to use the Ansible WinRM module to connect and manage Windows machines remotely.

Prerequisites

Before you begin, ensure you have the following:

• Ansible is installed on a Linux control machine.
• A Windows host machine to manage.
• Administrative access to both the Ansible control machine and the Windows host.

Step 1: Configure the Windows Host

Ensure that the PowerShell execution policy allows running scripts. You can set it to RemoteSigned or Unrestricted if needed.

Open a PowerShell session as an administrator and run the following command:

 # Set-ExecutionPolicy RemoteSigned

Download the ConfigureRemotingForAnsible.ps1 script from the Git repository.

 # Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AlbanAndrieu/ansible-windows/master/files/ConfigureRemotingForAnsible.ps1" -OutFile "ConfigureRemotingForAnsible.ps1"

Execute the downloaded script with administrative privileges to configure the Windows machine for Ansible.

 # .\ConfigureRemotingForAnsible.ps1

This script performs the following tasks.

• Starts and enable the WinRM service.
• Adds inbound firewall rules to allow WinRM traffic through the default ports (5985 for HTTP and 5986 for HTTPS).
• Configures WinRM to trust the Ansible control machine’s IP address if needed.
• Sets up SSL for encrypted communication. You’ll need to generate or obtain a certificate for this purpose.

After running the script, verify that WinRM is properly set up.

 # Test-WSMan

If WinRM is correctly set up, the output should look something like:

Configure Ansible Control Machine

On the Ansible control machine, you need to install some Python packages and configure Ansible to interact with the Windows host.

Install the pywinrm package using pip.

 # pip install pywinrm

If you plan to use Kerberos for authentication, install the requests-kerberos package:

 # pip install requests-kerberos

Edit the Ansible main configuration file /etc/ansible/ansible.cfg and add the correct settings for the WinRM connection.

[defaults]
host_key_checking = False

[winrm]
transport = ntlm
server_cert_validation = ignore

Modify your Ansible inventory to include the Windows host. Create or edit the hosts file, typically located in /etc/ansible/hosts.

 # nano /etc/ansible/hosts

Add the following lines to the inventory file:

[windows]
windows_host ansible_host=Windows_Host_IP

[windows:vars]
ansible_user=Username
ansible_password=Password
ansible_port=5985
ansible_connection=winrm
ansible_winrm_transport=basic
ansible_winrm_server_cert_validation=ignore

Replace Windows_Host_IP, Username, and Password with the actual IP address, username, and password of the Windows host.

Test Ansible Connectivity

Run a simple Ansible command to test the connection.

 # ansible windows -m win_ping

If Ansible can successfully communicate with the Windows host via WinRM, you’ll receive a successful response indicating that the connection is working.

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

You can also create a simple Ansible playbook to test the connection.

 # nano test_winrm.yml

Add the following configuration.

---
- name: Test WinRM Connection
  hosts: windows
  tasks:
    - name: Gather facts from Windows hosts
      win_ping:

Run the playbook with the following command.

 # ansible-playbook test_winrm.yml

You should see an output indicating a successful connection if everything is set up correctly.

PLAY [Test WinRM Connection] ***************************************************

TASK [Gather facts from Windows hosts] *****************************************
ok: [windows_host]

PLAY RECAP *********************************************************************
windows_host               : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Example 1: Playbook for Installing Software

Create a playbook named install_software.yml to install software named 7zip on the Windows host.

---
- name: Install Software on Windows
  hosts: windows
  tasks:
    - name: Install 7-Zip
      win_chocolatey:
        name: 7zip
        state: present

Execute the playbook with the following command:

 # ansible-playbook install_software.yml

Output.

Example 2: Playbook for Running a PowerShell Script

Create a playbook named run_powershell.yml to run a PowerShell script on the Windows host.

---
- name: Run PowerShell Script on Windows
  hosts: windows
  tasks:
    - name: Run a PowerShell script
      win_shell: |
        Write-Output "Hello from Ansible!"

Execute the playbook with the following command:

 # ansible-playbook run_powershell.yml

Conclusion

You can now connect Ansible to a Windows host using the WinRM module.  Ansible WinRM module allows you to automate and manage Windows systems with your Linux infrastructure. You can now create and run playbooks to install software, configure settings, and execute scripts on Windows hosts, enhancing your automation capabilities across different operating systems.

FAQs