Ansible to Manage Windows Servers – Step by Step

Introduction

Ansible is quickly becoming the dominant DevOps platform for automating software provisioning, configuration management, and application deployment in a heterogeneous datacenter and hybrid cloud environment. Ansible has facilities to integrate and manage various technologies including Microsoft Windows, systems with REST API support and of course Linux.

This article will go through the steps of deploying the Ansible controlling node on CentOS 7, the configuration of Windows Server 2016 for management and create Ansible playbook examples with custom Powershell Ansible modules.

Windows and Ansible integration is documented in the official Ansible documentation.

By following the instructions in this article, you will be able to manage Windows systems using Ansible as easily as any other environment, including Linux.

Example Lab

The examples in this article will reference this minimal configuration:

• One Ansible Controlling Node running Linux CentOS 7
• One Windows Server 2016 server to be managed
• One Windows Server 2016 Active Directory server providing DNS services

This lab is built on three VMs running on Hyper-V on a Windows 10 desktop. Here is an article describing a similar scenario, How to Build Windows Storage Spaces Direct on a Virtual Lab.

Below is a diagram of the example lab environment.

All communications between systems runs on a private network segment for simplicity.

Install Lab Servers

Build the following servers in your environment.

Configure Lab Network

Configure AD1 DNS services

Configure DNS Forward and Reverse Lookups, Kerberos requires both forward and reverse DNS lookup to resolve correctly.

Configure the DNS Reverse Lookup Zone. This will look like the screenshot below.

The DNS Forward Lookup Zone will be like the screenshot below

Add Ansible1 and WinServer1 A records:

• Ansible1: 172.20.20.100 – Select to create the PTR record automatically
• WinServer1: 172.20.20.101 – Select to create the PTR record automatically

Review the Reverse Look Zone 20.20.172.in-addr.arpa. You may need to select Right-Click and REFRESH to see the new records.

Configure Ansible1 CentOS System Network

Update the following files. Be sure to modify as appropriate for your own environment.

The eth0 interface in this example uses DHCP addresses to access the Internet and provide SSH access for administration.

1. Edit: /etc/sysconfig/network-scripts/ifcfg-eth0

TYPE="Ethernet"
PROXY_METHOD="none"
BROWSER_ONLY="no"
BOOTPROTO="dhcp"
DEFROUTE="yes"
PEERDNS="no"
IPV4_FAILURE_FATAL="no"
NAME="eth0"
DEVICE="eth0"
ONBOOT="yes"

The eth1 interface is a private network and is shared only with the other servers in this lab.

2. Edit /etc/sysconfig/network-scripts/ifcfg-eth1

TYPE=Ethernet
PROXY_METHOD=none
BROWSER_ONLY=no
BOOTPROTO=static
DEFROUTE=yes
IPADDR=172.20.20.100
NETMAST=255.255.0.0
DNS1=172.20.20.1
IPV4_FAILURE_FATAL=no
NAME=eth1
DEVICE=eth1
ONBOOT=yes

The resolv.conf configures the Linux DNS client.

3. Edit /etc/resolv/conf

search Lab1AD1.local
nameserver 172.20.20.1

Set the hostname

4. Edit: /etc/hostname

Ansible1

5. Reboot the server

Type: reboot

6. Test your network. Make sure you can resolve DNS correctly.

Type: nslookup WinServer1

This command will query the AD1 DNS server for WinServer1 without a fully qualified name.

Type: nslookup 172.20.20.101

This command will do a reverse lookup on the IP address. This should return WinServer1 as the name.

Configure Ansible Environment

Install Prerequisite Packages

Use Yum to install the following packages.

1. Install GCC required for Kerberos

yum -y group install “Development Tools”

2. Install EPEL

yum -y install epel-release

3. Install Ansible

yum -y install ansible

4. Install Kerberos

yum -y install python-devel krb5-devel krb5-libs krb5-workstation

5. Install Python PIP

yum -y install python-pip

6. Install BIND utilities for nslookup

yum -y install bind-utils

7. Bring all packages up to the latest version

yum -y update

Check Ansible and Python is Installed

1. Run the commands:

ansible - - version | head -l 1
python - - version

Configure Kerberos

There are other options than Kerberos, but Kerberos is generally the best option, though not the simplest.

1. Install the Kerberos wrapper:

pip install pywinrm[Kerberos]

Kerberos packages were installed previously which will have created /etc/krb5.conf

2. Edit /etc/krb5.conf

Add:

[realms]
LAB1AD1.LOCAL = {
  kdc = AD1.LAB1AD1.LOCAL
}

Add:

[domain_realm]
.lab1ad1.local = LAB1AD1.LOCAL
lab1ad1.local = LAB1AD1.LOCAL

