mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
285 lines
11 KiB
ReStructuredText
285 lines
11 KiB
ReStructuredText
5 years ago
|
:orphan:
|
||
|
|
||
|
.. _collections:
|
||
|
|
||
5 years ago
|
***********
|
||
5 years ago
|
Collections
|
||
5 years ago
|
***********
|
||
|
|
||
5 years ago
|
|
||
|
Collections are a distribution format for Ansible content. They can be used to
|
||
|
package and distribute playbooks, roles, modules, and plugins.
|
||
5 years ago
|
You will be able to publish and use collections through `Ansible's Galaxy repository <https://galaxy.ansible.com>`_.
|
||
5 years ago
|
|
||
|
.. important::
|
||
|
This feature is available in Ansible 2.8 as a *Technology Preview* and therefore is not fully supported. It should only be used for testing and should not be deployed in a production environment.
|
||
|
Future Galaxy or Ansible releases may introduce breaking changes.
|
||
|
|
||
|
|
||
5 years ago
|
.. contents::
|
||
|
:local:
|
||
|
|
||
|
Collection structure
|
||
5 years ago
|
====================
|
||
|
|
||
5 years ago
|
Collections follow a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. They do require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy
|
||
5 years ago
|
and other tools need in order to package, build and publish the collection.::
|
||
|
|
||
|
collection/
|
||
|
├── docs/
|
||
|
├── galaxy.yml
|
||
|
├── plugins/
|
||
|
│ ├── modules/
|
||
|
│ │ └── module1.py
|
||
|
│ ├── inventory/
|
||
|
│ └── .../
|
||
|
├── README.md
|
||
|
├── roles/
|
||
|
│ ├── role1/
|
||
|
│ ├── role2/
|
||
|
│ └── .../
|
||
|
├── playbooks/
|
||
|
│ ├── files/
|
||
|
│ ├── vars/
|
||
|
│ ├── templates/
|
||
|
│ └── tasks/
|
||
|
└── tests/
|
||
|
|
||
|
|
||
|
.. note::
|
||
|
* We will only accept ``.yml`` extensions for galaxy.yml.
|
||
|
* A full structure can be found at `Draft collection <https://github.com/bcoca/collection>`_
|
||
|
* Not all directories are currently in use. Those are placeholders for future features.
|
||
|
|
||
|
|
||
|
galaxy.yml
|
||
|
----------
|
||
|
|
||
5 years ago
|
A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact.
|
||
|
See :ref:`collections_galaxy_meta` for details on how this file is structured.
|
||
|
|
||
5 years ago
|
|
||
|
docs directory
|
||
|
---------------
|
||
|
|
||
5 years ago
|
Keep general documentation for the collection here. Plugins and modules will still keep their specific documentation embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Currently we are looking at Markdown as the standard format for documentation files, but this is subject to change.
|
||
5 years ago
|
|
||
5 years ago
|
We are `updating ansible-doc <https://github.com/ansible/ansible/pull/57764>`_ to allow showing documentation for plugins inside a collection::
|
||
5 years ago
|
|
||
|
ansible-doc -t lookup mycol.myname.lookup1
|
||
|
|
||
|
The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation.
|
||
|
|
||
|
|
||
|
plugins directory
|
||
|
------------------
|
||
|
|
||
|
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by any other plugin by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
|
||
|
|
||
|
|
||
|
roles directory
|
||
|
----------------
|
||
|
|
||
|
Collection roles are mostly the same as existing roles, but with a couple of limitations:
|
||
|
|
||
|
- Role names are now limited to contain only lowercase alphanumeric characters, plus ``_`` and start with an alpha character.
|
||
|
- Roles cannot have their own plugins any more. The plugins must live in the collection ``plugins`` directory and will be accessible to the collection roles.
|
||
|
|
||
|
The directory name of the role is used as the role name. Therefore, the directory name must comply with the
|
||
|
above role name rules.
|
||
|
The collection import into Galaxy will fail if a role name does not comply with these rules.
|
||
|
|
||
|
You can migrate 'traditional roles' into a collection but they must follow the rules above. You man need to rename roles if they don't conform. You will have to move or link any role-based plugins to the collection specific directories.
|
||
|
|
||
|
.. note::
|
||
|
|
||
|
For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` value in the role's
|
||
|
metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a
|
||
|
collection, Galaxy uses the role directory as the name of the role and ignores the ``role_name`` metadata value.
|
||
|
|
||
|
playbooks directory
|
||
|
--------------------
|
||
|
|
||
|
TBD.
|
||
|
|
||
|
tests directory
|
||
|
----------------
|
||
|
|
||
|
TBD. Expect tests for the collection itself, including Molecule files, to reside here.
|
||
|
|
||
|
|
||
|
.. _creating_collections:
|
||
|
|
||
5 years ago
|
Creating collections
|
||
5 years ago
|
====================
|
||
|
|
||
5 years ago
|
This is currently is a work in progress. We created the `Mazer <https://galaxy.ansible.com/docs/mazer/>`_ command line tool
|
||
5 years ago
|
available at the `Ansible Mazer project <https://github.com/ansible/mazer>`_. as a proof of concept for packaging,
|
||
5 years ago
|
distributing and installing collections. You can install ``mazer`` with ``pip install mazer`` or checkout the code directly.
|
||
5 years ago
|
|
||
|
.. Note::
|
||
|
All the documentation below that use ``mazer`` might be updated to use another tool in the future as ``mazer`` will not be updated in the future.
|
||
|
|
||
5 years ago
|
We are working on integrating this into Ansible itself for 2.9. Currently we have an `ansible-galaxy PR <https://github.com/ansible/ansible/pull/57106>`_ incorporating some of the commands into ``ansible-galaxy``. Currently it is not installable outside Ansible, but we hope to land this into development soon so early adopters can test.
|
||
5 years ago
|
|
||
|
.. Note::
|
||
5 years ago
|
Any references to ``ansible-galaxy`` below will be of a 'working version' either in this PR or subsequently in development. As such, the command and this documentation section is subject to frequent change.
|
||
5 years ago
|
|
||
|
We also plan to update `Ansible Molecule <https://github.com/ansible/molecule>`_, for a full developer toolkit with integrated testing.
|
||
|
|
||
|
In the end, to get started with authoring a new collection it should be as simple as:
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
5 years ago
|
collection_dir#>ansible-galaxy collection init
|
||
5 years ago
|
|
||
|
|
||
5 years ago
|
And then populating the directories with the content you want inside the collection. For now you can optionally clone from https://github.com/bcoca/collection to get the directory structure (or just create the directories as you need them).
|
||
5 years ago
|
|
||
|
.. _building_collections:
|
||
|
|
||
5 years ago
|
Building collections
|
||
5 years ago
|
====================
|
||
|
|
||
|
Collections are built by running ``mazer build`` from inside the collection's root directory.
|
||
5 years ago
|
This will create a ``releases/`` directory inside the collection with the build artifacts,
|
||
5 years ago
|
which can be uploaded to Galaxy.::
|
||
|
|
||
|
collection/
|
||
|
├── ...
|
||
5 years ago
|
├── releases/
|
||
5 years ago
|
│ └── namespace_name-collection_name-1.0.12.tar.gz
|
||
|
└── ...
|
||
|
|
||
|
.. note::
|
||
|
Changing the filename of the tarball in the release directory so that it doesn't match
|
||
|
the data in ``galaxy.yml`` will cause the import to fail.
|
||
|
|
||
|
|
||
|
This tarball itself can be used to install the collection on target systems. It is mainly intended to upload to Galaxy as a distribution method, but you should be able to use directly.
|
||
|
|
||
5 years ago
|
Publishing collections
|
||
5 years ago
|
======================
|
||
|
|
||
5 years ago
|
We are in the process of updating Ansible Galaxy to manage collections as it currently manages roles.
|
||
5 years ago
|
|
||
|
|
||
5 years ago
|
Upload from the Galaxy website
|
||
5 years ago
|
------------------------------
|
||
|
|
||
5 years ago
|
Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces. From
|
||
5 years ago
|
the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local
|
||
|
filesystem.
|
||
|
|
||
5 years ago
|
When uploading collections it doesn't matter which namespace you select. The collection will be uploaded to the
|
||
|
namespace specified in the collection metadata in the ``galaxy.yml`` file. If you're not an owner of the
|
||
5 years ago
|
namespace, the upload request will fail.
|
||
|
|
||
|
Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the
|
||
|
import process, including any errors or warnings about the metadata and content contained in the collection.
|
||
|
|
||
5 years ago
|
Upload using mazer
|
||
5 years ago
|
------------------
|
||
|
|
||
5 years ago
|
You can upload collection artifacts with ``mazer``, as shown in the following example:
|
||
5 years ago
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
mazer publish --api-key=SECRET path/to/namespace_name-collection_name-1.0.12.tar.gz
|
||
|
|
||
|
The above command triggers an import process, just as if the collection had been uploaded through the Galaxy website. Use the **My Imports**
|
||
|
page to view the output from the import process.
|
||
|
|
||
5 years ago
|
Your API key can be found on `the preferences page in Galaxy <https://galaxy.ansible.com/me/preferences>`_.
|
||
5 years ago
|
|
||
5 years ago
|
To learn more about Mazer, see `Mazer <https://galaxy.ansible.com/docs/mazer/>`_.
|
||
5 years ago
|
|
||
|
|
||
5 years ago
|
Collection versions
|
||
5 years ago
|
-------------------
|
||
|
|
||
|
Once you upload a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before
|
||
|
uploading. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number)
|
||
|
will be the version displayed everywhere in Galaxy; however, users will still be able to download older versions.
|
||
|
|
||
|
|
||
5 years ago
|
Installing collections
|
||
5 years ago
|
======================
|
||
|
|
||
|
The recommended way to install a collection is:
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
5 years ago
|
#> ansible-galaxy collection install mycollection -p /path
|
||
5 years ago
|
|
||
|
assuming the collection is hosted in Galaxy.
|
||
|
|
||
|
You can also use a tarball resulting from your build:
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
5 years ago
|
#> ansible-galaxy install mynamespace.mycollection.0.1.0.tgz -p /path
|
||
5 years ago
|
|
||
|
|
||
5 years ago
|
As a path you should use one of the values configured in `COLLECTIONS_PATHS <https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths>`_. This is also where Ansible itself will expect to find collections when attempting to use them.
|
||
5 years ago
|
|
||
5 years ago
|
You can also keep a collection adjacent to the current playbook, under a ``collections/ansible_collection/`` directory structure.
|
||
5 years ago
|
|
||
|
::
|
||
|
|
||
|
play.yml
|
||
|
├── collections/
|
||
|
│ └── ansbile_collection/
|
||
|
│ └── myname/
|
||
5 years ago
|
│ └── mycol/<collection structure lives here>
|
||
5 years ago
|
|
||
|
|
||
|
|
||
|
|
||
5 years ago
|
Using collections
|
||
5 years ago
|
=================
|
||
|
|
||
|
Once installed, you can reference collection content by its FQCN:
|
||
|
|
||
|
.. code-block:: yaml
|
||
|
|
||
|
- hosts: all
|
||
|
tasks:
|
||
|
- myname.mycol.mymodule:
|
||
|
option1: value
|
||
|
|
||
|
This works for roles or any type of plugin distributed within the collection:
|
||
|
|
||
|
.. code-block:: yaml
|
||
|
|
||
|
- hosts: all
|
||
|
tasks:
|
||
|
- include_role:
|
||
|
name : myname.mycol.role1
|
||
5 years ago
|
- myname.mycol.mymodule:
|
||
|
option1: value
|
||
5 years ago
|
|
||
|
- debug:
|
||
|
msg: '{{ lookup("myname.mycol.lookup1", 'param1')| myname.mycol.filter1 }}'
|
||
|
|
||
|
|
||
|
To avoid a lot of typing, you can use the ``collections`` keyword added in Ansbile 2.8:
|
||
|
|
||
|
|
||
|
.. code-block:: yaml
|
||
|
|
||
|
- hosts: all
|
||
|
collections:
|
||
|
- myname.mycol
|
||
|
tasks:
|
||
|
- include_role:
|
||
|
name: role1
|
||
5 years ago
|
- mymodule:
|
||
|
option1: value
|
||
5 years ago
|
|
||
|
- debug:
|
||
5 years ago
|
msg: '{{ lookup("myname.mycol.lookup1", 'param1')| myname.mycol.filter1 }}'
|
||
5 years ago
|
|
||
|
This keyword creates a 'search path' for non namespaced plugin references. It does not import roles or anything else.
|
||
5 years ago
|
Notice that you still need the FQCN for non-action or module plugins.
|