* Add description for COLLECTIONS_SCAN_SYS_PATH (#74351)
Fixes: #74275
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 567361b124)
* lighten navigation background to make section labels easier to read for core docs (#74356)
* make section labels for /ansible-core/ docs easier to read, with black text and lighter gray background
(cherry picked from commit 6119fb0a9a)
* Correct splitext() description, and example (#74377)
`splitext()` returns a 2-tuple of strings, and the last element of the return value includes the `.`
(cherry picked from commit c295de661c)
* Using "~" instead of "+" for concatination (#74364)
Changed FAQ examples to conform with the Jinja documentation:
If both values on either side of a plus/+ are numbers, they will be added whereas using "~" will convert all operands into strings and then concatenate them. Closes#73799.
(cherry picked from commit e6a5245d60)
* Docs - Split Developing collections page, add info on optional module_utils (#74105)
*
(cherry picked from commit c90922ee36)
* Add weos4 network platform to documentation (#74088)
* Add weos4 network platform to documentation
* Fix small format issues
(cherry picked from commit 7ca5dede97)
* Fix typo in Makefile (#74396)
Fixed minor typo specfic -> specific
(cherry picked from commit 4880fee6ca)
* Update complex_data_manipulation.rst (#72509)
(cherry picked from commit c2985c491b)
* Update VMware library installation docs (#71219)
Depending upon OS/distro, please use pip/pip3.
(cherry picked from commit ddfc648d37)
* Update AWS dev guides to use collections utils and fragments (#72312)
(cherry picked from commit cf08c23b4f)
* Use is_boto3_error_code in 'standard' example (#72313)
Use is_boto3_error_code in 'standard' example rather than e.response['Error']['Code'] (#72313)
Co-authored-by: Sloane Hertel <shertel@redhat.com>
(cherry picked from commit 63afb33d86)
* Update Kubernetes collection name in docs (#74440)
(cherry picked from commit 8d499bbc83)
* Update argcomplete docs links on installation guide (#74410)
Link on installation docs is outdated. Switch to currently docs at: https://kislyuk.github.io/argcomplete/
(cherry picked from commit f97787ca74)
* fix spacing to fix header, reorg contributing page (#74421)
Co-authored-by: John R Barker <john@johnrbarker.com>
(cherry picked from commit 9d9b08bece)
* Update first_found documentation (#70502)
* import_tasks do not work with loop, use use include_tasks instead
* update documentation
(cherry picked from commit bacede7a2b)
* Product-related updates. (#74454)
(cherry picked from commit 34c9ed8a28)
Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>
Co-authored-by: Alex Willmer <alex@moreati.org.uk>
Co-authored-by: Hublerho <43293510+Hublerho@users.noreply.github.com>
Co-authored-by: Ernst Oudhof <17832702+ernst-s@users.noreply.github.com>
Co-authored-by: Hu Shuai <hus.fnst@cn.fujitsu.com>
Co-authored-by: dhx-mike-palandra <45608336+dhx-mike-palandra@users.noreply.github.com>
Co-authored-by: jakelevinez <31458570+jakelevinez@users.noreply.github.com>
Co-authored-by: Mark Chappell <mchappel@redhat.com>
Co-authored-by: Lidiane Taquehara <lidi.mayra@gmail.com>
Co-authored-by: Alex Domoradov <alex.hha@gmail.com>
Co-authored-by: Bill Nottingham <notting@redhat.com>
Ansible has several mailing lists. Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear.
* `Ansible Announce list <https://groups.google.com/forum/#!forum/ansible-announce>`_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent event information, such as announcements about an upcoming AnsibleFest, which is our official conference series. Worth subscribing to!
* `Ansible AWX List <https://groups.google.com/forum/#!forum/awx-project>`_ is for `Ansible AWX <https://github.com/ansible/awx>`_the upstream version of `Red Hat Ansible Tower <https://www.ansible.com/products/tower>`_
* `Ansible AWX List <https://groups.google.com/forum/#!forum/awx-project>`_ is for `Ansible AWX <https://github.com/ansible/awx>`_
* `Ansible Container List <https://groups.google.com/forum/#!forum/ansible-container>`_ is for users and developers of the Ansible Container project.
* `Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for learning how to develop on Ansible, asking about prospective feature design, or discussions about extending ansible or features in progress.
* `Ansible Lockdown List <https://groups.google.com/forum/#!forum/ansible-lockdown>`_ is for all things related to Ansible Lockdown projects, including DISA STIG automation and CIS Benchmarks.
@ -59,7 +59,7 @@ Many of our community `Working Groups <https://github.com/ansible/community/wiki
- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - ``#ansible-aws``
- `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ | `gh/ansible/ansible-lockdown <https://github.com/ansible/ansible-lockdown>`_ - ``#ansible-lockdown``- Security playbooks/roles
- `AWX Working Group <https://github.com/ansible/awx>`_ - ``#ansible-awx`` - Upstream for Ansible Tower
- `AWX Working Group <https://github.com/ansible/awx>`_ - ``#ansible-awx``
- `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - ``#ansible-azure``
- `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ - ``#ansible-community`` - Including Meetups
- `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - ``#ansible-container``
@ -95,13 +95,13 @@ IRC meetings
The Ansible community holds regular IRC meetings on various topics, and anyone who is interested is invited to
participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
Ansible Tower support questions
===============================
Ansible Automation Platform support questions
=============================================
Red Hat Ansible `Tower <https://www.ansible.com/products/tower>`_ is a UI, Server, and REST endpoint for Ansible.
The Red Hat Ansible Automation subscription contains support for Ansible, Ansible Tower, Ansible Automation for Networking, and more.
Red Hat Ansible `Automation Platform <https://www.ansible.com/products/automation-platform>`_ is a subscription that contains support, certified content, and tooling for Ansible including
content management, a controller, UI and REST API.
If you have a question about Ansible Tower, visit `Red Hat support <https://access.redhat.com/products/ansible-tower-red-hat/>`_ rather than using the IRC channel or the general project mailing list.
If you have a question about Ansible Automation Platform, visit `Red Hat support <https://access.redhat.com/products/red-hat-ansible-automation-platform/>`_ rather than using the IRC channel or the general project mailing list.
- `Ansigenome <https://github.com/nickjj/ansigenome>`_ - a command line tool designed to help you manage your Ansible roles.
- `ARA <https://github.com/openstack/ara>`_ - records Ansible playbook runs and makes the recorded data available and intuitive for users and systems by integrating with Ansible as a callback plugin.
- `Awesome Ansible <https://github.com/jdauphant/awesome-ansible>`_ - a collaboratively curated list of awesome Ansible resources.
- `AWX <https://github.com/ansible/awx>`_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. AWX is the upstream project for Red Hat Ansible Tower, part of the Red Hat Ansible Automation subscription.
- `AWX <https://github.com/ansible/awx>`_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. Red Hat Ansible Automation Platform includes code from AWX.
- `Mitogen for Ansible <https://mitogen.networkgenomics.com/ansible_detailed.html>`_ - uses the `Mitogen <https://github.com/dw/mitogen/>`_ library to execute Ansible playbooks in a more efficient way (decreases the execution time).
- `nanvault <https://github.com/marcobellaccini/nanvault>`_ - a standalone tool to encrypt and decrypt files in the Ansible Vault format, featuring UNIX-style composability.
- `OpsTools-ansible <https://github.com/centos-opstools/opstools-ansible>`_ - uses Ansible to configure an environment that provides the support of `OpsTools <https://wiki.centos.org/SpecialInterestGroup/OpsTools>`_, namely centralized logging and analysis, availability monitoring, and performance monitoring.
Collections are a distribution format for Ansible content. You can package and distribute playbooks, roles, modules, and plugins using collections.
You can publish any collection to `Ansible Galaxy <https://galaxy.ansible.com>`_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform.
* For details on how to *use* collections see :ref:`collections`.
* For the current development status of Collections and FAQ see `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_.
..contents::
:local:
:depth:2
.._collection_structure:
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::
collection/
├── docs/
├── galaxy.yml
├── meta/
│ └── runtime.yml
├── plugins/
│ ├── modules/
│ │ └── module1.py
│ ├── inventory/
│ └── .../
├── README.md
├── roles/
│ ├── role1/
│ ├── role2/
│ └── .../
├── playbooks/
│ ├── files/
│ ├── vars/
│ ├── templates/
│ └── tasks/
└── tests/
..note::
* Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :file:`/docs` folder.
* See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for examples of collection structure.
* Not all directories are currently in use. Those are placeholders for future features.
.._galaxy_yml:
galaxy.yml
----------
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.
.._collections_doc_dir:
docs directory
---------------
Put general documentation for the collection here. Keep the specific documentation for plugins and modules 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. Use markdown and do not add subfolders.
Use ``ansible-doc`` to view documentation for plugins inside a collection:
The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace.
..note:: The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name.
.._collections_plugin_dir:
plugins directory
------------------
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins 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.
Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
.._collection_module_utils:
module_utils
^^^^^^^^^^^^
When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``
The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and
those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``.
In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is
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 in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection.
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 may 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.
.._developing_collections_tests_directory:
tests directory
----------------
Ansible Collections are tested much like Ansible itself, by using the
`ansible-test` utility which is released as part of Ansible, version 2.9.0 and
newer. Because Ansible Collections are tested using the same tooling as Ansible
itself, via `ansible-test`, all Ansible developer documentation for testing is
applicable for authoring Collections Tests with one key concept to keep in mind.
See :ref:`testing_collections` for specific information on how to test collections
with ``ansible-test``.
When reading the :ref:`developing_testing` documentation, there will be content
that applies to running Ansible from source code via a git clone, which is
typical of an Ansible developer. However, it's not always typical for an Ansible
Collection author to be running Ansible from source but instead from a stable
release, and to create Collections it is not necessary to run Ansible from
source. Therefore, when references of dealing with `ansible-test` binary paths,
command completion, or environment variables are presented throughout the
:ref:`developing_testing` documentation; keep in mind that it is not needed for
Ansible Collection Testing because the act of installing the stable release of
Ansible containing `ansible-test` is expected to setup those things for you.
.._meta_runtime_yml:
meta directory
--------------
A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:
- *requires_ansible*:
The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
..code:: yaml
requires_ansible: ">=2.10,<2.11"
..note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
- *plugin_routing*:
Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.
The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.
To define a new location for a plugin, set the ``redirect`` field to another name.
To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date.
..code:: yaml
plugin_routing:
inventory:
kubevirt:
redirect: community.general.kubevirt
my_inventory:
tombstone:
removal_version: "2.0.0"
warning_text: my_inventory has been removed. Please use other_inventory instead.
modules:
my_module:
deprecation:
removal_date: "2021-11-30"
warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
redirect: another.collection.new_module
podman_image:
redirect: containers.podman.podman_image
module_utils:
ec2:
redirect: amazon.aws.ec2
util_dir.subdir.my_util:
redirect: namespace.name.my_util
- *import_redirection*
A mapping of names for Python import statements and their redirected locations.
Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
.._creating_collections:
Creating collections
======================
To create a collection:
#. Create a collection skeleton with the ``collection init`` command. See :ref:`creating_collections_skeleton` above.
#. Add your content to the collection.
#. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<building_collections>`.
#. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publishing_collections>`.
A user can then install your collection on their systems.
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.
* ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
* ``publish``: Publish a built collection artifact to Galaxy.
* ``install``: Install one or more collections.
To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
.._docfragments_collections:
Using documentation fragments in collections
--------------------------------------------
To include documentation fragments in your collection:
#. Create the documentation fragment: ``plugins/doc_fragments/fragment_name``.
#. Refer to the documentation fragment with its FQCN.
..code-block:: yaml
extends_documentation_fragment:
- community.kubernetes.k8s_name_options
- community.kubernetes.k8s_auth_options
- community.kubernetes.k8s_resource_options
- community.kubernetes.k8s_scale_options
:ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes <https://github.com/ansible-collections/kubernetes>`_ collection includes a complete example.
You can also share documentation fragments across collections with the FQCN.
.._building_collections:
Building collections
--------------------
To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
..code-block:: bash
collection_dir#> ansible-galaxy collection build
This creates a tarball of the built collection in the current directory which can be uploaded to Galaxy.::
my_collection/
├── galaxy.yml
├── ...
├── my_namespace-my_collection-1.0.0.tar.gz
└── ...
..note::
* Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections` to exclude other files you would not want to distribute.
* If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
* The current Galaxy maximum tarball size is 2 MB.
This tarball is mainly intended to upload to Galaxy
as a distribution method, but you can use it directly to install the collection on target systems.
.._ignoring_files_and_folders_collections:
Ignoring files and folders
^^^^^^^^^^^^^^^^^^^^^^^^^^
By default the build step will include all the files in the collection directory in the final build artifact except for the following:
* ``galaxy.yml``
* ``*.pyc``
* ``*.retry``
* ``tests/output``
* previously built artifacts in the root directory
* various version control directories like ``.git/``
To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the
``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for
wildcard matching:
* ``*``: Matches everything
* ``?``: Matches any single character
* ``[seq]``: Matches and character in seq
* ``[!seq]``:Matches any character not in seq
For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you
can set the following in your ``galaxy.yml`` file:
..code-block:: yaml
build_ignore:
- playbooks/sensitive
- '*.tar.gz'
..note::
This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
.._trying_collection_locally:
Trying collections locally
--------------------------
You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to
You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
Prerequisites
-------------
1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
2. Get an API token for each distribution server you want to use.
3. Specify your API token(s).
Getting a namespace
^^^^^^^^^^^^^^^^^^^
You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
* For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
* For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
.._galaxy_get_token:
Getting your API token
^^^^^^^^^^^^^^^^^^^^^^
You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
To get your API token:
* For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
* For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
Specifying your API token
^^^^^^^^^^^^^^^^^^^^^^^^^
Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
* Pass the token to the ``ansible-galaxy`` command using the ``--token``.
* Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
Specifying your API token with the ``--token`` argument
You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
..code-block:: ini
[galaxy]
server_list = release_galaxy
[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token
See :ref:`galaxy_server_config` for complete details.
Publishing a collection
-----------------------
Once you have a namespace and an API token for each distribution server you want to use, you can distribute your collection by publishing it to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
Each time you add features or make changes to your collection, you must publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
.._upload_collection_ansible_galaxy:
Publish a collection using ``ansible-galaxy``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
..note::
By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
To upload the collection artifact with the ``ansible-galaxy`` command:
The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
.._upload_collection_galaxy:
Publishing a collection using the Galaxy website
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To publish your collection directly on the Galaxy website:
#. 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 the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, 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.
.._collection_versions:
Collection versions
^^^^^^^^^^^^^^^^^^^
Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. 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 or Automation Hub; however, users will still be able to download older versions.
Collection versions use `Semantic 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 (for example new modules/plugins, parameters, return values).
* Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
.._migrate_to_collection:
Migrating Ansible content to a different collection
First, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
#. Copy content from the source (old) collection to the target (new) collection.
#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection.
#. When the next major release of the old collection is prepared:
* remove the module/plugin from the old collection
* remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)
* remove related unit and integration tests
* remove specific module utils
* remove specific documentation fragments if there are any in the old collection
* add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_
* change ``meta/runtime.yml`` in the old collection:
* add ``redirect`` to the corresponding module/plugin's entry
* in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable
* remove ``removal_version`` from there
* remove related entries from ``tests/sanity/ignore.txt`` files if exist
* remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)
* remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml``
According to the above, you need to create at least three PRs as follows:
#. Create a PR against the new collection to copy the content.
#. Deprecate the module/plugin in the old collection.
#. Later create a PR against the old collection to remove the content according to the schedule.
Adding the content to the new collection
----------------------------------------
Create a PR in the new collection to:
#. Copy ALL the related files from the old collection.
#. If it is an action plugin, include the corresponding module with documentation.
#. If it is a module, check if it has a corresponding action plugin that should move with it.
#. Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
#. Update ``meta/runtime.yml`` in the old collection.
Removing the content from the old collection
--------------------------------------------
Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
#. If you are removing a module, remove any corresponding action plugin that should stay with it.
#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
..warning::
Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
BOTMETA.yml
-----------
The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
* ansibullbot
If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
Ansibulbot will know how to redirect existing issues and PRs to the new repo.
The build process for docs.ansible.com will know where to find the module docs.
* The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs.
* ``migrated_to:`` MUST be added for every:
* module
* plugin
* module_utils
* contrib/inventory script
* You do NOT need to add ``migrated_to`` for:
* Unit tests
* Integration tests
* ReStructured Text docs (anything under ``docs/docsite/rst/``)
* Files that never existed in ``ansible/ansible:devel``
.._testing_collections:
Testing collections
===================
The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Shippable both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
Compile and sanity tests
------------------------
To run all compile and sanity tests::
ansible-test sanity --docker default -v
See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues.
Unit tests
----------
You must place unit tests in the appropriate``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
To run all unit tests for all supported Python versions::
ansible-test units --docker default -v
To run all unit tests only for a specific Python version::
ansible-test units --docker default -v --python 3.6
To run only a specific unit test::
ansible-test units --docker default -v --python 3.6 tests/unit/plugins/module_utils/foo/test_bar.py
You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files.
Integration tests
-----------------
You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on.
You can write two different kinds of integration tests:
* Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services.
* ``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings.
For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details.
Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
To execute all integration tests for a collection::
ansible-test integration --docker centos8 -v
If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
To execute only the integration tests in a specific directory::
You can specify multiple target names. Each target name is the name of a directory in ``tests/integration/targets/``.
.._hacking_collections:
Contributing to collections
===========================
If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``).
This section describes the process for `community.general <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection.
We assume that you have included ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`, and if that path mentions multiple directories, that you made sure that no other directory earlier in the search path contains a copy of ``community.general``. Create the directory ``~/dev/ansible/collections/ansible_collections/community``, and in it clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the folder ``general``::
Now you can use this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch.
For collections hosted in the ``ansible_collections`` GitHub org, create a branch and commit your changes on the branch. When you are done (remember to add tests, see :ref:`testing_collections`), push your changes to your fork of the collection and create a Pull Request. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
.._collection_changelogs:
Generating changelogs for a collection
======================================
We recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs for your collection. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
..note::
Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
Understanding antsibull-changelog
---------------------------------
The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
..note::
The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
#. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
To generate changelogs from the changelog fragments you created:
#. Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
#. Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
..note::
Add the ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
Porting Guide entries
----------------------
The following changelog fragment categories are consumed by the Ansible changelog generator into the Ansible Porting Guide:
* ``major_changes``
* ``breaking_changes``
* ``deprecated_features``
* ``removed_features``
Collections are a distribution format for Ansible content. You can package and distribute playbooks, roles, modules, and plugins using collections. A typical collection addresses a set of related use cases. For example, the ``cisco.ios`` collection automates management of Cisco IOS devices.
Including collection changelogs into Ansible
=============================================
You can create a collection and publish it to `Ansible Galaxy <https://galaxy.ansible.com>`_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform.
..toctree::
:maxdepth:2
:caption:Developing new collections
If your collection is part of Ansible, use one of the following three options to include your changelog into the Ansible release changelog:
developing_collections_creating
developing_collections_shared
developing_collections_testing
developing_collections_distributing
* Use the ``antsibull-changelog`` tool.
..toctree::
:maxdepth:2
:caption:Working with existing collections
* If are not using this tool, include the properly formatted ``changelog.yaml`` file into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
developing_collections_migrating
developing_collections_contributing
developing_collections_changelogs
* Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
..toctree::
:maxdepth:2
:caption:Collections references
..note::
developing_collections_structure
collections_galaxy_meta
For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
For instructions on developing modules, see :ref:`developing_modules_general`.
..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
Learn how to install and use collections in playbooks and roles
:ref:`contributing_maintained_collections`
Guidelines for contributing to selected collections
`Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_
Current development status of community collections and FAQ
`Mailing List <https://groups.google.com/group/ansible-devel>`_
You can create and share changelog and porting guide entries for your collection. If your collection is part of the Ansible Community package, we recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
..note::
Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
..contents::
:local:
:depth:2
Understanding antsibull-changelog
=================================
The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
..note::
The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
#. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
To generate changelogs from the changelog fragments you created:
#. Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
#. Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
..note::
Add the ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
Porting Guide entries from changelog fragments
----------------------------------------------
The Ansible changelog generator automatically adds several changelog fragment categories to the Ansible Porting Guide:
* ``major_changes``
* ``breaking_changes``
* ``deprecated_features``
* ``removed_features``
Including collection changelogs into Ansible
=============================================
If your collection is part of Ansible, use one of the following three options to include your changelog into the Ansible release changelog:
* Use the ``antsibull-changelog`` tool.
* If are not using this tool, include the properly formatted ``changelog.yaml`` file into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
* Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
..note::
For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
..seealso::
:ref:`collections`
Learn how to install and use collections.
:ref:`contributing_maintained_collections`
Guidelines for contributing to selected collections
`Mailing List <https://groups.google.com/group/ansible-devel>`_
If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``).
You should first check the collection repository to see if it has specific contribution guidelines. These are typically listed in the README.md or CONTRIBUTING.md files within the repository.
Contributing to a collection: community.general
===============================================
These instructions apply to collections hosted in the `ansible_collections GitHub org <https://github.com/ansible-collections>`_. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
This example uses the `community.general collection <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections in the same GitHub org, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection.
Prerequisites
-------------
* Include ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`
* If that path mentions multiple directories, make sure that no other directory earlier in the search path contains a copy of ``community.general``.
Creating a PR
-------------
* Create the directory ``~/dev/ansible/collections/ansible_collections/community``::
* Clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the directory ``general``::
cd ~/dev/ansible/collections/ansible_collections/community
git clone git@github.com:ansible-collections/community.general.git general
* If you clone from a fork, add the original repository as a remote ``upstream``::
cd ~/dev/ansible/collections/ansible_collections/community/general
* Create a branch and commit your changes on the branch.
* Remember to add tests for your changes, see :ref:`testing_collections`.
* Push your changes to your fork of the collection and create a Pull Request.
You can test your changes by using this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch.
..seealso::
:ref:`collections`
Learn how to install and use collections.
:ref:`contributing_maintained_collections`
Guidelines for contributing to selected collections
`Mailing List <https://groups.google.com/group/ansible-devel>`_
Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
Reference: the ``ansible-galaxy collection`` command
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.
* ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
* ``publish``: Publish a built collection artifact to Galaxy.
* ``install``: Install one or more collections.
To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
..seealso::
:ref:`collections`
Learn how to install and use collections.
:ref:`collection_structure`
Directories and files included in the collection skeleton
`Mailing List <https://groups.google.com/group/ansible-devel>`_
You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
Distributing collections involves three major steps:
#. Configuring your distribution server(s)
#. Building your collection artifact
#. Publishing your collection
..contents::
:local:
:depth:2
Configuring your distribution server or servers
================================================
1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
2. Get an API token for each distribution server you want to use.
3. Specify the API token for each distribution server you want to use.
Getting a namespace
-------------------
You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
* For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
* For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
.._galaxy_get_token:
Getting your API token
----------------------
You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
To get your API token:
* For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
* For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
Specifying your API token
-------------------------
Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
* Pass the token to the ``ansible-galaxy`` command using the ``--token``.
* Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
Specifying your API token with the ``--token`` argument
You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
..code-block:: ini
[galaxy]
server_list = release_galaxy
[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com/
token=my_token
See :ref:`galaxy_server_config` for complete details.
.._building_collections:
Building a collection tarball
=============================
Once you have configured one or more distribution servers, you must build a collection tarball. To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
..code-block:: bash
collection_dir#> ansible-galaxy collection build
This creates a tarball of the built collection in the current directory which can be uploaded to your distribution server::
my_collection/
├── galaxy.yml
├── ...
├── my_namespace-my_collection-1.0.0.tar.gz
└── ...
..note::
* Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections` to exclude other files you would not want to distribute.
* If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
* The current Galaxy maximum tarball size is 2 MB.
This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems.
.._ignoring_files_and_folders_collections:
Ignoring files and folders
--------------------------
By default the build step will include all the files in the collection directory in the final build artifact except for the following:
* ``galaxy.yml``
* ``*.pyc``
* ``*.retry``
* ``tests/output``
* previously built artifacts in the root directory
* various version control directories like ``.git/``
To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the
``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for
wildcard matching:
* ``*``: Matches everything
* ``?``: Matches any single character
* ``[seq]``: Matches and character in seq
* ``[!seq]``:Matches any character not in seq
For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you
can set the following in your ``galaxy.yml`` file:
..code-block:: yaml
build_ignore:
- playbooks/sensitive
- '*.tar.gz'
..note::
This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
.._collection_versions:
Collection versions
===================
Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. 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 or Automation Hub; however, users will still be able to download older versions.
Collection versions use `Semantic 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 (for example new modules/plugins, parameters, return values).
* Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
.._trying_collection_locally:
Trying collections locally
==========================
Before you publish your collection, test it out locally. Every time you publish a tarball, you create a :ref:`new version <collection_versions>` of your collection. Testing the collection locally gives you confidence that the new version will contain the functionality you want without unexpected behavior.
Trying your collection from the tarball
---------------------------------------
You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:
Once you have a namespace and an API token for each distribution server you want to use, and you have created and tested a collection tarball, you can distribute your collection by publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
Each time you add features or make changes to your collection, you must create a new collection artifact and publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
.._upload_collection_ansible_galaxy:
Publish a collection using ``ansible-galaxy``
---------------------------------------------
..note::
By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
To upload the collection artifact with the ``ansible-galaxy`` command:
The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
.._upload_collection_galaxy:
Publishing a collection using the Galaxy website
------------------------------------------------
To publish your collection directly on the Galaxy website:
#. 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 the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, 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.
..seealso::
:ref:`collections`
Learn how to install and use collections.
`Mailing List <https://groups.google.com/group/ansible-devel>`_
When you move content from one collection to another, for example to extract a set of related modules out of ``community.general`` to create a more focused collection, you must make sure the transition is easy for users to follow.
..contents::
:local:
:depth:2
Migrating content
=================
Before you start migrating content from one collection to another, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
#. Copy content from the source (old) collection to the target (new) collection.
#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection.
#. When the next major release of the old collection is prepared:
* remove the module/plugin from the old collection
* remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)
* remove related unit and integration tests
* remove specific module utils
* remove specific documentation fragments if there are any in the old collection
* add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_
* change ``meta/runtime.yml`` in the old collection:
* add ``redirect`` to the corresponding module/plugin's entry
* in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable
* remove ``removal_version`` from there
* remove related entries from ``tests/sanity/ignore.txt`` files if exist
* remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)
* remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml``
To implement these changes, you need to create at least three PRs:
#. Create a PR against the new collection to copy the content.
#. Deprecate the module/plugin in the old collection.
#. Later create a PR against the old collection to remove the content according to the schedule.
Adding the content to the new collection
----------------------------------------
Create a PR in the new collection to:
#. Copy ALL the related files from the old collection.
#. If it is an action plugin, include the corresponding module with documentation.
#. If it is a module, check if it has a corresponding action plugin that should move with it.
#. Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
#. Update ``meta/runtime.yml`` in the old collection.
Removing the content from the old collection
--------------------------------------------
Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
#. If you are removing a module, remove any corresponding action plugin that should stay with it.
#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
..warning::
Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
Updating BOTMETA.yml
--------------------
The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
* ansibullbot
If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build process for docs.ansible.com will know where to find the module docs.
* The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs.
* ``migrated_to:`` MUST be added for every:
* module
* plugin
* module_utils
* contrib/inventory script
* You do NOT need to add ``migrated_to`` for:
* Unit tests
* Integration tests
* ReStructured Text docs (anything under ``docs/docsite/rst/``)
* Files that never existed in ``ansible/ansible:devel``
..seealso::
:ref:`collections`
Learn how to install and use collections.
:ref:`contributing_maintained_collections`
Guidelines for contributing to selected collections
`Mailing List <https://groups.google.com/group/ansible-devel>`_
Although developing Ansible modules contained in collections is similar to developing standalone Ansible modules, you use shared resources like documentation fragments and module utilities differently in collections. You can use documentation fragments within and across collections. You can use optional module utilities to support multiple versions of ansible-core in your collection.
..contents::
:local:
:depth:2
.._docfragments_collections:
Using documentation fragments in collections
============================================
To include documentation fragments in your collection:
#. Create the documentation fragment: ``plugins/doc_fragments/fragment_name``.
#. Refer to the documentation fragment with its FQCN.
..code-block:: yaml
extends_documentation_fragment:
- kubernetes.core.k8s_name_options
- kubernetes.core.k8s_auth_options
- kubernetes.core.k8s_resource_options
- kubernetes.core.k8s_scale_options
:ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes.core <https://github.com/ansible-collections/kubernetes.core>`_ collection includes a complete example.
If you use FQCN, you can use documentation fragments from one collection in another collection.
.._optional_module_utils:
Leveraging optional module utilities in collections
Optional module utilities let you adopt the latest features from the most recent ansible-core release in your collection-based modules without breaking your collection on older Ansible versions. With optional module utilities, you can leverage the latest features when running against the latest versions, while still providing fallback behaviors when running against older versions.
This implementation, widely used in Python programming, wraps optional imports in conditionals or defensive `try/except` blocks, and implements fallback behaviors for missing imports. Ansible's module payload builder supports these patterns by treating any module_utils import nested in a block (e.g., `if`, `try`) as optional. If the requested import cannot be found during the payload build, it is simply omitted from the target payload and assumed that the importing code will handle its absence at runtime. Missing top-level imports of module_utils packages (imports that are not wrapped in a block statement of any kind) will fail the module payload build, and will not execute on the target.
For example, the `ansible.module_utils.common.respawn` package is only available in Ansible 2.11 and higher. The following module code would fail during the payload build on Ansible 2.10 or earlier (as the requested Python module does not exist, and is not wrapped in a block to signal to the payload builder that it can be omitted from the module payload):
..code-block:: python
from ansible.module_utils.common.respawn import respawn_module
By wrapping the import statement in a ``try`` block, the payload builder will omit the Python module if it cannot be located, and assume that the Ansible module will handle it at runtime:
..code-block:: python
try:
from ansible.module_utils.common.respawn import respawn_module
except ImportError:
respawn_module = None
...
if needs_respawn:
if respawn_module:
respawn_module(target)
else:
module.fail_json('respawn is not available in Ansible < 2.11, ensure that foopkg is installed')
The optional import behavior also applies to module_utils imported from collections.
..seealso::
:ref:`collections`
Learn how to install and use collections.
:ref:`contributing_maintained_collections`
Guidelines for contributing to selected collections
`Mailing List <https://groups.google.com/group/ansible-devel>`_
A collection is 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.
..contents::
:local:
:depth:2
Collection directories and files
================================
A collection can contain these directories and files::
collection/
├── docs/
├── galaxy.yml
├── meta/
│ └── runtime.yml
├── plugins/
│ ├── modules/
│ │ └── module1.py
│ ├── inventory/
│ └── .../
├── README.md
├── roles/
│ ├── role1/
│ ├── role2/
│ └── .../
├── playbooks/
│ ├── files/
│ ├── vars/
│ ├── templates/
│ └── tasks/
└── tests/
..note::
* Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :file:`/docs` folder.
* See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for examples of collection structure.
* Not all directories are currently in use. Those are placeholders for future features.
.._galaxy_yml:
galaxy.yml
----------
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.
.._collections_doc_dir:
docs directory
---------------
Put general documentation for the collection here. Keep the specific documentation for plugins and modules 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. Use markdown and do not add subfolders.
Use ``ansible-doc`` to view documentation for plugins inside a collection:
The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace.
..note:: The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name.
.._collections_plugin_dir:
plugins directory
-----------------
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins 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.
Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
.._collection_module_utils:
module_utils
^^^^^^^^^^^^
When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``
The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and
those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``.
In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is
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 in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection.
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 may 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.
.._developing_collections_tests_directory:
tests directory
----------------
Ansible Collections are tested much like Ansible itself, by using the `ansible-test` utility which is released as part of Ansible, version 2.9.0 and newer. Because Ansible Collections are tested using the same tooling as Ansible itself, via `ansible-test`, all Ansible developer documentation for testing is applicable for authoring Collections Tests with one key concept to keep in mind.
See :ref:`testing_collections` for specific information on how to test collections with ``ansible-test``.
When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code via a git clone, which is typical of an Ansible developer. However, it's not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you.
.._meta_runtime_yml:
meta directory
--------------
A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:
- *requires_ansible*:
The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
..code:: yaml
requires_ansible: ">=2.10,<2.11"
..note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
- *plugin_routing*:
Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.
The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.
To define a new location for a plugin, set the ``redirect`` field to another name.
To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date.
..code:: yaml
plugin_routing:
inventory:
kubevirt:
redirect: community.general.kubevirt
my_inventory:
tombstone:
removal_version: "2.0.0"
warning_text: my_inventory has been removed. Please use other_inventory instead.
modules:
my_module:
deprecation:
removal_date: "2021-11-30"
warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
redirect: another.collection.new_module
podman_image:
redirect: containers.podman.podman_image
module_utils:
ec2:
redirect: amazon.aws.ec2
util_dir.subdir.my_util:
redirect: namespace.name.my_util
- *import_redirection*
A mapping of names for Python import statements and their redirected locations.
Testing your collection ensures that your code works well and integrates well with the rest of the Ansible ecosystem. Your collection should pass the general compile and sanity tests for Ansible code. You should also add unit tests to cover the code in your collection and integration tests to cover the interactions between your collection and ansible-core.
..contents::
:local:
:depth:2
Testing tools
=============
The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Shippable both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
Compile and sanity tests
------------------------
To run all compile and sanity tests::
ansible-test sanity --docker default -v
See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues.
Adding unit tests
-----------------
You must place unit tests in the appropriate``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
To run all unit tests for all supported Python versions::
ansible-test units --docker default -v
To run all unit tests only for a specific Python version::
ansible-test units --docker default -v --python 3.6
To run only a specific unit test::
ansible-test units --docker default -v --python 3.6 tests/unit/plugins/module_utils/foo/test_bar.py
You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files.
Adding integration tests
------------------------
You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on.
You can write two different kinds of integration tests:
* Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services.
* ``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings.
For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details.
Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
To execute all integration tests for a collection::
ansible-test integration --docker centos8 -v
If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
To execute only the integration tests in a specific directory::
@ -233,8 +233,8 @@ Linking and other format macros within module documentation
You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:
* ``L()`` for links with a heading. For example: ``See L(Ansible Tower,https://www.ansible.com/products/tower).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/tower) for an overview.``
* ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``. Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
@ -255,7 +255,7 @@ content in a uniform way:
..note::
- To refer to a group of modules in a collection, use ``R()``. When a collection is not the right granularity, use ``C(..)``:
- ``Refer to the R(community.kubernetes collection, plugins_in_community.kubernetes) for information on managing kubernetes clusters.``
- ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
- ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
@ -268,7 +268,7 @@ content in a uniform way:
Documentation fragments
-----------------------
If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``community.kubernetes.k8s_auth_options``).
If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``kubernetes.core.k8s_auth_options``).
Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment.
from ansible.module_utils.aws.core import AnsibleAWSModule
from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
...
module = AnsibleAWSModule(...)
@ -118,7 +118,8 @@ Unless the name of your service is quite unique, please consider using ``aws_``
Importing botocore and boto3
----------------------------
The ``ansible.module_utils.ec2`` module and ``ansible.module_utils.core.aws`` modules both
The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and
``ansible_collections.amazon.aws.plugins.module_utils.core`` modules both
automatically import boto3 and botocore. If boto3 is missing from the system then the variable
``HAS_BOTO3`` will be set to false. Normally, this means that modules don't need to import
boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule
@ -126,7 +127,7 @@ as the module does that check:
..code-block:: python
from ansible.module_utils.aws.core import AnsibleAWSModule
from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
try:
import botocore
except ImportError:
@ -137,7 +138,7 @@ or:
..code-block:: python
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.ec2 import HAS_BOTO3
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import HAS_BOTO3
try:
import botocore
except ImportError:
@ -220,8 +221,8 @@ and that the more esoteric connection options are documented. For example:
# some lines omitted here
requirements: [ 'botocore', 'boto3' ]
extends_documentation_fragment:
- aws
- ec2
- amazon.aws.aws
- amazon.aws.ec2
'''
Handling exceptions
@ -234,7 +235,7 @@ are a number of possibilities for handling it.
``is_boto3_error_code``.
* Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way
* Retry using AWSRetry
* Use ``fail_json()`` to report the failure without using ``ansible.module_utils.aws.core``
* Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plugins.module_utils.core``
* Do something custom in the case where you know how to handle the exception
For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_.
@ -242,7 +243,7 @@ For more information on botocore exception handling see the `botocore error docu
Using is_boto3_error_code
-------------------------
To use ``ansible.module_utils.aws.core.is_boto3_error_code`` to catch a single
To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to catch a single
AWS error code, call it in place of ``ClientError`` in your except clauses. In
this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here,
and any other error will be raised for handling elsewhere in the program.
@ -268,7 +269,7 @@ amounts of exception handling to existing modules, we recommend migrating the mo
..code-block:: python
from ansible.module_utils.aws.core import AnsibleAWSModule
from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
# Set up module parameters
# module params code here
@ -286,7 +287,8 @@ amounts of exception handling to existing modules, we recommend migrating the mo
Note that it should normally be acceptable to catch all normal exceptions here, however if you
expect anything other than botocore exceptions you should test everything works as expected.
If you need to perform an action based on the error boto3 returned, use the error code.
If you need to perform an action based on the error boto3 returned, use the error code and the
``is_boto3_error_code()`` helper.
..code-block:: python
@ -294,16 +296,13 @@ If you need to perform an action based on the error boto3 returned, use the erro
name = module.params.get['name']
try:
result = connection.describe_frooble(FroobleName=name)
except botocore.exceptions.ClientError as e:
if e.response['Error']['Code'] == 'FroobleNotFound':
workaround_failure() # This is an error that we can work around
@ -12,7 +12,7 @@ Spell out the acronym before using it in alone text, such as "The Embedded DevKi
Applications
+++++++++++++++++++
When used as a proper name, use the capitalization of the product, such as GNUPro, Source-Navigator, and Ansible Tower. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
When used as a proper name, use the capitalization of the product, such as GNUPro or Source-Navigator. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
@ -575,7 +575,7 @@ As of Ansible 2.9, you can add shell completion of the Ansible command line util
You can install ``python-argcomplete`` from EPEL on Red Hat Enterprise based distributions, and or from the standard OS repositories for many other distributions.
For more information about installation and configuration, see the `argcomplete documentation <https://argcomplete.readthedocs.io/en/latest/>`_.
For more information about installation and configuration, see the `argcomplete documentation <https://kislyuk.github.io/argcomplete/>`_.
Installing ``argcomplete`` on RHEL, CentOS, or Fedora
- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration.
- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
@ -45,6 +45,6 @@ To disable SSL certificate verification, set ``verify_ssl`` to false.
Reporting an issue
==================
If you find a bug or have a suggestion regarding modules, please file issues at `Ansible Kubernetes collection <https://github.com/ansible-collections/community.kubernetes>`_.
If you find a bug or have a suggestion regarding modules, please file issues at `Ansible Kubernetes collection <https://github.com/ansible-collections/kubernetes.core>`_.
If you find a bug regarding OpenShift client, please file issues at `OpenShift REST Client issues <https://github.com/openshift/openshift-restclient-python/issues>`_.
If you find a bug regarding Kubectl binary, please file issues at `Kubectl issue tracker <https://github.com/kubernetes/kubectl>`_
@ -52,7 +52,7 @@ Since Ansible utilizes the Kubernetes API to perform actions, in this use case w
To begin, there are a few bits of information we will need. Here you are using Kubeconfig which is pre-configured in your machine. The Kubeconfig is generally located at ``~/.kube/config``. It is highly recommended to store sensitive information such as password, user certificates in a more secure fashion using :ref:`ansible-vault` or using `Ansible Tower credentials <https://docs.ansible.com/ansible-tower/latest/html/userguide/credentials.html>`_.
Now you need to supply the information about the Pod which will be created. Using ``definition`` parameter of the ``community.kubernetes.k8s`` module, you specify `PodTemplate <https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates>`_. This PodTemplate is identical to what you provide to the ``kubectl`` command.
Now you need to supply the information about the Pod which will be created. Using ``definition`` parameter of the ``kubernetes.core.k8s`` module, you specify `PodTemplate <https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates>`_. This PodTemplate is identical to what you provide to the ``kubectl`` command.
These filters have migrated to the `community.kubernetes <https://galaxy.ansible.com/community/kubernetes>`_ collection. Follow the installation instructions to install that collection.
These filters have migrated to the `kuberernetes.core<https://galaxy.ansible.com/kubernetes/core>`_ collection. Follow the installation instructions to install that collection.
Use the "k8s_config_resource_name" filter to obtain the name of a Kubernetes ConfigMap or Secret,
Alicia Cozine
4 years ago
committed by