The /etc/krb5.conf file when complete will be similar to:

Test Kerberos

1. Run the following commands to test Kerberos:

kinit administrator@LAB1AD1.LOCAL

You will be prompted for the administrator password klist
You should see a Kerberos KEYRING record.

Configure Ansible

Ansible is complex and is sensitive to the environment. Troubleshooting an environment that has never initially worked is complex and confusing. We are going to configure Ansible with the least complex possible configuration. Once you have a working environment, you can make extensions and enhancements in small steps.

The core configuration of Ansible resides at /etc/ansible

We are only going to update two files for this exercise.

Update the Ansible Inventory file

1. Edit /etc/ansible/hosts and add:

[windows]
WinServer1.lab1ad1.local

[windows] is a created group of servers called “windows”. In reality, this should be named something more appropriate for a group that would have similar configurations, such as “Active Directory Servers”, or “Production Floor Windows 10 PCs”, etc.

Update the Ansible Group Variables for Windows

Ansible Group Variables are variable settings for a specific inventory group. In this case, we will create the group variables for the “windows” servers created in the /etc/ansible/hosts file.

1. Create /etc/ansible/group_vars/windows and add:

---
ansible_user: Administrator
ansible_password: Abcd1234
ansible_port: 5986
ansible_connection: winrm
ansible_winrm_server_cert_validation: ignore

Naturally, change the Administrator password to the password for WinServer1.

Configure Windows Servers to Manage

Configuring the Windows Server for remote management by Ansible requires a bit of work. Luckily the Ansible team has created a PowerShell script for this. Download this script from [here] to each Windows Server to manage and run this script as an Administrator.

Log in to WinServer1 as an Administrator, download ConfigureRemotingForAnsible.ps1 and run this PowerShell script without any parameters.

Once this command has been run on the WinServer1, return to the Ansible1 Controller host.

Test Connectivity to the Windows Server

If all has gone well, we should be able to perform an Ansible PING test command. This command will connect to the remote WinServer1 server and report success or failure.

1. Type: ansible windows -m win_ping

This command runs the Ansible module win_ping on every server in the windows inventory group.

2. Type: ansible windows -m setup to retrieve a complete configuration of Ansible environmental settings.
3. Type: ansible windows -c ipconfig

If this command is successful, the next steps will be to build Ansible playbooks to manage Windows Servers.

Managing Windows Servers with Playbooks

Let’s create some playbooks and test Ansible for real on Windows systems.

1. Create a folder on Ansible1 for the playbooks, YAML files, modules, scripts, etc. For these exercises, we created a folder under /root called win_playbooks.

Ansible has some expectations on the directory structure where playbooks reside. Create the library and scripts folders for use later in this exercise.

Commands:

cd /root
mkdir win_playbooks
mkdir win_playbooks/library
mkdir win_playbooks/scripts

2. Create the first playbook example “netstate.yml”

The contents are:

- name: test cmd from win_command module
  hosts: windows
  tasks:
    - name: run netstat and return Ethernet stats
      win_command: netstat -e
      register: netstat
    - debug: var=netstat

This playbook does only one task, to connect to the servers in the Ansible inventory group windows and run the command netstat.exe -a and return the results.

To run this playbook, run this command on Ansible1: ansible-playbook netstat_e.yml

OK, not exciting, but it did run, just not very friendly.

Also, notice that the changed flag is set. As of the time this article was created, all of the Windows commands return the changed flag as true. This is the same with running PowerShell scripts remotely. This makes much of the value of Ansible difficult as a configuration and deployment tool.

Interestingly enough, Ansible modules created with PowerShell do work correctly and return the changed flag correctly. PowerShell scripts and direct commands always return the changed flag as true. This is problematic for managing systems with Ansible. The rest of this article will focus on PowerShell modules that can perform complex management functions as well as integrate with other non-Windows systems.

Creating Ansible Modules with PowerShell

Ansible modules are plugin programs which are:

1. Loaded by Ansible when running a playbook test
2. Ansible generates module input parameters in the JSON format
3. Modifies the module into a generalized script and command
4. Copies the modified script to the remote system(s)
5. Executes the modified module on the remote system
6. The module generates a response in JSON and this response is returned
7. The returned JSON is parsed and values are saved or used by other tests
8. The module returns a flag called changed which is essential to maintain “Desired State Configurations”. A return of changed = True will signal other tests to run to achieve the “Desired State”

Modules are stored in several locations where Ansible will find them. One location is a folder named library located in the folder where the playbook is run. Modules stored in our library are first in the module search path and will override modules of the same name.

This example lab has a folder win_playbooks/library/

PowerShell modules consist of two programs, a Python program, and a PowerShell program. The Python program configures the local Ansible environment and the PowerShell program does the actual processing on the remote systems.

