How to use Ansible with Windows for server management

What is Ansible?

Ansible itself is an agentless, open-source configuration management tool. You define a configuration in YAML and use the Ansible command line tool to execute it against a set of remote hosts. In an enterprise configuration, you can set up the free AWX management platform or pay for the Red Hat Ansible Automation Platform. The examples in this article focus on the command line tools.

What are the benefits of Ansible with Windows systems?

The biggest difference between Ansible and other configuration management tools is it does not require an agent to manage the hosts. Instead, Ansible remotely connects to the servers via SSH or WinRM from a computer that functions as the control node.

You define a host's configuration using declarative syntax -- you describe the desired system state and let the system work out how to get there. Ansible uses playbooks written in YAML to configure systems.

Ansible playbooks use collections to bundle material -- such as plugins, roles and modules -- for configuration changes.

How to set up Ansible

You can create the Ansible control node on nearly any Unix-like operating system, such as Red Hat, Ubuntu or MacOS. You can also use Windows via the Windows Subsystem for Linux. The only software requirement is Python 3.9. If you need to set up a development environment and you have Windows 10 or 11, then using Windows Subsystem for Linux is an easy choice. Red Hat recommends pipx to install Ansible.

You can install the full or minimal Ansible package. The full version contains a community-curated selection of collections. If you aren't sure which version to install, you should go with the full Ansible package.

To install the full Ansible package, use the following command:

pipx install --include-deps ansible

For a minimal install, use this command:

pipx install --include-deps ansible-core

Check that Ansible installed properly with this command:

ansible --version

If you installed the full Ansible package, then you can see the version of the curated collections by entering:

ansible-community --version

How to set up Windows Server for Ansible

To manage a Windows Server host with Ansible, be sure to have the following prerequisites in place:

• Ansible generally supports all Windows versions with Microsoft backing. Currently, this includes Windows Server 2016, 2019 and 2022;
• Windows PowerShell 5.1 or newer;
• .NET 4.6 or newer;
• WinRM enabled; and
• The control node can connect to the host via WinRM.

Installing PowerShell 5.1 and .NET 4.6

If you are running an older version of Windows Server that doesn't already have Windows PowerShell 5.1 and .NET 4.6, such as Windows Server 2016, then you can use the following PowerShell script to automatically update those systems to the supported version.

The following example shows how to execute the script on the target host using the installed version of PowerShell running as administrator:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Upgrade-PowerShell.ps1"

$file = "$env:temp\Upgrade-PowerShell.ps1"

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

Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force

& $file -Version 5.1 -Verbose

If prompted, reboot the system.

How to enable WinRM

The Ansible control node needs WinRM enabled to talk to the Windows host and manage it. Ansible supports SSH for Windows, but it is experimental and not recommended for production use.

To configure WinRM on the host to use HTTP as the transport protocol, use the following command:

winrm quickconfig

To set up the Windows host to use HTTPS, run the following command:

winrm quickconfig -transport:https

For hosts that run in a domain environment, you should use group policy to enable WinRM by following the documentation from Microsoft. Getting WinRM to work in your environment can be difficult. Refer to the Ansible guide that explains how to set up a Windows host if you need further assistance.

How to write your first Ansible playbook

In Ansible, a playbook is the list of tasks or configuration declarations that automates the management process. The following example includes some host variables in the playbook:

- name: First Windows Playbook
  hosts: all
  gather_facts: no

  vars:
    ansible_user: user
    ansible_connection: winrm
    ansible_winrm_transport: ntlm
    ansible_port: 5985

  tasks:
     - name: Get product id and product key
       community.windows.win_product_facts:
     - name: Display Windows edition

       debug:
         var: ansible_os_license_edition

The example calls the playbook First Windows Playbook and runs it on all hosts. This article does not cover how to set up and manage inventories in Ansible. You will pass the list of hosts when you run the playbook.

Under the vars: section the example:

• sets the user account Ansible uses.
• sets the connection protocol method for Windows, using NTLM for authentication, switching to WinRM over HTTP (port 5985) rather than HTTPS (port 5986).

If WinRM over HTTPS is configured, then omit the ansible_port: setting, which defaults to 5986.

Lastly, under tasks:, the example executes a Get product id and product key task that runs the community.windows.win_product_facts module -- part of the community.windows collection -- that provides information about the system's OS version.

The Display Windows edition task outputs the information the system collected in the previous step.

Save that code to a file on your control node called first-playbook.yaml and open your favorite shell in that directory.

To run that playbook, take note of the target Windows Server IP address and then run:

ansible-playbook --ask-pass -i <ipaddress>, first-playbook.yaml

Breaking down the command's actions:

• ansible-playbook: The Ansible command that executes the playbook.
• --ask-pass: This flag tells Ansible to prompt for the password. You already specified the username in the playbook.
• -i <ipaddress>,: Specify the list of IP addresses to configure and include the comma at the end. If it is just one IP address, it would be 172.30.192.1,.
• first-playbook.yaml: The playbook YAML file name.

The screenshot shows the command run against a Windows 10 Pro host and displays the status of each task defined in the playbook with any corresponding output. For the second task, Ansible output the variable as requested.

How to install Windows Server roles with Ansible

Most of the work Ansible does relates to servers, including installing and configuring Windows Server roles. The following Ansible example installs IIS on a server:

- name: Configure Web Servers
  hosts: all
  gather_facts: no

  vars:
    ansible_user: user
    ansible_connection: winrm
    ansible_winrm_transport: ntlm
    ansible_port: 5985

  tasks:
    - name: Install IIS
      win_feature:
        name:
          - Web-Server
        state: present
        restart: yes
        include_sub_features: yes
        include_management_tools: yes

The win_feature module gives Ansible a list of features to install with the name: parameter and uses present in the state: parameter.  

When the playbook runs successfully, you get the following output:

The screenshot shows on which host Ansible executed the changes under each task.

How to benefit from using Ansible with Windows

These basic Ansible examples should give you an idea of the administrative possibilities in a mixed environment. If you take the time to build your familiarity with playbooks to manage your infrastructure, then your playbooks get more sophisticated. As you store more of your application and server configuration in Ansible, it will be easier to maintain and document your infrastructure configuration.

Anthony Howell is an IT strategist with extensive experience in infrastructure and automation technologies. His expertise includes PowerShell, DevOps, cloud computing, and working in both Windows and Linux environments.