Managing Windows Hosts

1. Configuring WinRM

Configuration	Description	Notes
ansible_connection	`winrm`	Must be set to use WinRM connection
ansible_winrm_transport	`ssl` or `plaintext`	Transport method for WinRM communication
ansible_winrm_server_cert_validation	`ignore` or `validate`	Controls SSL certificate validation
ansible_winrm_port	`5986` (SSL) or `5985` (plaintext)	Port to connect to WinRM service

Example: Basic WinRM Configuration

---
- name: Configure WinRM on Windows host
  hosts: windows_hosts
  vars:
    ansible_connection: winrm
    ansible_winrm_transport: ssl
    ansible_winrm_server_cert_validation: ignore
    ansible_winrm_port: 5986
  tasks:
    - name: Ensure WinRM is running
      win_service:
        name: WinRM
        state: started

Note: Ensure the target Windows host has WinRM enabled and configured to accept remote connections.

2. Setting Windows Connection

Parameter	Description	Values
ansible_connection	Connection type to use	`winrm` or `psrp`
ansible_host	Windows host IP or hostname	`192.168.1.100`
ansible_user	Username for authentication	`administrator`
ansible_password	Password for authentication	`password123`
ansible_port	Port to connect to (default 5985 for winrm, 5986 for psrp)	`5985` or `5986`
ansible_winrm_transport	Transport method for winrm (basic, certificate, kerberos)	`basic`, `certificate`, `kerberos`
ansible_winrm_server_cert_validation	Validate server certificate (ignore for testing)	`validate`, `ignore`

Example: Playbook using Windows connection

---
- name: Manage Windows Hosts
  hosts: windows_servers
  gather_facts: no
  vars:
    ansible_connection: winrm
    ansible_host: 192.168.1.100
    ansible_user: administrator
    ansible_password: password123
    ansible_port: 5985
    ansible_winrm_transport: basic
    ansible_winrm_server_cert_validation: ignore

  tasks:
    - name: Get Windows version
      win_shell: |
        $PSVersionTable.PSVersion

3. Using Windows Modules

Module	Description	Notes
win_shell	Executes a PowerShell or batch script on the Windows host.	Supports both PowerShell and cmd scripts. Requires a script file or inline script content.
win_command	Runs a command on the Windows host.	Similar to `command` module but for Windows. Does not support shell features like pipes or redirections.
win_copy	Copies files from the control node to the Windows host.	Supports recursive copying and file permissions. Can copy from local or remote sources.
win_template	Uses Jinja2 templates to generate configuration files on the Windows host.	Templates must be written in Jinja2 syntax. Supports variables and conditionals.
win_service	Manages Windows services on the target host.	Can start, stop, restart, or check status of services. Requires service name and desired state.
win_user	Manages local Windows users on the target host.	Supports creating, modifying, and deleting users. Can set password policies and group membership.

Example: Running a PowerShell Script

- name: Run PowerShell script on Windows
  win_shell:
    script: |
      Write-Host "Hello from Ansible"
      Get-Date

Example: Managing a Windows Service

- name: Ensure IIS service is running
  win_service:
    name: W3SVC
    state: started

Note: Ensure the Windows host has PowerShell 3.0 or higher installed for full module support.

4. Managing Windows Services

Property	Description	Values	Notes
name	Service name	`string`	Required. The name of the Windows service to manage.
state	Service state	`running`, `stopped`, `restarted`, `absent`	Defaults to `running`. Controls the desired state of the service.
delayed_start	Delayed start	`true`, `false`	Whether to delay the start of the service. Default is `false`.
start_mode	Service start mode	`manual`, `automatic`, `disabled`	Determines how the service is started. Default is `automatic`.

Example: Start a Windows Service

- name: Start the IIS service
  ansible.windows.win_service:
    name: w3svc
    state: running

Example: Stop and Disable a Windows Service

- name: Stop and disable the Windows Update service
  ansible.windows.win_service:
    name: wuauserv
    state: stopped
    start_mode: disabled

Note: The ansible.windows.win_service module requires the Windows host to be configured with WinRM and have PowerShell 3.0 or higher installed.

5. Managing Windows Packages

Property	Description	Values
name	Name of the package to install or remove	`7-Zip 21.07`
state	State of the package	`present`, `absent`
version	Version of the package to install	`21.07`
source	Source location for the package (e.g., local file or repository)	`http://example.com/package.msi`

Example: Install a Windows Package

- name: Install 7-Zip
  ansible.builtin.win_package:
    name: 7-Zip 21.07
    source: http://example.com/7z21.07.msi
    state: present

Example: Remove a Windows Package

- name: Remove 7-Zip
  ansible.builtin.win_package:
    name: 7-Zip 21.07
    state: absent

Note: The win_package module requires the Windows host to have PowerShell installed and configured.

Warning: Ensure that the package source is trusted to avoid security risks.

6. Managing Windows Files

