mkletz / ansible.windows

Windows core collection for Ansible

Ansible Collection: ansible.windows

The ansible.windows collection includes the core plugins supported by Ansible to help the management of Windows hosts.

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.10.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Included content

Quote filter plugins

Name	Description
ansible.windows.quote	Quotes argument(s) for the various shells in Windows command processing.

Modules

Name	Description
ansible.windows.win_acl	Set file/directory/registry permissions for a system user or group
ansible.windows.win_acl_inheritance	Change ACL inheritance
ansible.windows.win_certificate_store	Manages the certificate store
ansible.windows.win_command	Executes a command on a remote Windows node
ansible.windows.win_copy	Copies files to remote locations on windows hosts
ansible.windows.win_dns_client	Configures DNS lookup on Windows hosts
ansible.windows.win_domain	Ensures the existence of a Windows domain
ansible.windows.win_domain_controller	Manage domain controller/member server state for a Windows host
ansible.windows.win_domain_membership	Manage domain/workgroup membership for a Windows host
ansible.windows.win_dsc	Invokes a PowerShell DSC configuration
ansible.windows.win_environment	Modify environment variables on windows hosts
ansible.windows.win_feature	Installs and uninstalls Windows Features on Windows Server
ansible.windows.win_file	Creates, touches or removes files or directories
ansible.windows.win_find	Return a list of files based on specific criteria
ansible.windows.win_get_url	Downloads file from HTTP, HTTPS, or FTP to node
ansible.windows.win_group	Add and remove local groups
ansible.windows.win_group_membership	Manage Windows local group membership
ansible.windows.win_hostname	Manages local Windows computer name
ansible.windows.win_optional_feature	Manage optional Windows features
ansible.windows.win_owner	Set owner
ansible.windows.win_package	Installs/uninstalls an installable package
ansible.windows.win_path	Manage Windows path environment variables
ansible.windows.win_ping	A windows version of the classic ping module
ansible.windows.win_powershell	Run PowerShell scripts
ansible.windows.win_reboot	Reboot a windows machine
ansible.windows.win_reg_stat	Get information about Windows registry keys
ansible.windows.win_regedit	Add, change, or remove registry keys and values
ansible.windows.win_service	Manage and query Windows services
ansible.windows.win_service_info	Gather information about Windows services
ansible.windows.win_share	Manage Windows shares
ansible.windows.win_shell	Execute shell commands on target hosts
ansible.windows.win_stat	Get information about Windows files
ansible.windows.win_tempfile	Creates temporary files and directories
ansible.windows.win_template	Template a file out to a remote server
ansible.windows.win_updates	Download and install Windows updates
ansible.windows.win_uri	Interacts with webservices
ansible.windows.win_user	Manages local Windows user accounts
ansible.windows.win_user_right	Manage Windows User Rights
ansible.windows.win_wait_for	Waits for a condition before continuing
ansible.windows.win_whoami	Get information about the current user and process

Installation and Usage

Installing the Collection from Ansible Galaxy

Before using the Windows collection, you need to install it with the ansible-galaxy CLI:

ansible-galaxy collection install ansible.windows

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
- name: ansible.windows

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Ansible Windows collection repository. See Contributing to Ansible-maintained collections for details.

See Developing modules for Windows for specifics on Windows modules.

You can also join us on the #ansible-windows libera.chat IRC channel.

See the Ansible Community Guide for details on contributing to Ansible.

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Generating plugin docs

Currently module documentation is generated manually using add_docs.py. This should be run whenever there are any major doc changes or additional plugins have been added to ensure a docpage is viewable online in this repo. The following commands will run the doc generator and create the updated doc pages under docs.

# This is the path to the ansible.windows checkout
COLLECTION_PATH=~/ansible_collections/ansible/windows

cd /tmp
git clone https://github.com/ansible-network/collection_prep.git
cd collection_prep
python add_docs.py -p "${COLLECTION_PATH}"

Testing with ansible-test

The tests directory contains configuration for running sanity and integration tests using ansible-test.

You can run the collection's test suites with the commands:

ansible-test sanity --docker
ansible-test windows-integration --docker

Publishing New Version

The current process for publishing new versions of the Windows Core Collection is manual, and requires a user who has access to the ansible namespace on Ansible Galaxy and Automation Hub to publish the build artifact.

• Update galaxy.yml with the new version for the collection.
• Rebuild the plugin docs:

  pip install git+https://github.com/ansible-network/collection_prep
  collection_prep_add_docs --path ./ --branch-name main

• Update the CHANGELOG:
  • Make sure you have antsibull-changelog installed pip install antsibull-changelog.
  • Make sure there are fragments for all known changes in changelogs/fragments.
  • Add a new fragment with the header release_summary to give a summary on the release.
  • Run antsibull-changelog release.
• Commit the changes and wait for CI to be green
• Build and publish the collection to Galaxy:

  git clone https://github.com/ansible-collections/ansible.windows.git /tmp/ansible.windows
  ansible-galaxy collection build /tmp/ansible.windows --output-path /tmp/ansible.windows
  ansible-galaxy collection publish $(find /tmp/ansible.windows -maxdepth 1 -name 'ansible-windows-*.tar.gz') --token <API_KEY> -vv

After the version is published, verify it exists on the Windows Core Collection Galaxy page.

More Information

For more information about Ansible's Windows integration, join the #ansible-windows channel on libera.chat IRC, and browse the resources in the Windows Working Group Community wiki page.

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

License

GNU General Public License v3.0 or later

See COPYING to see the full text.