Why we need to put fully ansible.builtin.xxx in ansible playbook? RH294

[benlimanto]

Why we need to put fully ansible.builtin.xxx in ansible playbook even when we use xxx it also work as it's ? take example apt, ping, and dnf, we can write it down as it's, eg like this :

---

- name: apt w3m

  hosts: all

  tasks:

    - apt:

       name: w3m

       status: latest

...

Rather than:

---

- name: apt w3m

  hosts: all

  tasks:

    - ansible.builtin.apt:

       name: w3m

       status: latest

...

Is there a reason for it? I seen it on the RH294 module, but I'm curious of it, as a lot of ansible playbook on github doesn't write it down fully, but working. Any pointer is really appreciated. Thank you!

cc @Travis (if it's allowed to mention people, sorry if it's annoying )

[Fran_Garcia]

Using the Fully Qualified collection name (FQCN) is a best practise - you want to be precise on what collection you want to use as many collections might provide a module named the same way.

Ansible builtins may come and go in different major versions, so this saves you the trouble of revising code (plus it makes code linters like ansible-lint happy )

[exceed]

When using features available in ansible.builtin I dont really see the point of this being a best practice. I think its a good practice to use in collections and modules though and I do think its a good idea to always use a FQCN, but it seems unnecessary when using builtins.

When you say that builtins may come and go... if they are removed then wouldnt your ansible file (or could you say "code" when refering to ansible yaml) break anyway ? It certainly would not work if the builtin is removed from my understanding. So, how does this save you the trouble of revising the code ? I'm probably missing something here though since Im still pretty new to Ansible.

[bonnevil]

I don't think that builtins going away would necessarily be a concern with this.  The dev team has rules that before a module is removed it has to be visibly deprecated (with warning messages) for several releases of Ansible; in ansible.builtin's case, this would be several releases of Ansible Core.  See https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html for details.

[bonnevil · Accepted solution]

Need is a tricky word.  Right now, you don't need to use FQCNs with ansible.builtin (or in fact many collections) because Ansible will resolve the short names to a collection name. This helps keep existing automation code from Ansible 2.9 and earlier working in Ansible 2.11+. The important question is should you start using FQCNs for ansible.builtin modules in new playbooks?

So, whether or not you should use FQCNs for modules in the ansible.builtin Ansible Content Collection that's always available in ansible-core has actually been a topic of discussion in the Ansible community since content collections were implemented.  Folks as active in the community as Jeff Geerling have argued that, especially for ansible.builtin, FQCNs should not be necessary since they feel like it is more typing and makes it harder to read their playbooks.  I guess this assumes that an unqualified name with a conflict will resolve to ansible.builtin first; I'd expect that to be true, but I don't know whether it's guaranteed to be true.

The bulk of the developers of Ansible itself seem to disagree with Jeff.  I have to say that I've come around on that point.

The main concern here is the whole reason they came up with FQCNs in the first place: to avoid collisions with other modules that happen to have the same unqualified name.

That could cause malfunctions, but I suppose in theory it could also cause security issues, if someone could manipulate the collections search path and collections provided in some way to deliberately cause Ansible to pick the module from the wrong collection.  Again, I don't even know if this is possible with ansible.builtin.

I mean, I'd have to dig into how collection name resolution works, but I know there are complexities with how that's defined and that additional collections can add their own rules for how to route module (and other plug-in) name resolution.

The developers of ansible-lint, based on input from the developers of Ansible Core, have decided that the best coding style decision is to use FQCNs in all cases for clarity, rather than having one rule for ansible.builtin and another for all the other Ansible Content Collections.  It's a style rule, at least for now, and you can turn it off in ansible-lint if you don't like it.  But they think that it's a better practice to use it than not to use it.

In the spirit of transparency, this is a link to the discussion in the ansible-lint upstream between Jeff Geerling and the ansible-lint devs where he was, at least at the time, disagreeing with this feature: https://github.com/ansible/ansible-lint/issues/2050.  In particular I'd suggest looking over Sorin Sbarnea's response for insight into what the ansible-lint folks are thinking.

For me, right now the focus for this is on new code.  I've got a lot of older automation that doesn't use FQCNs much yet, and I'll edit those as I update those playbooks.  But for anything new I'm writing, I've been using them.

[Travis]

@benlimanto -

Sorry it took a while to answer, but I agree with @bonnevil on many of the points he made. In general, and I'm also bad about this with my playbooks as I often don't use the FQCN for built-in collections, it is a best practice and a good habit that should should get into. I try to do this for all the courses I deliver, but sometimes I get lazy or forget. 

Currently it is more a "style" rule, but there can be other things where it might matter and you would get unintended behavior. Initially, I was really lazy and defined collections at the top of the playbook so I could use the "shorter" module name without the FQCN. However, what happens when there are two collections with the same module name or a custom collection where you've created a duplicate module name. Even worse, what happens when a "built-in" collection gets deprecated, but you have the same module name in another collection.

I've been going through and updating my playbooks to utilize the FQCNs as much as possible and I always attempt to use those during my demonstrations and newly developed playbooks. I've created a custom Execution Environment to run my old playbooks in so there aren't conflicts and I know I'm getting the collections/modules that I expect so that gives me a little more control, but I would exercise extreme caution and attempt to convert to using FQCNs ASAP as you develop new playbooks.

Travis

[benlimanto]

@Travis Thank you for replying, that cement the right/prefered answer, I just curious when I asked, and thank you for all respond to my simple question.