{"id":51393,"date":"2025-08-07T10:18:24","date_gmt":"2025-08-07T10:18:24","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=51393"},"modified":"2025-08-07T10:18:24","modified_gmt":"2025-08-07T10:18:24","slug":"what-is-ansible-collection-2","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/what-is-ansible-collection-2\/","title":{"rendered":"What is Ansible Collection?"},"content":{"rendered":"\n<h2 class=\"wp-block-heading\" id=\"what-is-ansible-collection\">What is Ansible Collection?<\/h2>\n\n\n\n<p><strong>Ansible Collections<\/strong> are a standardized packaging format for distributing Ansible content (roles, modules, plugins, playbooks, and documentation). Introduced in Ansible 2.9+, collections allow you to easily share, install, and manage sets of automation assets together.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>A collection organizes content under a common namespace and name (e.g., <code>community.mysql<\/code>).<\/li>\n\n\n\n<li>It may include:\n<ul class=\"wp-block-list\">\n<li>Roles<\/li>\n\n\n\n<li>Playbooks<\/li>\n\n\n\n<li>Modules<\/li>\n\n\n\n<li>Plugins (lookup, filter, callback, etc.)<\/li>\n\n\n\n<li>Documentation and tests<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Before Collections<\/h2>\n\n\n\n<p>Earlier, most content was shipped with Ansible or required to be managed separately as roles (via Ansible Galaxy). There was no simple, standard bundle for sharing custom modules, plugins, and roles together. Collections solve these challenges by grouping and versioning all content for modular use and distribution.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"why-do-we-need-ansible-collections\">Why Do We Need Ansible Collections?<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Modularity:<\/strong> Package all automation content (plugins, modules, roles, playbooks, docs) together, decoupled from Ansible core.<\/li>\n\n\n\n<li><strong>Versioning:<\/strong> Install and use specific versions, enabling more reliable dependency management for automations.<\/li>\n\n\n\n<li><strong>Distribution:<\/strong> Distribute content via platforms like Ansible Galaxy, Automation Hub, or private repositories.<\/li>\n\n\n\n<li><strong>Community &amp; Vendor Content:<\/strong> Use well-defined namespaces (e.g., <code>community.general<\/code>, <code>cisco.ios<\/code>) for community- or vendor-created collections.<\/li>\n\n\n\n<li><strong>Upgrades and Maintenance:<\/strong> Update collections independently of Ansible engine, making it easier to keep automation content up to date.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"how-to-use-ansible-collections\">How to Use Ansible Collections<\/h2>\n\n\n\n<h2 class=\"wp-block-heading\">1. Installing a Collection<\/h2>\n\n\n\n<p>Install a collection from Galaxy or Automation Hub:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection install community.mysql\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li>By default, collections are installed to <code>~\/.ansible\/collections<\/code> or globally if run as root.<\/li>\n<\/ul>\n\n\n\n<p>Install a specific version:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection install community.mysql:==3.8.0\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">2. Listing Installed Collections<\/h2>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection list\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">3. Using Collection Content in Playbooks<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Modules\/Plugins:<\/strong> Use the Fully-Qualified Collection Name (FQCN), e.g., <code>community.mysql.mysql_db<\/code>.<\/li>\n<\/ul>\n\n\n\n<pre class=\"wp-block-preformatted\">text<code>- name: Create a MySQL database\n  hosts: dbservers\n  tasks:\n    - name: Create database\n      community.mysql.mysql_db:\n        name: example\n        state: present\n        login_user: root\n        login_password: s3cret\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Roles:<\/strong> Reference within <code>roles<\/code> section:<\/li>\n<\/ul>\n\n\n\n<pre class=\"wp-block-preformatted\">text<code>roles:\n  - role: community.mysql.mysql_role\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Plugins:<\/strong> Loaded automatically when present in installed collections.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">4. Using Collections in the <code>collections:<\/code> Block<\/h2>\n\n\n\n<p>You can reduce boilerplate by declaring required collections at the playbook level:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">text<code>---\n- hosts: all\n  collections:\n    - community.mysql\n  tasks:\n    - mysql_db:\n        name: test\n        state: present\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The task will now use <code>community.mysql.mysql_db<\/code> as just <code>mysql_db<\/code>.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">5. Using Collections in Requirements<\/h2>\n\n\n\n<p>Declare project dependencies in a <code>requirements.yml<\/code>:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">text<code>collections:\n  - name: community.mysql\n    version: \"&gt;=3.8.0,&lt;4.0.0\"\n  - name: amazon.aws\n<\/code><\/pre>\n\n\n\n<p>Install all requirements:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection install -r requirements.yml\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"how-to-create-an-ansible-collection\">How to Create an Ansible Collection<\/h2>\n\n\n\n<h2 class=\"wp-block-heading\">1. Initialize a Collection Skeleton<\/h2>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection init my_namespace.my_collection\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Produces <code>my_namespace\/my_collection\/<\/code> with directories for plugins, roles, docs, tests, etc.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">2. Add Content<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Place modules in <code>plugins\/modules\/<\/code><\/li>\n\n\n\n<li>Put roles in <code>roles\/<\/code><\/li>\n\n\n\n<li>Add filter plugins, lookup plugins, etc., in corresponding plugin directories.<\/li>\n\n\n\n<li>Add documentation in <code>docs\/<\/code><\/li>\n\n\n\n<li>Write tests in <code>tests\/<\/code><\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">3. Edit <code>galaxy.yml<\/code><\/h2>\n\n\n\n<p>Defines collection metadata, dependencies, authors, etc.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Namespace and name<\/li>\n\n\n\n<li>Description<\/li>\n\n\n\n<li>License, etc.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">4. Build the Collection Package<\/h2>\n\n\n\n<p>From the root collection directory:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">bash<code>ansible-galaxy collection build\n<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Creates a <code>.tar.gz<\/code> distributable artifact.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">5. Publish or Share<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Publish to Ansible Galaxy (requires account): bash<code>ansible-galaxy collection publish .\/my_namespace-my_collection-*.tar.gz<\/code><\/li>\n\n\n\n<li>Or upload to Automation Hub\/private repo.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"advanced-developing--testing-a-collection\">Advanced: Developing &amp; Testing a Collection<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Use <code>ansible-test<\/code> for unit and integration tests (<code>tests\/<\/code> directory).<\/li>\n\n\n\n<li>Use <code>molecule<\/code> for role\/playbook scenario testing (see [previous suggestions]).<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"other-important-detailsmissing-info\">Other Important Details\/Missing Info<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Namespace Conventions:<\/strong> Namespace must be unique (vendor, project, or username; lowercase, no spaces).<\/li>\n\n\n\n<li><strong>Dependencies:<\/strong> List other collections as dependencies in <code>galaxy.yml<\/code> (<code>dependencies:<\/code> key).<\/li>\n\n\n\n<li><strong>Documentation:<\/strong> Each module, role, or plugin should have YAML\/Markdown docs for Galaxy rendering.<\/li>\n\n\n\n<li><strong>Collection Path Precedence:<\/strong> Ansible resolves content in this order: playbook\/project <code>collections\/<\/code> \u2192 user\u2019s default location \u2192 system path.<\/li>\n\n\n\n<li><strong>Backward Compatibility:<\/strong> Older content (roles, modules) should be refactored into collections for modern workflows.<\/li>\n\n\n\n<li><strong>Private Collections:<\/strong> You can run your own Galaxy\/Automation Hub server for internal sharing.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"summary-table\">Summary Table<\/h2>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Action<\/th><th>Command\/Step<\/th><\/tr><\/thead><tbody><tr><td>Install a collection<\/td><td><code>ansible-galaxy collection install &lt;namespace&gt;.&lt;name&gt;<\/code><\/td><\/tr><tr><td>Use a module from a collection<\/td><td><code>namespace.collection.module<\/code> or via <code>collections:<\/code> block<\/td><\/tr><tr><td>List installed collections<\/td><td><code>ansible-galaxy collection list<\/code><\/td><\/tr><tr><td>Initialize a collection skeleton<\/td><td><code>ansible-galaxy collection init ns.coll<\/code><\/td><\/tr><tr><td>Build collection for distribution<\/td><td><code>ansible-galaxy collection build<\/code><\/td><\/tr><tr><td>Publish to Galaxy<\/td><td><code>ansible-galaxy collection publish &lt;tarball&gt;<\/code><\/td><\/tr><tr><td>Add dependencies in collection<\/td><td>Edit <code>galaxy.yml<\/code> (dependencies section)<\/td><\/tr><tr><td>Use dependencies in project<\/td><td>Add to <code>requirements.yml<\/code>, then install<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"references\">References<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>[Official Ansible Collections Documentation]<\/li>\n\n\n\n<li>[Ansible Galaxy Collections Guide]<\/li>\n\n\n\n<li>[Red Hat Automation Hub Collection Info]<\/li>\n<\/ul>\n\n\n\n<p>: <a rel=\"noreferrer noopener\" target=\"_blank\" href=\"https:\/\/docs.ansible.com\/ansible\/latest\/dev_guide\/collections_tech.html\">https:\/\/docs.ansible.com\/ansible\/latest\/dev_guide\/collections_tech.html<\/a><br>: <a rel=\"noreferrer noopener\" target=\"_blank\" href=\"https:\/\/galaxy.ansible.com\/docs\/collections.html\">https:\/\/galaxy.ansible.com\/docs\/collections.html<\/a><br>: <a rel=\"noreferrer noopener\" target=\"_blank\" href=\"https:\/\/access.redhat.com\/documentation\/en-us\/red_hat_ansible_automation_platform\/2.5\/html-single\/getting_started_with_automation_hub\/index\">https:\/\/access.redhat.com\/documentation\/en-us\/red_hat_ansible_automation_platform\/2.5\/html-single\/getting_started_with_automation_hub\/index<\/a><\/p>\n\n\n\n<p><strong>In summary:<\/strong><br>Ansible Collections are a modern, standardized mechanism to organize, share, and version all types of Ansible content. You use them to install and consume content (modules, roles, plugins) with clear namespaces and manageable dependencies. You create them with <code>ansible-galaxy collection init<\/code>, add content, build, and (optionally) publish. They are essential for scale, modularity, and modern Ansible workflows.<\/p>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>What is Ansible Collection? Ansible Collections are a standardized packaging format for distributing Ansible content (roles, modules, plugins, playbooks, and documentation). Introduced in Ansible 2.9+, collections allow you to easily&#8230; <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-51393","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51393","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=51393"}],"version-history":[{"count":1,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51393\/revisions"}],"predecessor-version":[{"id":51396,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/51393\/revisions\/51396"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=51393"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=51393"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=51393"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}