Document how to migrate a standalone role to a collection #68687
Conversation
samccann
added
docs
ansibot
added
core_review
|
@geerlingguy - would love feedback on this when you get a chance. |
| | :file:`library/` with custom modules | - Move to :file:`plugins/modules/` | | ||
| | | - Use :abbr:`FQCN (Fully Qualified Collection Name)` external to collection | | ||
| +----------------------------------------+------------------------------------------------------------------------------+ | ||
| |``ansible.module_utils`` in Python + Use :abbr:`FQCN (Fully Qualified Collection Name)` for Python imports | |
There was a problem hiding this comment.
Also since we're talking about roles still (a standalone role vs a role in a collection), what other content within the role directory besides plugins (which I believe have to actually move out of the role and into the collection proper) would need to use ansible.module_utils?
If this is more of a guide for "how to move plugins out of roles into collection plugins directories", then maybe this section/table should be re-introduced as
"roles can have the same structure inside collections as when they're standalone, but you have to move all the plugins and supporting Python code out of the role and into the collection, renaming and modifying the Python code like so:"
There was a problem hiding this comment.
snipped the table entirely. I think this is covered in the steps but let me know if anything is still missing.
|
(Forgot to leave comment for my review, so here it is) One thing I think is a little difficult with this doc is the fact that it's written mostly for the perspective of someone maintaining a role on Galaxy that is intended to become a collection on Galaxy—and even in that case there are a few parts that I think could be improved (see review comments). But from the perspective of converting an existing standalone role that is not on Galaxy, there are a few mines that are waiting for the unsuspecting user to step on, with regard to namespacing (not relevant for standalone roles, but it looks like we'll be required to make up our own namespace and have another three levels of empty directory heirarchy to navigate when using collections, so it's in Additionally, and I've opened an issue for this, the given |
|
(Noting that even prominent examples of Red Hat-maintained playbooks use standalone roles like the ones I mention in the comment above—see https://github.com/ansible/tower/tree/devel/installer/roles) Also, I didn't review the RPM packaging notes at the end of this PR as I don't have any experience there. |
ansibot
added
needs_revision
|
@geerlingguy - hmm github doesn't let me directly reply to some of your final comments. WRT being Galaxy-specific... I think this is in general a statement for the collection docs overall, correct? I'm not sure how many people create collections with no plan to upload them for others to use (in Galaxy/AH, etc). I'm reluctant to sprinkle in 'if you aren't ever uploading your collections... do blablabla'. Maybe what we need is a separate docs page that lists the exceptions for those who plan on 'standalone' private collections to cover this? |
|
@samccann - I think the problem is there are thousands (likely hundreds of thousands) of roles out there that have never been intended to be stored on galaxy (or in many cases even used in more than one playbook), and that use case is often neglected in collections docs since the primary driver behind most things collections—so far—has been module and plugin extraction from core and distribution. That use case is vastly different than what roles are/have been used for, so focusing on Galaxy and abstracted roles exclusively has blinded a lot of people to the problems and difficulties end users face when trying to work with roles in collections. |
|
the latest commit clarifies this is the instructions for shared roles in a collection on Galaxy. Also, separated the sections for simple roles vs roles with plugins. The TOC will look like this now: |
Co-Authored-By: Alicia Cozine <879121+acozine@users.noreply.github.com>
ansibot
added
needs_ci
|
|
||
| 1. Create a local :file:`ansible_collections` directory and ``cd`` to this new directory. | ||
|
|
||
| 2. Create a collection. You need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_ to import this collection to Galaxy. |
There was a problem hiding this comment.
I know we talked about this previously—but as this guide seems to be for any role (and not just roles that are already on Galaxy)—should this be a top level requirement, or can we move it to an aside? If an aside, I'd suggest:
If you wish to share your collection on Ansible Galaxy, you will need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>` to import the collection. Make sure you use the same namespace when creating the collection.
Something along those lines.
|
|
||
| .. note:: | ||
|
|
||
| In standalone roles, some of the plugin directories referenced their plugin types in the plural sense; this is not the case in collections. |
There was a problem hiding this comment.
Is this true? In the example above, we have modules/ in the plugins/ directory - that's plural.
|
|
||
| .. note:: | ||
|
|
||
| If you want to import your collection to Galaxy, you need a `Galaxy namespace <https://galaxy.ansible.com/docs/contributing/namespaces.html>`_. |
There was a problem hiding this comment.
I might move this to a "Prerequisites" section right above the migration instructions.
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
SUMMARY
Document how to migrate a standalone role to a collection.
Fixes #68473
ISSUE TYPE
COMPONENT NAME
docs.ansible.com
ADDITIONAL INFORMATION