Skip to content

Latest commit

 

History

History
174 lines (127 loc) · 12.9 KB

README.md

File metadata and controls

174 lines (127 loc) · 12.9 KB
Raw

Ansible Collection: ansible.windows

Build Status codecov

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.

License

GNU General Public License v3.0 or later

See COPYING to see the full text.