RH294: ansible-galaxy requirements.yml files

[JS_Learning]

Hello,

I am following the course RH294, using the document "RH294-RHEL8.0-en-1-20190531".

On page 328 it starts to mention about requirements.yml files, used for installing a particular role.

I am trying to understand how we are supposed to know about the values inside that file:

Exemple:

# from any Git-based repository, using SSH
- src: git@gitlab.com:guardianproject-ops/ansible-nginx-acme.git
scm: git
version: master
name: nginx-acme-ssh

1) Where do we know that we have to write "src, scm, version, name"...?

2) For git, it looks we need to provide the above values. Let's say someone use something else or ask to use something else, how can we find what is required?

I am trying to understand the "how to" rather than to make it work (I managed to make it work by simply copy/paste as in the example).

Thanks,

[JangoJeff]

You'll need to use the Ansible documentation at docs.ansible.com. I've provided a link to all moduels below. You can look up the module and see what all the parameters is takes, needs and what each parameter does. 

https://docs.ansible.com/ansible/latest/modules/list_of_all_modules.html?highlight=git%20repo 

[JS_Learning]

Thanks, 

Indeed one can read the docs at ansible online, I should have specified I was trying to find out "within the tool" or within the OS, not necessarily with internet access.

I should clarify, sometimes there is :

-A man page

-information in "--help"

-Some default config files explaining how to do (like /etc/crontab...).

I was thinking maybe there is similar with that requirement file.

[JangoJeff]

Actually you can get the infomaiton without going online. Type ansible-doc MODULENAME
for example
ansible-doc copy
This will show you information on the copy module.
or for Help type 
ansible-doc -h
or for a list of modules
ansible-doc -l
You can also pipe it to grep to find more specific ones.
ansible-doc - l | grep httpd
You can also find out what functions are availble for a modue by typing
ansible-doc -s MODULENAME

Hope that helps

[JS_Learning]

Thanks for informing about that :)

I fully appreciate your efforts and good intentions. Just it would be even more helpful if it would be a little bit more related to the topic I raised...

What I am trying to say is that the initial question is specifically about the "requirements files" and how to find about it offline- It's true, ansible-doc is available offline, from the terminal. It's true there's great features to use it better like you said- But none of that helps for finding how to write the requirements.yml file offline.

In fact there's no ansible-doc for ansible-galaxy because it's not a module. Also, ansible-galaxy doesn't, as far as I tried, provide anything about the requirement file. It seems that it's simply something which "needs to be known".

In fact even when reading the official page, it seems forgetting that it's supposed to provide information to the reader, not be a "knowledge display for others". I am referring to the fact that SCM is not defined. Ok, I made the connection GIT/SCM source control manager (I assume it means that). But it should be clearly documented, as it's not necessarily clear within the context.

Oh well. I gave you kudo as a gesture of good intentions (eventhough I'm quite familiar with Ansible, it might help others).

Cheers,

[andkra · Accepted solution]

The syntax of the requirements.yml file is documented here:

https://docs.ansible.com/ansible/latest/reference_appendices/galaxy.html#installing-multiple-roles-f...

Greetings
Andreas

[JS_Learning]

Thanks,

I see it is explained there, thank you.

However, during events when the online doc is not available, it's not so easy to find these explanations (for example during a certification exam).

For now that's good enough to learn :D

[littlebigfab]

Hi @JS_Learning,

You're making an assumption here. Relevant online documentation may very well be available during a certification exam. The goal of such an exam is absolutely not to trick you into memorizing complex data structures.

Cf. the following exam's objective:

- Use provided documentation to look up specific information about Ansible modules and commands

However, I wouldn't call the structure of an Ansible Galaxy requirement file 'complex'. Think of it as a list of roles to import. Each item in that list is introduced by an hyphen and is actually a dictionary made up with 4 key/values. The key names are explicit and pretty easy to remember.

I probably would try and memorize that structure before taking a related Red Hat exam.

Note that I have not taken EX294 yet.

[JS_Learning]

Hi,

Oh no, I have far too many experiences to know not to make any assumptions. So to be accurate, I did not make any assumption(s).

In fact, I am already Ansible certified from RedHat (I know if the doc is/was available in that context; I don't know about EX294 but that does not change much to the topic). I was trying to be generic, saying that during the learning, one should find the information without these online documentation. 

I'm not debatting that any exam goals are to "trick you into memory complex data structures", but my previous experiences with these exams are that I should be able to do/understand how to do everything related to the topic without internet resources. 

You are correct, the structure of a requirement file is not that complex...Once you know and understand what's required and "what is what". I copied the information blindly during the training, but that's clearly not enough. In fact it should have been made clearer why it's using these key/values and what they are for. Thanks to the online link I know better, I wish that information was provided during the course and also was available in the OS, as an example requirement.yml file... I used before the example of crontab as a reference.

Yes, the keys are explicit and easy to remember. That's combining them with the 100 others commands to remember that starts to be difficult :D. During an exam, it's pretty much "do or die", if the syntax is wrong, it will not work, fail and sometimes impact other question(s). The loss of points can be serious enough to fail. Again, no assumptions I have been there before :D

Anyway, as I see it, to move forward, it's:

-Know where it is in official doc

-Remember the parameters in the event that official doc is not available

-Report that one way or another to improve the situation, for example improving the man page or help for ansible-galaxy.

Cheers!

[littlebigfab]

Hi @JS_Learning,

Even in the worst case scenario where you cannot locate the expected structure in any manual, there are still available options. I would first give a try with an incomplete requirement yaml file made up with what I can remember, to steal information from stdin (with maximal verbosity) or stderr :

# cat "- src: foo" > requirements.yml
# ansible-galaxy install -vvv -r requirements.yml -p roles/
...truncated output...
found role {'scm': None, 'src': 'foo', 'version': '', 'name': 'foo'} in yaml file

-> Voilà ! The expected dictionary structure immediately appears ! :)

If I were to take EX294, I would just make sure to remember that src key ;)

If you don't even remember it, the last resort is to dig into the source code :

# cat "- {}" > requirements.yml
# ansible-galaxy install -vvv -r requirements.yml -p roles/
...truncated output...
Traceback (most recent call last):
...truncated output...
File "/usr/lib/python2.7/site-packages/ansible/cli/galaxy.py", line 149, in run

Inspecting the galaxy.py file enventually leads you to this interesting line:

342     raise AnsibleError("Must specify name or src for role")

-> you're able to retrieve the src key here

I had to use similar source-code digging on my latest certification exam (EX447), for a very tricky situation, and in the end I found what I needed ;)