Create a file called win_playbooks/library/get_version.py and add the following contents:

#!/usr/bin/python
# -*- coding: utf-8 -*-
#License: Public Domain
ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['stableinterface'],
                    'supported_by': 'core'}
DOCUMENTATION = r'''
---
module: get_version
short_description: Windows get OS verison and return changed flag if below min
description:
  - Checks Windows OS version and returns the version data in JSON
  - Checks that the min version against the passed "major,minor,build" parameters
  - Returns "changed" if the remote system OS version is below a minimum
  - The "changed" flag is to notify operations or to trigger another task
options:
  major:
    description:
      - Windows major version [MAJOR.minor.build]
    default: 5
  minor:
    description:
      - Windows minor version [major.MINOR.build]
    default: 1
  build:
    description:
      - Windows build version [major.minor.BUILD]
    default: None
author:
- Robert Keith (Argon Systems)
'''

EXAMPLES = r'''
# Example Ansible Playbook
- name: test remote Windows OS version
  hosts: windows
  tasks:
    - name: PowerShell module example to get Windows OS version
      get_version:
        major: "5"
        minor: "1"
        build: "13493"

'''

RETURN = '''
    description: Output of (Get-Host).Version powershell in JSON format
    returned: success
    type: string
'''

Next create a file win_playbooks/library/get_version.ps1 and add the following contents:

#!powershell
# WANT_JSON
# POWERSHELL_COMMON
$ErrorActionPreference = "Stop"
$params = Parse-Args $args -supports_check_mode $true
$MajorVer = Get-AnsibleParam -obj $params -name "major" -type "str"
$MinorVer = Get-AnsibleParam -obj $params -name "minor" -type "str"
$BuildVer = Get-AnsibleParam -obj $params -name "build" -type "str"
#Should validate input parameters here naturally
$Vers = (Get-Host).Version
$Message = $Message = "Windows OS is at desired version"
$BelowMin = $false
if ($Vers.Major -lt $MajorVer) { $BelowMin = $true }
if ($Vers.Minor -lt $MinorVer) { $BelowMin = $true }
if ($Vers.Build -lt $BuildVer) { $BelowMin = $true }
if ($BelowMin) { $Message = "Windows OS below desired version" }
$result = @{
  changed = $BelowMin
  version = $Vers
  message = $Message
  desired_major_ver = $MajorVer
  desired_minor_ver = $MinorVer
  desired_build_ver = $BuildVer
}
Exit-Json $result

Next, create the playbook YAML file to set up and run the new module.

From the win_playbooks folder, create a file with the following contents:

- name: test simple powershell module - get OS version and test for minimum desired version
  hosts: windows
  tasks:
    - name: simple powershell module example to get Windows OS version
      get_version:
        major: "5"
        minor: "1"
        build: "14393"

Execute this playbook with the command:

ansible-playbook get_version.yml

Notice the changed flag is set to False. In this case, this means the remote operating system matched the values in the get_version.yml playbook.

If we set the Verbose flag, we see the data returned from the PowerShell module in the JSON format.

ansible-playbook get_version.yml -v

Setting the Very Very Verbose flag gives more information, and oddly enough formats the JSON into a more readable format.

ansible-playbook get_version.yml -vvv

Now if we modify the playbook expecting a different version. We set the major version from 5 to 9 (which does not exist).

- name: test simple powershell module - get OS version and test for minimum desired version
  hosts: windows
  tasks:
    - name: simple powershell module example to get Windows OS version
      get_version:
        major: "9"
        minor: "1"
        build: "14393"

And run the playbook again

ansible-playbook get_version.yml

The “changed” flag is set.

We could extend this playbook with other PowerShell modules, for example:

- name: test simple powershell module - get OS version and test for minimum desired version
  hosts: windows
  tasks:
    - name: simple powershell module example to get Windows OS version
      get_version:
        major: "9"
        minor: "1"
        build: "14393"
      register: get_version_output
    - debug:
        var: get_version_output.message
    - enable_win_updates: Enable unattended Windows Updates
      when get_version_output.changed

This playbook could check the Windows version, and if it is below a version threshold, the next task could then enable updates, manually install updates, or practically any possible action imaginable to maintain the Windows servers to a “Desired State”.

Summary

Ansible is a powerful management and DevOps framework. It is complex to set up initially, but relatively simple to operate. Playbooks can be created that manage large and complex environments consisting of cloud systems, servers, storage systems, network systems, security systems, hardware and facilities management devices, and any of a large set of disparate systems.

Configured correctly, managing and monitoring complex can be consolidated into a single framework, and with the Ansible Windows support and some initial instructions detailed in this article, can include Windows Servers, Windows desktops and other Windows-based systems.