Ansible Collection: microsoft.ad
The microsoft.ad collection includes the plugins supported by Ansible to help the management of Microsoft Active Directory.
Communication
For more information about communication, see the Ansible communication guide.
Ansible version compatibility
This collection has been tested against following Ansible versions: >=2.16.
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.
Changelog
See CHANGELOG.rst for the release history and changes made to this collection.
Collection Documentation
Browsing the latest collection documentation will show docs for the latest version released in the Ansible package not the latest version of the collection released on Galaxy.
Browsing the devel collection documentation shows docs for the latest version released on Galaxy.
We also separately publish latest commit collection documentation which shows docs for the latest commit in the main branch.
If you use the Ansible package and don't update collections independently, use latest, if you install or update this collection directly from Galaxy, use devel. If you are looking to contribute, use latest commit.
Release Policy
This collection follows semantic versioning (major.minor.patch) which in short means:
- A
patch release can only contain bug fixes
- A
minor release can contain bug fixes, features, and new deprecations
- A
major release can contain bug fixes, features, new deprecations, removal of features, and other breaking changes
Deprecated features can be removed only 2 years after the deprecation warning was added.
Once a deprecation warning has lasted for 2 years, they will be removed in the next major release.
Installation and Usage
Installing the Collection from Ansible Galaxy
Before using the Active Directory collection, you need to install it with the ansible-galaxy CLI:
ansible-galaxy collection install microsoft.ad
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: microsoft.ad
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 Active Directory collection repository. See Contributing to Ansible-maintained collections for details.
See Developing modules for Windows for specifics on Windows modules.
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.
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 Microsoft AD Collection is done through a tagged release which triggers a Zuul run. Before the tag is set, the following steps must be done.
- Update
galaxy.yml with the new version for the collection.
- 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
release_summary fragment: echo "release_summary: Release summary for v..." > changelogs/fragments/release-summary.yml
- Run
antsibull-changelog release.
- Commit the changes and wait for CI to be green
- Create a release with the tag that matches the version number
- The tag is the version number itself, and should not start with anything
- This will trigger a build and publish the collection to AH and Galaxy
- The Zuul job progress will be listed here
After the version is published, verify it exists on the Active Directory Galaxy page.
Support
As a Red Hat Ansible Certified Content, this collection is entitled to support through Ansible Automation Platform (AAP) through the Red Hat Ansible team.
If a support case cannot be opened with Red Hat or the collection has been obtained either from Galaxy or GitHub, you can open a GitHub issue on this repo but this has no guarantee of support or timeframes for a response.
License
GNU General Public License v3.0 or later
See COPYING to see the full text.
