Documentation on requirements.yml is confusing or misleading

[ssbarnea]

SUMMARY

• Galaxy docs from https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file mention the newer dictionary format with roles and collections but does not mention if the same format can be used for inside-role meta/requirements.yml. We could assume they should, but that is not specified anywhere.
• Same document two paragraphs later, inside the "installing roles from multiple files", we get an example that uses old syntax and is incompatible with the previous one. https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-multiple-roles-from-multiple-files

Please clarify this documentation and assure that it answers these questions:

• documents if requirements.yml at collection level is using the safe format as the one inside roles (meta/requirements.yml).
• document the deprecation of the old format and indicate when is going away
• preferably mention which is the minimal version of ansible that supports the newer format
• if examples are given using both formats, they should start with a comment mentioning the format they use, like "# v1 requirements format", or # v2 requirements format (ansible 2.x+)

ISSUE TYPE

• Documentation Report

COMPONENT NAME

documentation

ANSIBLE VERSION

devel

[ansibot]

Files identified in the description:
None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[sivel]

meta/requirements.yml only supports the v1 requirements format. We do not support dependencies between stand alone roles and collections (nor between collections and stand alone roles).

The v1 format is not deprecated.

The v2 requirements.yml format was introduced in 2.9, the ability to install both collections and roles from a single command was introduced in 2.10.

[ssbarnea]

To double check, please correct me if needed:

• root reqs supports both formats
• role-reqs supports only v1
• side-effect: a standalone-role cannot depend on collections
• side-effect: a collection can depend on a standalone-role, if you add it to your v2 file inside roles:.... still, it is up to the user to install them using current command as they are not automatically installed.
• adding meta/requirements.yml to roles from within a collection does not make sense as they are not processed or part of the installation.
• work done at Replace the inhouse collection dependency resolver with resolvelib #72591 is supposed to improve how ansible dependencies are installed

AFAIK galaxy-ng has zero support for bare roles and there are no plans to add it. To me it does not make sense, why to add so much complexity for a packaging format that presents no benefits over the newer collections one. I do understand that the v1 is not deprecated, but based on what I hear, is a matter of time until it will happen. I really doubt there is even one Ansible user that enjoys the idea that he needs to run install twice in order to install the deps.

[webknjaz]

• side-effect: a collection can depend on a standalone-role, if you add it to your v2 file inside roles:.... still, it is up to the user to install them using current command as they are not automatically installed.

Sounds like you confuse environment and package (role or collection) dependencies. Collection dependencies are only specified in galaxy.yml in source and are then moved to MANIFEST.json inside the built artifact, they only have a mapping of FQCN to version, that's it.

Another thing is requirements.yml (could be called anything, actually) that one must use via ansible-galaxy collection install -r requirements.yml. It's a user-side environment dependencies list that their playbooks need, nothing to do with a specific collection dependencies whatsoever.

The difference is the same as between setup.cfg (setup.py) and requirements.txt in pip ecosystem.

[s-hertel]

side-effect: a collection can depend on a standalone-role, if you add it to your v2 file inside roles:.... still, it is up to the user to install them using current command as they are not automatically installed.

Well, couldn't you also use a FQCN in a standalone role's deps and have the side-effect of a standalone role depending upon a collection and needing to manually install that too?

A collection's roles should only depend on other roles in the collection or roles of its dependencies. A collection's dependencies are in the format {collection_identifier: version} in the MANIFEST.json/galaxy.yml and standalone roles are not supported. Collection dependencies are installed with the collection itself unless --no-deps is used.

Standalone roles should depend on standalone roles, collections should depend on other collections. We should clarify this in the documentation.

work done at #72591 is supposed to improve how ansible dependencies are installed

for collections, but it isn't really a behavioral change

[jhampson-dbre]

I stumbled here while following the instructions Migrating a role to a collection.
Step 4 is "Update galaxy.yml to include any role dependencies."

Based on the thread above, it sounds like role dependencies should not be in the galaxy.yml unless they are a collection? Error message when importing collection to galaxy is:

ERROR! Galaxy import process failed: Invalid collection metadata. Dependency collection not in galaxy: geerlingguy.docker (Code: GLW0002)

with the dependencies defined in galaxy.yml

dependencies:
  "geerlingguy.docker": ">=3.0.0"

Using ansible-2.10.6 ansible-base-2.10.5

[jborean93]

Dependencies in a galaxy.yml is just for Collection dependencies. There is no cross dependency support to have a collection dependent on a role and vice versa. They are completely separate artifacts and should be treated as such.

[jhampson-dbre]

I realize that now, but I thought it was a good example of how the documentation around requirements.yml, meta/requirements.yml, meta/main.yml, galaxy.yml and dependency management in general between roles and collections is confusing.

[jhampson-dbre]

Standalone roles should depend on standalone roles, collections should depend on other collections. We should clarify this in the documentation.

What is the appropriate dependency management solution for moving a standalone role to a collection if it has a dependency on another standalone role? It sounds like there isn't one?

[sivel]

What is the appropriate dependency management solution for moving a standalone role to a collection if it has a dependency on another standalone role? It sounds like there isn't one?

You are correct, there isn't one. Stand alone roles, and collections (as well as roles in collections) cannot depend on each other. Only collection<->collection, and standalone-role<->standalone-role. To get dep auto installation, both would have to be stand alone roles, or both would have to live in collections.

Otherwise users are on their own to install the deps.

[JensHeinrich]

Can this please be added to to documentation explicitely (or an apropriate error be added to the ansible-galaxy CLI) ?

eg: check if there is a collections: key in meta/requirements.yml and print out a warning?
(and maybe install roles listed in roles?)

[kombinatgmbh]

There is also another inconsistency. https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file says

While both roles and collections can be specified in one requirements file, they need to be installed separately. The ansible-galaxy role install -r requirements.yml will only install roles and ansible-galaxy collection install -r requirements.yml -p ./ will only install collections.

At the same time https://docs.ansible.com/ansible/latest/user_guide/collections_using.html states

To install both roles and collections at the same time with one command, run the following: $ ansible-galaxy install -r requirements.yml

[ssbarnea]

I do really hope we endup with a single galaxy command for installing both types of dependencies. It makes no sense to have two different commands for installing deps declared inside the same file.

What if we add another dependency type? Are we going to add a 3rd command for those?

PS. I know that this observation is bit outside the original issue, but is closely related to it.

[sivel]

This commit 400475a added additional handling to enforce and provide friendly errors that meta/requirements.yml must be v1 format.

I do really hope we endup with a single galaxy command for installing both types of dependencies.

The ansible-galaxy install command can handle both, whereas the role install and collection install are specific.

I'm going to proceed with closing this.

If you have further questions please stop by IRC or the mailing list:

• IRC: #ansible on irc.libera.chat
• mailing list: https://groups.google.com/forum/#!forum/ansible-project