New Collection microsoft.ad

[jborean93]

There is a new collection microsoft.ad that has just gone live to Galaxy and Automation Hub. It is a supported collection for managing Active Directory in Ansible. While some of the modules are similar to what's in ansible.windows and community.windows there will end up being a redirect in place for the ansible.windows equivalents but community.windows will most likely deprecate their existing ones due to too many differences between what is there and what is in microsoft.ad.

Ansible Galaxy: https://galaxy.ansible.com/microsoft/ad
GitHub: https://github.com/ansible-collections/microsoft.ad
Issues Tracker: https://github.com/ansible-collections/microsoft.ad/issues
GitHub Handles: @jborean93
Is the collection part of Automation Hub: Yes
We meet Collection Requirements: Yes

[Andersson007]

@jborean93 hi, thanks for the new collection! I'll post this request in Bullhorn today

[Andersson007]

@briantist @lowlydba as you folks are familiar with powershell, could you please take a look? Here's the checklist.

[lowlydba]

Review: Passed ✅

Ansible Collections Checklist (short version)

For details about the following points, refer to the Collection Requirements.

Every comment should say whether the reviewer expects it to be addressed, or whether it's optional.

Public availability and communication:

• published on Ansible Galaxy with version 1.0.0 or later
• has a policy of releasing, versioning and deprecation announced to contributors and users in some way
  • OPTIONAL: Should explicitly mention semantic versioning & any deprecation policies
• have a Code of Conduct (CoC) compatible with the Ansible Code of Conduct (CoC)
• have a publicly available issue tracker that does not require a paid level of service to create an account or view issues
• have a public git repository, releases of the collection are tagged in this repository

Standards and documentation:

• adheres to semantic versioning
• follows licensing rules
• follows the Ansible documentation standards and the style guide
  • FIX: "distibution" typo in group module docs
  • FIX: "traditiional" typo in object_info module docs
  • FIX: C() formatting for command reference in object_info module docs
  • FIX: "pricipals" typo in user module docs
  • FIX: "memberhips" typo in user module docs
  • FIX: "recommened" typo in ad_object docs
• follows development conventions; as well as these other requirements:
  • modules satisfy the concept of idempotency
  • modules that only gather information are named <something>_info
  • modules that return ansible_facts are named <something>_facts and do not return non-facts
  • other modules must not allow querying information using specific state option values, or similar mechanisms (like state=get or state=query). These features should be moved to <something>_info or <something>_fact modules.
  • check_mode is supported in all _info and _facts modules
• supports Python 2.6 or greater and Python 3.5 or greater. If it does not, read the full guidelines to see if you qualify for an exception and document the unsupported Python versions in the collection README.md and in every module and plugin (or in doc fragments)
  • OPTIONAL: It looks like only Python 3.10 is tested against in the pipelines - not sure if testing for 2.6+ is required?
• only uses the allowed plugin types in the plugins/ directory
• has README.md
• documentation, examples, and return sections use FQCNs for the M(..) format macros when referring to modules
• modules (or plugins) from ansible-core use ansible.builtin. as a FQCN prefix
• documentation and return sections use version_added: containing the collection version for which an option, module or plugin was added
• FQCNs are used for extends_documentation_fragment:, unless you are referring to doc_fragments from ansible-core
• public plugins, roles and playbooks do not use files outside of meta/, plugins/, roles/, and playbooks/

Collection management:

• galaxy.yml having tags field set
• collection dependencies must have a lower bound on the version which is at least 1.0.0, and are all part of the ansible package
• meta/runtime.yml defines the minimal version of Ansible which the collection works with
• has changelog, preferably with changelogs/changelog.yaml
• collection repository should not contain any large objects (binaries) comparatively to the current Galaxy tarball size limit of 20 MB. For example, package installers for testing purposes shouldn't be added.
• collection repository should not contain any unnecessary files like, for example, temporary files. Temporary files should be added to .gitignore.

Tests:

• passed ansible-test sanity
  • OPTIONAL: dlevel sanity is failing currently, but all major versions are ✅
• if test/sanity/ignore*.txt exists, it MUST not contain error codes listed here
• has CI tests up and running against each of the "major versions" of ansible-base/ansible-core that the collection supports
• all CI tests MUST run against every pull request
• all CI tests MUST run regularly (nightly, or at least once per week)
• sanity tests MUST run against a commit that releases the collection; if they don't pass, the collection won't be released

[jborean93]

Thanks for the thorough review, I believe I've addressed the documentation problems in ansible-collections/microsoft.ad#20.

For the Python support the majority of the code is run on the remote side with PowerShell. We have tests covering Server 2012, 2012 R2, 2016, 2019, and 2019 which covers PowerShell 3, 4, and 5.1. There are no remote Python modules and the only Python code is in the action plugins. This has a limited range of supported versions (2.14 uses Python 3.9 - 3.11) and the effort to test this alongside the various PowerShell versions is too much for what we need.

[Andersson007]

@lowlydba thanks much for the contribution! Much appreciated!
When you're satisfied, please put something if the collection is OK or not for inclusion. Then we can mark it ready for the second review

[lowlydba]

All looks good to me now, thanks! OK for inclusion 👍🏻

[Andersson007]

Ansible Collections Checklist (short version)

For details about the following points, refer to the Collection Requirements.

Every comment should say whether the reviewer expects it to be addressed, or whether it's optional.

Note for reviewers: If you don't know how to check any of the points below, please ask maintainers of the collection you're reviewing or a Steering Committee member for clarifications in comments of corresponding inclusion discussion.

Public availability and communication:

