Ansible Naming Rules for Roles and Collections (dash, underscore)

Question

Does Ansible have naming rules for roles and collections regarding the use of - (dash) and _ (underscore)?

• I noticed that since around 2019, geerlingguy only uses underscores for role names (snake_case), but the names of his older roles contain dashes (kebab-case).

• For one role in the Ansible Galaxy, I encountered the following note:

  NOTE: This role has been renamed from acme-sh to acme_sh to fullfill Ansible Galaxy requirements.

• I then looked through the Ansible Galaxy documentation, but only found naming conventions (limitations) for namespaces, but not for role or collection names. The example on the Creating Roles page of the Ansible Galaxy documentation also uses dashes in the name: test-role-1.

• I am aware that all Ansible Builtin modules use underscores only, so strictly snake_case (as far as I have seen so far). There are probably modules that allow parameters via alias also in kebab-case (e.g. apt), but rather few.

• In the Role Names section, I found this hint in the first note:

  Role names are limited to lowercase word characters (i.e., a-z, 0-9) and ‘_’.

  However, it is unclear to me for which places or operations this applies, because there are quite a few roles in the Ansible Galaxy with dashes in the name, likewise an ansible-galaxy role init my-super-role works without problems and without any hint.

Are there any Ansible or Ansible Galaxy requirements for using dashes or underscores?
Or are there official recommendations or even technical restrictions?
Is there a recommendation in general?

Answer 1

You're asking a number of somewhat related questions, so I'll try to break them apart and address each one individually.

Does Ansible have naming rules for roles?

Not exactly. It has technical constraints, including that the role name must be a valid filename and representable as a YAML string.

Does Ansible have naming rules for collections?

Yes. These again arise from technical constraints, but they are more well-defined and considerably stricter. The namespace, collection name, and all collection content (including roles) must be valid Python identifiers (containing only A-Z, a-Z, _, 0-9, or a subset of Unicode characters, but not beginning with a numeral.)

Does Ansible Galaxy have naming rules for roles?

Yes. Role names are limited to a-z, 0-9, and _. During import, any . and - characters contained in the repository name or role_name will be replaced with _.

Does Ansible Galaxy have naming rules for collections?

Yes. Collection names and content are limited to Python identifiers containing a-z, 0-9, and _. Import will fail if the uploaded collection artifact contains names that Galaxy does not allow.

Why does Ansible Galaxy contain roles that don't meet their naming rules?

The rules have changed over time, and forcibly removing or renaming content that existed before these rules were in place would break things for people who were using that content.