Skip to content

Commit

Permalink
Backport/2.9/docs2 (#62805)
Browse files Browse the repository at this point in the history 
* Update pip module docs (#62359)
* Clarifying pip module requirements in reference to #47361
* Further clarifying message with link to ansible_python_interpreter

(cherry picked from commit d3ec5ca)

* chore/doc-module: sts_assume_role.py (#62475)
Update `Example` section with with the correct module usage.

(cherry picked from commit a4a2166)

* Improve dconf documentation to include conversion problems (#62316)

(cherry picked from commit 8649283)

* Add examples for various inventory setups to the documentation (#62323)
* Updates docs/docsite/rst/user_guide/intro_inventory.rst, closes #12480.
* Use code-block and rename groups in inventory setup examples
* Fix group name in inventory setup example

Co-Authored-By: Sandra McCann <samccann@redhat.com>

(cherry picked from commit 7047b66)

* added networking porting guide info (#61999)
* Update docs/docsite/rst/porting_guides/porting_guide_2.9.rst

Co-Authored-By: Nathaniel Case <this.is@nathanielca.se>

(cherry picked from commit 6d35f90)

* [docs] split collections into user and dev guide sections (#62363)

(cherry picked from commit 7badeb6)

* fixed options (#62605)

(cherry picked from commit 170b4e6)

* ec2_vpc_subnet: Rename resource_tags > tags (#62663)

Most of the AWS module documentation refers to `tags` and not
`resource_tags`. This patch updates the documentation to match
other AWS module documentation. 😉

Signed-off-by: Major Hayden <major@redhat.com>
(cherry picked from commit cced1a3)

* [Docs] Document the resource module builder (#62222)

(cherry picked from commit b17581a)

* Fix link syntax and a typo in dev collections doc (#62650)

(cherry picked from commit 2969614)

* hcloud_volume: clarify volume size units (#62771)

(cherry picked from commit 190b8fc)

* ovirt_host update force doc (#62491)

(cherry picked from commit 3b2b418)

* update example document for zabbix_action module (#62667)

(cherry picked from commit 3299f29)
  • Loading branch information
@samccann @acozine
samccann authored and acozine committed Sep 30, 2019
1 parent 633b089 commit 40c40a9
Show file tree
Hide file tree
Showing 17 changed files with 822 additions and 273 deletions.
253 changes: 19 additions & 234 deletions ...st/dev_guide/collections_tech_preview.rst → .../rst/dev_guide/developing_collections.rst
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,14 @@
:orphan:

.. _collections:
.. _developing_collections:

***********
Collections
***********
**********************
Developing collections
**********************


Collections are a distribution format for Ansible content. They can be used to
package and distribute playbooks, roles, modules, and plugins.
Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins.
You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.

.. 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.


.. contents::
:local:
:depth: 2
Expand All @@ -24,7 +17,7 @@ Collection structure
====================

Collections follow a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. A collection does require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy
and other tools need in order to package, build and publish the collection.::
and other tools need in order to package, build and publish the collection::

collection/
├── docs/
Expand Down Expand Up @@ -182,10 +175,6 @@ To create a collection:

A user can then install your collection on their systems.

.. note::
Any references to ``ansible-galaxy`` below will be of a 'working version' that is in development for the 2.9
release. As such, the command and this documentation section is subject to frequent changes.

Currently the ``ansible-galaxy collection`` command implements the following sub commands:

* ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template.
Expand Down Expand Up @@ -302,7 +291,7 @@ Once you upload a version of a collection, you cannot delete or modify that vers
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.

Collection versions use `Sematic Versioning <https://semver.org/>` for version numbers. Please read the official documentation for details and examples. In summary:
Collection versions use `Sematic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:

* Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
* Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner.
Expand All @@ -319,219 +308,15 @@ You can experiment with migrating existing modules into a collection using the `

See the `content_collector README <https://github.com/ansible/content_collector>`_ for full details and usage guidelines.

Installing collections
======================

You can use the ``ansible-galaxy collection install`` command to install a collection on your system. You must specify an installation location using the ``-p`` option.

To install a collection hosted in Galaxy:

.. code-block:: bash
ansible-galaxy collection install my_namespace.my_collection -p /collections
You can also directly use the tarball from your build:

.. code-block:: bash
ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
.. note::
The install command automatically appends the path ``ansible_collections`` to the one specified with the ``-p`` option unless the
parent directory is already in a folder called ``ansible_collections``.


You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will expect to find collections when attempting to use them.

You can also keep a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure.

::

play.yml
├── collections/
│ └── ansible_collections/
│ └── my_namespace/
│ └── my_collection/<collection structure lives here>


Installing an older version of a collection
-------------------------------------------

By default ``ansible-galaxy`` installs the latest collection that is available but you can add a version range
identifier to install a specific version.

To install the 1.0.0 version of the collection:

.. code-block:: bash
ansible-galaxy collection install my_namespace.my_collection:1.0.0
To install the 1.0.0-beta.1 version of the collection:

.. code-block:: bash
ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1
To install the collections that are greater than or equal to 1.0.0 or less than 2.0.0:

.. code-block:: bash
ansible-galaxy collection install my_namespace.my_collection:>=1.0.0,<2.0.0
You can specify multiple range identifiers which are split by ``,``. You can use the following range identifiers:

* ``*``: Any version, this is the default used when no range specified is set.
* ``!=``: Version is not equal to the one specified.
* ``==``: Version must be the one specified.
* ``>=``: Version is greater than or equal to the one specified.
* ``>``: Version is greater than the one specified.
* ``<=``: Version is less than or equal to the one specified.
* ``<``: Version is less than the one specified.

.. note::
The ``ansible-galaxy`` command ignores any pre-release versions unless the ``==`` range identifier is used to
explicitly set to that pre-release version.


.. _collection_requirements_file:

Install multiple collections with a requirements file
-----------------------------------------------------

You can also setup a ``requirements.yml`` file to install multiple collections in one command. This file is a YAML file in the format:

.. code-block:: yaml+jinja

---
collections:
# With just the collection name
- my_namespace.my_collection

# With the collection name, version, and source options
- name: my_namespace.my_other_collection
version: 'version range identifiers (default: ``*``)'
source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'

The ``version`` key can take in the same range identifier format documented above.

Roles can also be specified and placed under the ``roles`` key. The values follow the same format as a requirements
file used in older Ansible releases.

.. note::
While both roles and collections can be specified in one requirements file, they need to be installed separately.
The ``ansible-galaxy role install -r requirements.yml`` will only install roles and
``ansible-galaxy collection install -r requirements.yml -p ./`` will only install collections.

.. _galaxy_server_config:

Galaxy server configuration list
--------------------------------

By default running ``ansible-galaxy`` will use the :ref:`galaxy_server` config value or the ``--server`` command line
argument when it performs an action against a Galaxy server. The ``ansible-galaxy collection install`` supports
installing collections from multiple servers as defined in the :ref:`ansible_configuration_settings_locations` file
using the :ref:`galaxy_server_list` configuration option. To define multiple Galaxy servers you have to create the
following entries like so:

.. code-block:: ini
[galaxy]
server_list = my_org_hub, release_galaxy, test_galaxy
[galaxy_server.my_org_hub]
url=https://automation.my_org/
username=my_user
password=my_pass
[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token
[galaxy_server.test_galaxy]
url=https://galaxy-dev.ansible.com/
token=my_token
.. note::
You can use the ``--server`` command line argument to select an explicit Galaxy server in the ``server_list`` and
the value of this arg should match the name of the server. If the value of ``--server`` is not a pre-defined server
in ``ansible.cfg`` then the value specified will be the URL used to access that server and all pre-defined servers
are ignored. Also the ``--api-key`` argument is not applied to any of the pre-defined servers, it is only applied
if no server list is defined or a URL was specified by ``--server``.


The :ref:`galaxy_server_list` option is a list of server identifiers in a prioritized order. When searching for a
collection, the install process will search in that order, e.g. ``my_org_hub`` first, then ``release_galaxy``, and
finally ``test_galaxy`` until the collection is found. The actual Galaxy instance is then defined under the section
``[galaxy_server.{{ id }}]`` where ``{{ id }}`` is the server identifier defined in the list. This section can then
define the following keys:

* ``url``: The URL of the galaxy instance to connect to, this is required.
* ``token``: A token key to use for authentication against the Galaxy instance, this is mutually exclusive with ``username``
* ``username``: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive with ``token``
* ``password``: The password to use for basic authentication

As well as being defined in the ``ansible.cfg`` file, these server options can be defined as an environment variable.
The environment variable is in the form ``ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}`` where ``{{ id }}`` is the upper
case form of the server identifier and ``{{ key }}`` is the key to define. For example I can define ``token`` for
``release_galaxy`` by setting ``ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token``.

For operations where only one Galaxy server is used, i.e. ``publish``, ``info``, ``login`` then the first entry in the
``server_list`` is used unless an explicit server was passed in as a command line argument.

.. note::
Once a collection is found, any of its requirements are only searched within the same Galaxy instance as the parent
collection. The install process will not search for a collection requirement in a different Galaxy instance.


.. _using_collections:

Using collections
=================

Once installed, you can reference a collection content by its FQCN:

.. code-block:: yaml
- hosts: all
tasks:
- my_namespace.my_collection.mymodule:
option1: value
This works for roles or any type of plugin distributed within the collection:

.. code-block:: yaml
- hosts: all
tasks:
- import_role:
name: my_namespace.my_collection.role1
- my_namespace.mycollection.mymodule:
option1: value
- debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
To avoid a lot of typing, you can use the ``collections`` keyword added in Ansible 2.8:


.. code-block:: yaml
- hosts: all
collections:
- my_namespace.my_collection
tasks:
- import_role:
name: role1
- mymodule:
option1: value
- debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
This keyword creates a 'search path' for non namespaced plugin references. It does not import roles or anything else.
Notice that you still need the FQCN for non-action or module plugins.
.. seealso::

:ref:`collections`
Learn how to install and use collections.
:ref:`collections_galaxy_meta`
Understand the collections metadata structure.
:ref:`developing_modules_general`
Learn about how to write Ansible modules
`Mailing List <https://groups.google.com/group/ansible-devel>`_
The development mailing list
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel
3 changes: 2 additions & 1 deletion docs/docsite/rst/dev_guide/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Find the task that best describes what you want to do:

* I want to :ref:`add a custom plugin or module locally <developing_locally>`.
* I want to figure out if :ref:`developing a module is the right approach <module_dev_should_you>` for my use case.
* I want to :ref:`develop a collection <developing_collections>`.

* I've read the info above, and I'm sure I want to develop a module:

Expand Down Expand Up @@ -81,6 +82,6 @@ If you prefer to read the entire guide, here's a list of the pages in order.
developing_api
developing_rebasing
developing_module_utilities
collections_tech_preview
developing_collections
collections_galaxy_meta
overview_architecture
Loading

0 comments on commit 40c40a9

Please sign in to comment.