Property	Description	Values	Notes
src	Source file path on the Windows host	`C:\temp\file.txt`	Required for copy and fetch operations
dest	Destination file path on the Windows host	`C:\backup\file.txt`	Required for copy and fetch operations
state	Desired state of the file	`present`, `absent`	Default is `present`
mode	File permissions (Windows)	`0644`, `0755`	Uses octal notation; affects file access rights
owner	File owner (Windows)	`Administrator`	Applies to file ownership on Windows systems
group	File group (Windows)	`Administrators`	Applies to file group on Windows systems

Example: Copying a file to Windows host

- name: Copy file to Windows host
  ansible.windows.win_copy:
    src: files\config.xml
    dest: C:\temp\config.xml
    mode: 0644

Example: Creating a directory on Windows host

- name: Create directory on Windows
  ansible.windows.win_file:
    path: C:\temp\newdir
    state: directory

Example: Removing a file from Windows host

- name: Delete file from Windows host
  ansible.windows.win_file:
    path: C:\temp\oldfile.txt
    state: absent

Note: When using win_copy, ensure the source path is accessible from the Ansible control node and that the destination path exists or can be created.

7. Executing PowerShell

Parameter	Description	Values
script	PowerShell script content to execute	`string`
path	Path to a PowerShell script file on the target host	`string`
args	Arguments to pass to the script	`dict`

Example: Executing a PowerShell script

- name: Run PowerShell script
  ansible.windows.win_shell:
    script: |
      Write-Host "Hello from PowerShell"
      Get-Date

Example: Executing a PowerShell script with arguments

- name: Run PowerShell script with args
  ansible.windows.win_shell:
    path: C:\scripts\test.ps1
    args:
      param1: value1
      param2: value2

Note: The win_shell module executes PowerShell scripts on Windows hosts. Ensure the script path is accessible and the host has appropriate permissions.

8. Managing Windows Users

Property	Description	Values	Notes
name	User account name	`string`	Required field
password	Password for the user account	`string`	Must be encrypted or set via vault
state	Desired state of the user	`present`, `absent`	Default is `present`
groups	Groups to add the user to	`list`	Can be a list of group names
update_password	When to update password	`always`, `on_create`	Default is `always`

Example: Create a Windows User

- name: Create a Windows user
  ansible.windows.win_user:
    name: testuser
    password: "{{ vault_password }}"
    state: present
    groups:
      - Users
      - Administrators

Example: Delete a Windows User

- name: Delete a Windows user
  ansible.windows.win_user:
    name: testuser
    state: absent

9. Managing Windows Features

Feature	Description	Module	Example
win_feature	Manage Windows features (like .NET Framework, IIS)	`win_feature`	Example: Install IIS `- name: Install IIS win_feature: name: Web-Server state: present`
win_optional_feature	Manage optional Windows features (like Hyper-V)	`win_optional_feature`	Example: Enable Hyper-V `- name: Enable Hyper-V win_optional_feature: name: Microsoft-Hyper-V-Server-Core state: present`

10. Managing Windows Registry

Property	Description	Values	Notes
key	Registry key path to manage	`HKLM\SOFTWARE\MyApp`	Must be a valid Windows registry path
value_name	Name of the registry value to manage	`InstallPath`	Optional, defaults to `(Default)`
value_type	Type of registry value	`REG_SZ`, `REG_DWORD`, `REG_BINARY`	Must match the registry value type
value_data	Data to set for the registry value	`C:\Program Files\MyApp`	Must be valid for the specified `value_type`
state	Desired state of the registry key/value	`present`, `absent`	Defaults to `present`

Example: Setting a Windows Registry Value

- name: Set registry value for MyApp
  ansible.windows.win_registry:
    key: HKLM\SOFTWARE\MyApp
    value_name: InstallPath
    value_type: REG_SZ
    value_data: C:\Program Files\MyApp
    state: present

Example: Removing a Windows Registry Key

- name: Remove registry key
  ansible.windows.win_registry:
    key: HKLM\SOFTWARE\MyApp
    state: absent

Note: Registry operations require elevated privileges on the target Windows host.

Warning: Incorrect registry modifications can cause system instability or prevent Windows from booting properly.

11. Managing Windows Updates

Property	Description	Values	Notes
win_updates	Module to manage Windows updates	`ansible.windows.win_updates`	Available in Ansible 2.10+

Example: Install Windows Updates

- name: Install Windows Updates
  ansible.windows.win_updates:
    category:
      - "SecurityUpdates"
      - "CriticalUpdates"
    state: installed

Example: Check for Available Updates

- name: Check for available updates
  ansible.windows.win_updates:
    state: list
  register: update_results

- name: Display available updates
  debug:
    var: update_results.updates

Note: Ensure the target Windows hosts have the Windows Update service running and are configured to allow update installations.

Warning: Installing updates can cause system reboots. Ensure systems are prepared for potential downtime.

Parameter	Description	Default	Notes
category	List of update categories to include	None	Valid options: SecurityUpdates, CriticalUpdates, DefinitionUpdates, DriverUpdates, FeaturePacks, ServicePacks, Tools, UpdateRollups, Upgrades
state	State of updates	`list`	Valid options: list, installed, downloaded
reboot	Reboot after updates	`false`	Set to `true` to reboot after update installation
reboot_timeout	Timeout in seconds for reboot wait	`600`	Time to wait for system to come back online after reboot