• published on Ansible Galaxy with version 1.0.0 or later
• has a policy of releasing, versioning and deprecation announced to contributors and users in some way
  MUST FIX I see the process but don't see the policy. It can be in README or in an issue. See community.general as an example.
• have a Code of Conduct (CoC) compatible with the Ansible Code of Conduct (CoC)
• have a publicly available issue tracker that does not require a paid level of service to create an account or view issues
• have a public git repository, releases of the collection are tagged in this repository

Standards and documentation:

• adheres to semantic versioning
  MUST FIX Looks like it follows but there's no info about it in README
• follows licensing rules
• follows the Ansible documentation standards and the style guide
  MUST FIX please reflect in the DOCUMENTATION that the check mode is supported by modules (where supported)
• follows development conventions; as well as these other requirements:
  • modules satisfy the concept of idempotency
  • modules that only gather information are named <something>_info
  • modules that return ansible_facts are named <something>_facts and do not return non-facts
  • other modules must not allow querying information using specific state option values, or similar mechanisms (like state=get or state=query). These features should be moved to <something>_info or <something>_fact modules.
  • check_mode is supported in all _info and _facts modules
• supports Python 2.6 or greater and Python 3.5 or greater. If it does not, read the full guidelines to see if you qualify for an exception and document the unsupported Python versions in the collection README.md and in every module and plugin (or in doc fragments)
• only uses the allowed plugin types in the plugins/ directory
• has README.md
  COMMENT you could also put a link to a corresponding Matrix channel if exists and the badge like in c.mysql. Just a fyi
• documentation, examples, and return sections use FQCNs for the M(..) format macros when referring to modules
• modules (or plugins) from ansible-core use ansible.builtin. as a FQCN prefix
• documentation and return sections use version_added: containing the collection version for which an option, module or plugin was added
• FQCNs are used for extends_documentation_fragment:, unless you are referring to doc_fragments from ansible-core
• public plugins, roles and playbooks do not use files outside of meta/, plugins/, roles/, and playbooks/

Collection management:

• galaxy.yml having tags field set
• collection dependencies must have a lower bound on the version which is at least 1.0.0, and are all part of the ansible package
• meta/runtime.yml defines the minimal version of Ansible which the collection works with
• has changelog, preferably with changelogs/changelog.yaml
• collection repository should not contain any large objects (binaries) comparatively to the current Galaxy tarball size limit of 20 MB. For example, package installers for testing purposes shouldn't be added.
• collection repository should not contain any unnecessary files like, for example, temporary files. Temporary files should be added to .gitignore.
  SHOULD FIX: there are tests/sanity/ignore*.txt files that are empty, should be deleted i think. Also maybe .vscode? Anyway, this is should fix stuff, not must

Tests:

Note for reviewers: If you don't know how to check the points below, please ask maintainers of the collection you're reviewing how you can do it.

• In most cases, CI is set up via GitHub Actions.
• Check .yml files in the .github/workflows directory. There must be at least the sanity section under jobs containing the ansible-test sanity command running against all supported ansible-core versions that must be also listed there, for example, - stable-2.11, - stable-2.12, - stable-2.13.
• Check workflow runs by clicking the Actions tab in the repository's page - you're interested in Scheduled runs, runs against release commits and runs against pull requests.
• If there are no workflows in the Actions tab, ask the collection maintainers how CI is implemented.

• passed ansible-test sanity
• if test/sanity/ignore*.txt exists, it MUST not contain error codes listed here
• has CI tests up and running against each of the "major versions" of ansible-base/ansible-core that the collection supports
• all CI tests MUST run against every pull request
• all CI tests MUST run regularly (nightly, or at least once per week)
• sanity tests MUST run against a commit that releases the collection; if they don't pass, the collection won't be released

[Andersson007]

@jborean93 thanks for the response

1. Releasing info. Sorry, c.general has it in the pinned issue. But what you added to readme, i think, is adequate. (though I like c.g's approach personally, so can be taken into consideration).

2. Check mode. TIL about attributes, thanks. Do you know any other included modules that use this? I'd like to see how it looks on docs.ansible.com and if it looks good I'll introduce it to the collections i maintain

3. ignore and vscode files. OK

[jborean93]

Check mode. TIL about attributes, thanks. Do you know any other included modules that use this? I'd like to see how it looks on docs.ansible.com and if it looks good I'll introduce it to the collections i maintain

It's a relatively new thing and not very well documented. Here is an example of how it is rendered through the Ansible docs https://ansible-collections.github.io/microsoft.ad/branch/main/collections/microsoft/ad/computer_module.html#attributes

[Andersson007]

looks great, thank you for the example!

[briantist]

@Andersson007 I added attributes to the community.hashi_vault docs: https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/vault_kv2_delete_module.html#attributes

I think most if not all of the collections @felixfontein maintains have them too :)

[Andersson007]

@briantist cool, thanks for the links! I filed add-attributes issues in the collections I maintain.

@thanks for taking a look at and approving the collection for inclusion!

[Andersson007]

+1 from me for inclusion

Could anyone from @ansible-collections/steering-committee approve the collection too?

[jborean93]

Thanks for the review, greatly appreciate it.

[briantist]

+1 for inclusion!

[mariolenz]

I've created ansible-community/community-topics#217.

If no one objects, we'll add the collection in a week: ansible-community/ansible-build-data#204

[russoz]

+1

[mariolenz]

If no one objects, we'll add the collection in a week: ansible-community/ansible-build-data#204

Too late for ansible 7.4.0, but the collection has been added and should be part of 7.5.0.