htaudah / ansible.windows

Windows core collection for Ansible

Ansible Collection: ansible.windows

This repo hosts the ansible.windows Ansible Collection.

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

Included content

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_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

Testing and Development

If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is ot clone it into one of the configured COLLECTIONS_PATHS, and work on it there.

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.

1. Ensure CHANGELOG.md contains all the latest changes.

2. Update galaxy.yml with the new version for the collection.

3. Create a release in GitHub to tag the commit at the version to build.

4. Run the following commands to build and release the new version on Galaxy:

   ansible-galaxy collection build
   ansible-galaxy collection publish ./ansible-windows-$VERSION_HERE.tar.gz
   

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 Freenode IRC, and browse the resources in the Windows Working Group Community wiki page.

License

GNU General Public License v3.0 or later

See COPYING to see the full text.