mirror of https://github.com/ansible/ansible.git
Move galaxy appendix info to a new Galaxy section (#63356)
* start galaxy docs restructure * shared snippets in txt files * moved all content to galaxy sectionpull/63394/head
Sandra McCann
5 years ago
committed by
Alicia Cozine
parent
504d76e956
commit
ae265bc546
@ -0,0 +1,11 @@
|
||||
.. _creating_collections_galaxy:
|
||||
|
||||
*******************************
|
||||
Creating collections for Galaxy
|
||||
*******************************
|
||||
|
||||
|
||||
Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins.
|
||||
You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
|
||||
|
||||
See :ref:`developing_collections` for details on how to create collections.
|
||||
@ -0,0 +1,222 @@
|
||||
.. _creating_roles_galaxy:
|
||||
|
||||
*************************
|
||||
Creating roles for Galaxy
|
||||
*************************
|
||||
|
||||
Use the ``init`` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy init role_name
|
||||
|
||||
The above will create the following directory structure in the current working directory:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
role_name/
|
||||
README.md
|
||||
.travis.yml
|
||||
defaults/
|
||||
main.yml
|
||||
files/
|
||||
handlers/
|
||||
main.yml
|
||||
meta/
|
||||
main.yml
|
||||
templates/
|
||||
tests/
|
||||
inventory
|
||||
test.yml
|
||||
vars/
|
||||
main.yml
|
||||
|
||||
If you want to create a repository for the role the repository root should be `role_name`.
|
||||
|
||||
Force
|
||||
=====
|
||||
|
||||
If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error
|
||||
use the *--force* option. Force will create the above subdirectories and files, replacing anything that matches.
|
||||
|
||||
Container Enabled
|
||||
=================
|
||||
|
||||
If you are creating a Container Enabled role, pass ``--type container`` to ``ansible-galaxy init``. This will create the same directory structure as above, but populate it
|
||||
with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests
|
||||
the role using `Ansible Container <https://github.com/ansible/ansible-container>`_, and the meta directory includes a *container.yml* file.
|
||||
|
||||
Using a Custom Role Skeleton
|
||||
============================
|
||||
|
||||
A custom role skeleton directory can be supplied as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name
|
||||
|
||||
When a skeleton is provided, init will:
|
||||
|
||||
- copy all files and directories from the skeleton to the new role
|
||||
- any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role_name
|
||||
- The .git folder and any .git_keep files will not be copied
|
||||
|
||||
Alternatively, the role_skeleton and ignoring of files can be configured via ansible.cfg
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
[galaxy]
|
||||
role_skeleton = /path/to/skeleton
|
||||
role_skeleton_ignore = ^.git$,^.*/.git_keep$
|
||||
|
||||
Authenticate with Galaxy
|
||||
========================
|
||||
|
||||
Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
|
||||
can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
|
||||
|
||||
The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
|
||||
|
||||
The following shows authenticating with the Galaxy website using a GitHub username and password:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
$ ansible-galaxy login
|
||||
|
||||
We need your GitHub login to identify you.
|
||||
This information will not be sent to Galaxy, only to api.github.com.
|
||||
The password will not be displayed.
|
||||
|
||||
Use --github-token if you do not want to enter your password.
|
||||
|
||||
GitHub Username: dsmith
|
||||
Password for dsmith:
|
||||
Successfully logged into Galaxy as dsmith
|
||||
|
||||
When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
|
||||
It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
|
||||
destroyed.
|
||||
|
||||
If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token that you create.
|
||||
|
||||
|
||||
Import a role
|
||||
=============
|
||||
|
||||
The ``import`` command requires that you first authenticate using the ``login`` command. Once authenticated you can import any GitHub repository that you own or have been granted access.
|
||||
|
||||
Use the following to import to role:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy import github_user github_repo
|
||||
|
||||
By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Successfully submitted import request 41
|
||||
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
|
||||
Retrieving GitHub repo githubuser/ansible-role-repo
|
||||
Accessing branch: master
|
||||
Parsing and validating meta/main.yml
|
||||
Parsing galaxy_tags
|
||||
Parsing platforms
|
||||
Adding dependencies
|
||||
Parsing and validating README.md
|
||||
Adding repo tags as role versions
|
||||
Import completed
|
||||
Status SUCCESS : warnings=0 errors=0
|
||||
|
||||
Branch
|
||||
------
|
||||
|
||||
Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used.
|
||||
|
||||
Role name
|
||||
---------
|
||||
|
||||
By default the name given to the role will be derived from the GitHub repository name. However, you can use the *--role-name* option to override this and set the name.
|
||||
|
||||
No wait
|
||||
-------
|
||||
|
||||
If the *--no-wait* option is present, the command will not wait for results. Results of the most recent import for any of your roles is available on the Galaxy web site by visiting *My Imports*.
|
||||
|
||||
Delete a role
|
||||
=============
|
||||
|
||||
The ``delete`` command requires that you first authenticate using the ``login`` command. Once authenticated you can remove a role from the Galaxy web site. You are only allowed to remove roles where you have access to the repository in GitHub.
|
||||
|
||||
Use the following to delete a role:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy delete github_user github_repo
|
||||
|
||||
This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.
|
||||
|
||||
|
||||
Travis integrations
|
||||
===================
|
||||
|
||||
You can create an integration or connection between a role in Galaxy and `Travis <https://travis-ci.org>`_. Once the connection is established, a build in Travis will
|
||||
automatically trigger an import in Galaxy, updating the search index with the latest information about the role.
|
||||
|
||||
You create the integration using the ``setup`` command, but before an integration can be created, you must first authenticate using the ``login`` command; you will
|
||||
also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
|
||||
|
||||
The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described
|
||||
in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The hash is stored in Galaxy and used to verify notifications received from Travis.
|
||||
|
||||
The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the
|
||||
`Travis getting started guide <https://docs.travis-ci.com/user/getting-started/>`_.
|
||||
|
||||
To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
notifications:
|
||||
webhooks: https://galaxy.ansible.com/api/v1/notifications/
|
||||
|
||||
|
||||
List Travis integrations
|
||||
------------------------
|
||||
|
||||
Use the *--list* option to display your Travis integrations:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy setup --list
|
||||
|
||||
|
||||
ID Source Repo
|
||||
---------- ---------- ----------
|
||||
2 travis github_user/github_repo
|
||||
1 travis github_user/github_repo
|
||||
|
||||
|
||||
Remove Travis integrations
|
||||
---------------------------
|
||||
|
||||
Use the *--remove* option to disable and remove a Travis integration:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy setup --remove ID
|
||||
|
||||
Provide the ID of the integration to be disabled. You can find the ID by using the *--list* option.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`playbooks_reuse_roles`
|
||||
All about ansible roles
|
||||
`Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
@ -0,0 +1,20 @@
|
||||
.. _developing_galaxy:
|
||||
|
||||
***************
|
||||
Developer Guide
|
||||
***************
|
||||
|
||||
You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formated in pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_.
|
||||
You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
creating_collections
|
||||
creating_roles
|
||||
|
||||
.. seealso::
|
||||
`collections <collections>`_
|
||||
Sharable collections of modules, playbooks and roles
|
||||
`roles <playbooks_reuse_roles>`_
|
||||
Reusable tasks, handlers, and other files in a known directory structure
|
||||
@ -0,0 +1,14 @@
|
||||
|
||||
.. _finding_galaxy_collections:
|
||||
|
||||
*****************************
|
||||
Finding collections on Galaxy
|
||||
*****************************
|
||||
|
||||
To find collections on Galaxy:
|
||||
|
||||
#. Click the :guilabel:`Search` icon in the left-hand navigation.
|
||||
#. Set the filter to *collection*.
|
||||
#. Set other filters and press enter.
|
||||
|
||||
Galaxy presents a list of collections that match your search criteria.
|
||||
@ -0,0 +1,66 @@
|
||||
|
||||
.. _finding_galaxy_roles:
|
||||
|
||||
*************************
|
||||
Finding roles on Galaxy
|
||||
*************************
|
||||
|
||||
Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy search elasticsearch --author geerlingguy
|
||||
|
||||
The search command will return a list of the first 1000 results matching your search:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Found 2 roles matching your search:
|
||||
|
||||
Name Description
|
||||
---- -----------
|
||||
geerlingguy.elasticsearch Elasticsearch for Linux.
|
||||
geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.
|
||||
|
||||
|
||||
Get more information about a role
|
||||
=================================
|
||||
|
||||
Use the ``info`` command to view more detail about a specific role:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy info username.role_name
|
||||
|
||||
This returns everything found in Galaxy for the role:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Role: username.role_name
|
||||
description: Installs and configures a thing, a distributed, highly available NoSQL thing.
|
||||
active: True
|
||||
commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57
|
||||
commit_message: Adding travis
|
||||
commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab
|
||||
company: My Company, Inc.
|
||||
created: 2015-12-08T14:17:52.773Z
|
||||
download_count: 1
|
||||
forks_count: 0
|
||||
github_branch:
|
||||
github_repo: repo_name
|
||||
github_user: username
|
||||
id: 6381
|
||||
is_valid: True
|
||||
issue_tracker_url:
|
||||
license: Apache
|
||||
min_ansible_version: 1.4
|
||||
modified: 2015-12-08T18:43:49.085Z
|
||||
namespace: username
|
||||
open_issues_count: 0
|
||||
path: /Users/username/projects/roles
|
||||
scm: None
|
||||
src: username.repo_name
|
||||
stargazers_count: 0
|
||||
travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
|
||||
version:
|
||||
watchers_count: 1
|
||||
@ -0,0 +1,26 @@
|
||||
.. _using_galaxy:
|
||||
.. _ansible_galaxy:
|
||||
|
||||
**********
|
||||
User Guide
|
||||
**********
|
||||
|
||||
:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_ website, a free site for finding, downloading, and sharing community developed roles.
|
||||
|
||||
Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_.
|
||||
You can find roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
finding_collections
|
||||
finding_roles
|
||||
installing_collections
|
||||
installing_roles
|
||||
|
||||
|
||||
.. seealso::
|
||||
`collections <collections>`_
|
||||
Sharable collections of modules, playbooks and roles
|
||||
`roles <playbooks_reuse_roles>`_
|
||||
Reusable tasks, handlers, and other files in a known directory structure
|
||||
@ -0,0 +1,22 @@
|
||||
.. _installing_galaxy_collections:
|
||||
|
||||
Installing collections from Galaxy
|
||||
==================================
|
||||
|
||||
.. include:: ../../shared_snippets/installing_collections.txt
|
||||
|
||||
|
||||
Installing an older version of a collection
|
||||
-------------------------------------------
|
||||
|
||||
.. include:: ../../shared_snippets/installing_older_collection.txt
|
||||
|
||||
Install multiple collections with a requirements file
|
||||
-----------------------------------------------------
|
||||
|
||||
.. include:: ../../shared_snippets/installing_multiple_collections.txt
|
||||
|
||||
Galaxy server configuration list
|
||||
--------------------------------
|
||||
|
||||
.. include:: ../../shared_snippets/galaxy_server_list.txt
|
||||
@ -0,0 +1,218 @@
|
||||
Installing roles from Galaxy
|
||||
============================
|
||||
|
||||
The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can
|
||||
also use it to create a new role, remove roles, or perform tasks on the Galaxy website.
|
||||
|
||||
The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. Since the `Galaxy project <https://github.com/ansible/galaxy>`_
|
||||
is an open source project, you may be running your own internal Galaxy server and wish to override the default server address. You can do this using the *--server* option
|
||||
or by setting the Galaxy server value in your *ansible.cfg* file. For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`.
|
||||
|
||||
|
||||
Installing Roles
|
||||
----------------
|
||||
|
||||
Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy install username.role_name
|
||||
|
||||
roles_path
|
||||
^^^^^^^^^^
|
||||
|
||||
By default Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. This will install roles in the home directory of the user running ``ansible-galaxy``.
|
||||
|
||||
You can override this by setting the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session, defining ``roles_path`` in an ``ansible.cfg`` file, or by using the ``--roles-path`` option.
|
||||
|
||||
The following provides an example of using ``--roles-path`` to install the role into the current working directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy install --roles-path . geerlingguy.apache
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`intro_configuration`
|
||||
All about configuration files
|
||||
|
||||
Installing a specific version of a role
|
||||
---------------------------------------
|
||||
|
||||
You can install a specific version of a role from Galaxy by appending a comma and the value of a GitHub release tag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy install geerlingguy.apache,v1.0.0
|
||||
|
||||
It's also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following will
|
||||
install a specific commit:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
|
||||
|
||||
|
||||
Installing multiple roles from a file
|
||||
-------------------------------------
|
||||
|
||||
Beginning with Ansible 1.8 it is possible to install multiple roles by including the roles in a *requirements.yml* file. The format of the file is YAML, and the
|
||||
file extension must be either *.yml* or *.yaml*.
|
||||
|
||||
Use the following command to install roles included in *requirements.yml*:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy install -r requirements.yml
|
||||
|
||||
Again, the extension is important. If the *.yml* extension is left off, the ``ansible-galaxy`` CLI assumes the file is in an older, now deprecated,
|
||||
"basic" format.
|
||||
|
||||
Each role in the file will have one or more of the following attributes:
|
||||
|
||||
src
|
||||
The source of the role. Use the format *username.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing
|
||||
to a repository within a git based SCM. See the examples below. This is a required attribute.
|
||||
scm
|
||||
Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*.
|
||||
version:
|
||||
The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the *master*.
|
||||
name:
|
||||
Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults
|
||||
to the name of the repository.
|
||||
|
||||
Use the following example as a guide for specifying roles in *requirements.yml*:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# from galaxy
|
||||
- src: yatesr.timezone
|
||||
|
||||
# from GitHub
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
|
||||
# from GitHub, overriding the name and specifying a specific tag
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
version: master
|
||||
name: nginx_role
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.gz
|
||||
- src: https://some.webserver.example.com/files/master.tar.gz
|
||||
name: http-role-gz
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.bz2
|
||||
- src: https://some.webserver.example.com/files/master.tar.bz2
|
||||
name: http-role-bz2
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
|
||||
- src: https://some.webserver.example.com/files/master.tar.xz
|
||||
name: http-role-xz
|
||||
|
||||
# from Bitbucket
|
||||
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy
|
||||
version: v1.4
|
||||
|
||||
# from Bitbucket, alternative syntax and caveats
|
||||
- src: https://bitbucket.org/willthames/hg-ansible-galaxy
|
||||
scm: hg
|
||||
|
||||
# from GitLab or other git-based scm, using git+ssh
|
||||
- src: git@gitlab.company.com:mygroup/ansible-base.git
|
||||
scm: git
|
||||
version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value
|
||||
|
||||
Installing multiple roles from multiple files
|
||||
---------------------------------------------
|
||||
|
||||
At a basic level, including requirements files allows you to break up bits of roles into smaller files. Role includes pull in roles from other files.
|
||||
|
||||
Use the following command to install roles includes in *requirements.yml* + *webserver.yml*
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy install -r requirements.yml
|
||||
|
||||
Content of the *requirements.yml* file:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# from galaxy
|
||||
- src: yatesr.timezone
|
||||
|
||||
- include: <path_to_requirements>/webserver.yml
|
||||
|
||||
|
||||
Content of the *webserver.yml* file:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
# from github
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
|
||||
# from Bitbucket
|
||||
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy
|
||||
version: v1.4
|
||||
|
||||
.. _galaxy_dependencies:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed.
|
||||
|
||||
You specify role dependencies in the ``meta/main.yml`` file by providing a list of roles. If the source of a role is Galaxy, you can simply specify the role in
|
||||
the format ``username.role_name``. You can also use the more complex format in ``requirements.yml``, allowing you to provide ``src``, ``scm``, ``version``, and ``name``.
|
||||
|
||||
Tags are inherited *down* the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role.
|
||||
|
||||
Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on
|
||||
what tags and conditionals are applied.
|
||||
|
||||
Dependencies found in Galaxy can be specified as follows:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
dependencies:
|
||||
- geerlingguy.apache
|
||||
- geerlingguy.ansible
|
||||
|
||||
|
||||
The complex form can also be used as follows:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
dependencies:
|
||||
- src: geerlingguy.ansible
|
||||
- src: git+https://github.com/geerlingguy/ansible-role-composer.git
|
||||
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
|
||||
name: composer
|
||||
|
||||
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`.
|
||||
|
||||
.. note::
|
||||
|
||||
At the time of this writing, the Galaxy website expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the
|
||||
``username.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail.
|
||||
|
||||
List installed roles
|
||||
--------------------
|
||||
|
||||
Use ``list`` to show the name and version of each role installed in the *roles_path*.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy list
|
||||
|
||||
- chouseknecht.role-install_mongod, master
|
||||
- chouseknecht.test-role-1, v1.0.2
|
||||
- chrismeyersfsu.role-iptables, master
|
||||
- chrismeyersfsu.role-required_vars, master
|
||||
|
||||
Remove an installed role
|
||||
------------------------
|
||||
|
||||
Use ``remove`` to delete a role from *roles_path*:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible-galaxy remove username.role_name
|
||||
@ -1,529 +0,0 @@
|
||||
.. _ansible_galaxy:
|
||||
|
||||
Ansible Galaxy
|
||||
++++++++++++++
|
||||
|
||||
*Ansible Galaxy* refers to the `Galaxy <https://galaxy.ansible.com>`_ website where users can share roles, and to a command line tool for installing,
|
||||
creating and managing roles.
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
The Website
|
||||
```````````
|
||||
|
||||
`Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, and sharing community developed roles. Downloading roles from Galaxy is
|
||||
a great way to jumpstart your automation projects.
|
||||
|
||||
You can also use the site to share roles that you create. By authenticating with the site using your GitHub account, you're able to *import* roles, making
|
||||
them available to the Ansible community. Imported roles become available in the Galaxy search index and visible on the site, allowing users to
|
||||
discover and download them.
|
||||
|
||||
Learn more by viewing `the About page <https://galaxy.ansible.com/docs/>`_.
|
||||
|
||||
The command line tool
|
||||
`````````````````````
|
||||
|
||||
The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can
|
||||
also use it to create a new role, remove roles, or perform tasks on the Galaxy website.
|
||||
|
||||
The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. Since the `Galaxy project <https://github.com/ansible/galaxy>`_
|
||||
is an open source project, you may be running your own internal Galaxy server and wish to override the default server address. You can do this using the *--server* option
|
||||
or by setting the Galaxy server value in your *ansible.cfg* file. For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`.
|
||||
|
||||
|
||||
Installing Roles
|
||||
----------------
|
||||
|
||||
Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install username.role_name
|
||||
|
||||
roles_path
|
||||
==========
|
||||
|
||||
By default Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. This will install roles in the home directory of the user running ``ansible-galaxy``.
|
||||
|
||||
You can override this by setting the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session, defining ``roles_path`` in an ``ansible.cfg`` file, or by using the ``--roles-path`` option.
|
||||
|
||||
The following provides an example of using ``--roles-path`` to install the role into the current working directory:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install --roles-path . geerlingguy.apache
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`intro_configuration`
|
||||
All about configuration files
|
||||
|
||||
version
|
||||
=======
|
||||
|
||||
You can install a specific version of a role from Galaxy by appending a comma and the value of a GitHub release tag. For example:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install geerlingguy.apache,v1.0.0
|
||||
|
||||
It's also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following will
|
||||
install a specific commit:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
|
||||
|
||||
|
||||
Installing multiple roles from a file
|
||||
=====================================
|
||||
|
||||
Beginning with Ansible 1.8 it is possible to install multiple roles by including the roles in a *requirements.yml* file. The format of the file is YAML, and the
|
||||
file extension must be either *.yml* or *.yaml*.
|
||||
|
||||
Use the following command to install roles included in *requirements.yml*:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install -r requirements.yml
|
||||
|
||||
Again, the extension is important. If the *.yml* extension is left off, the ``ansible-galaxy`` CLI assumes the file is in an older, now deprecated,
|
||||
"basic" format.
|
||||
|
||||
Each role in the file will have one or more of the following attributes:
|
||||
|
||||
src
|
||||
The source of the role. Use the format *username.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing
|
||||
to a repository within a git based SCM. See the examples below. This is a required attribute.
|
||||
scm
|
||||
Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*.
|
||||
version:
|
||||
The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the *master*.
|
||||
name:
|
||||
Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults
|
||||
to the name of the repository.
|
||||
|
||||
Use the following example as a guide for specifying roles in *requirements.yml*:
|
||||
|
||||
::
|
||||
|
||||
# from galaxy
|
||||
- src: yatesr.timezone
|
||||
|
||||
# from GitHub
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
|
||||
# from GitHub, overriding the name and specifying a specific tag
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
version: master
|
||||
name: nginx_role
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.gz
|
||||
- src: https://some.webserver.example.com/files/master.tar.gz
|
||||
name: http-role-gz
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.bz2
|
||||
- src: https://some.webserver.example.com/files/master.tar.bz2
|
||||
name: http-role-bz2
|
||||
|
||||
# from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
|
||||
- src: https://some.webserver.example.com/files/master.tar.xz
|
||||
name: http-role-xz
|
||||
|
||||
# from Bitbucket
|
||||
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy
|
||||
version: v1.4
|
||||
|
||||
# from Bitbucket, alternative syntax and caveats
|
||||
- src: https://bitbucket.org/willthames/hg-ansible-galaxy
|
||||
scm: hg
|
||||
|
||||
# from GitLab or other git-based scm, using git+ssh
|
||||
- src: git@gitlab.company.com:mygroup/ansible-base.git
|
||||
scm: git
|
||||
version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value
|
||||
|
||||
Installing multiple roles from multiple files
|
||||
=============================================
|
||||
|
||||
At a basic level, including requirements files allows you to break up bits of roles into smaller files. Role includes pull in roles from other files.
|
||||
|
||||
Use the following command to install roles includes in *requirements.yml* + *webserver.yml*
|
||||
|
||||
::
|
||||
|
||||
ansible-galaxy install -r requirements.yml
|
||||
|
||||
Content of the *requirements.yml* file:
|
||||
|
||||
::
|
||||
|
||||
# from galaxy
|
||||
- src: yatesr.timezone
|
||||
|
||||
- include: <path_to_requirements>/webserver.yml
|
||||
|
||||
|
||||
Content of the *webserver.yml* file:
|
||||
|
||||
::
|
||||
|
||||
# from github
|
||||
- src: https://github.com/bennojoy/nginx
|
||||
|
||||
# from Bitbucket
|
||||
- src: git+https://bitbucket.org/willthames/git-ansible-galaxy
|
||||
version: v1.4
|
||||
|
||||
.. _galaxy_dependencies:
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed.
|
||||
|
||||
You specify role dependencies in the ``meta/main.yml`` file by providing a list of roles. If the source of a role is Galaxy, you can simply specify the role in
|
||||
the format ``username.role_name``. You can also use the more complex format in ``requirements.yml``, allowing you to provide ``src``, ``scm``, ``version``, and ``name``.
|
||||
|
||||
Tags are inherited *down* the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role.
|
||||
|
||||
Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on
|
||||
what tags and conditionals are applied.
|
||||
|
||||
Dependencies found in Galaxy can be specified as follows:
|
||||
|
||||
::
|
||||
|
||||
dependencies:
|
||||
- geerlingguy.apache
|
||||
- geerlingguy.ansible
|
||||
|
||||
|
||||
The complex form can also be used as follows:
|
||||
|
||||
::
|
||||
|
||||
dependencies:
|
||||
- src: geerlingguy.ansible
|
||||
- src: git+https://github.com/geerlingguy/ansible-role-composer.git
|
||||
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
|
||||
name: composer
|
||||
|
||||
When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`.
|
||||
|
||||
.. note::
|
||||
|
||||
At the time of this writing, the Galaxy website expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the
|
||||
``username.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail.
|
||||
|
||||
Create roles
|
||||
------------
|
||||
|
||||
Use the ``init`` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy init role_name
|
||||
|
||||
The above will create the following directory structure in the current working directory:
|
||||
|
||||
::
|
||||
|
||||
role_name/
|
||||
README.md
|
||||
.travis.yml
|
||||
defaults/
|
||||
main.yml
|
||||
files/
|
||||
handlers/
|
||||
main.yml
|
||||
meta/
|
||||
main.yml
|
||||
templates/
|
||||
tests/
|
||||
inventory
|
||||
test.yml
|
||||
vars/
|
||||
main.yml
|
||||
|
||||
If you want to create a repository for the role the repository root should be `role_name`.
|
||||
|
||||
Force
|
||||
=====
|
||||
|
||||
If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error
|
||||
use the *--force* option. Force will create the above subdirectories and files, replacing anything that matches.
|
||||
|
||||
Container Enabled
|
||||
=================
|
||||
|
||||
If you are creating a Container Enabled role, pass ``--type container`` to ``ansible-galaxy init``. This will create the same directory structure as above, but populate it
|
||||
with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests
|
||||
the role using `Ansible Container <https://github.com/ansible/ansible-container>`_, and the meta directory includes a *container.yml* file.
|
||||
|
||||
Using a Custom Role Skeleton
|
||||
============================
|
||||
|
||||
A custom role skeleton directory can be supplied as follows:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name
|
||||
|
||||
When a skeleton is provided, init will:
|
||||
|
||||
- copy all files and directories from the skeleton to the new role
|
||||
- any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role_name
|
||||
- The .git folder and any .git_keep files will not be copied
|
||||
|
||||
Alternatively, the role_skeleton and ignoring of files can be configured via ansible.cfg
|
||||
|
||||
::
|
||||
|
||||
[galaxy]
|
||||
role_skeleton = /path/to/skeleton
|
||||
role_skeleton_ignore = ^.git$,^.*/.git_keep$
|
||||
|
||||
|
||||
Search for Roles
|
||||
----------------
|
||||
|
||||
Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy search elasticsearch --author geerlingguy
|
||||
|
||||
The search command will return a list of the first 1000 results matching your search:
|
||||
|
||||
::
|
||||
|
||||
Found 2 roles matching your search:
|
||||
|
||||
Name Description
|
||||
---- -----------
|
||||
geerlingguy.elasticsearch Elasticsearch for Linux.
|
||||
geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.
|
||||
|
||||
|
||||
Get more information about a role
|
||||
---------------------------------
|
||||
|
||||
Use the ``info`` command to view more detail about a specific role:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy info username.role_name
|
||||
|
||||
This returns everything found in Galaxy for the role:
|
||||
|
||||
::
|
||||
|
||||
Role: username.role_name
|
||||
description: Installs and configures a thing, a distributed, highly available NoSQL thing.
|
||||
active: True
|
||||
commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57
|
||||
commit_message: Adding travis
|
||||
commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab
|
||||
company: My Company, Inc.
|
||||
created: 2015-12-08T14:17:52.773Z
|
||||
download_count: 1
|
||||
forks_count: 0
|
||||
github_branch:
|
||||
github_repo: repo_name
|
||||
github_user: username
|
||||
id: 6381
|
||||
is_valid: True
|
||||
issue_tracker_url:
|
||||
license: Apache
|
||||
min_ansible_version: 1.4
|
||||
modified: 2015-12-08T18:43:49.085Z
|
||||
namespace: username
|
||||
open_issues_count: 0
|
||||
path: /Users/username/projects/roles
|
||||
scm: None
|
||||
src: username.repo_name
|
||||
stargazers_count: 0
|
||||
travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
|
||||
version:
|
||||
watchers_count: 1
|
||||
|
||||
|
||||
List installed roles
|
||||
--------------------
|
||||
|
||||
Use ``list`` to show the name and version of each role installed in the *roles_path*.
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy list
|
||||
|
||||
- chouseknecht.role-install_mongod, master
|
||||
- chouseknecht.test-role-1, v1.0.2
|
||||
- chrismeyersfsu.role-iptables, master
|
||||
- chrismeyersfsu.role-required_vars, master
|
||||
|
||||
Remove an installed role
|
||||
------------------------
|
||||
|
||||
Use ``remove`` to delete a role from *roles_path*:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy remove username.role_name
|
||||
|
||||
Authenticate with Galaxy
|
||||
------------------------
|
||||
|
||||
Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
|
||||
can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
|
||||
|
||||
The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
|
||||
|
||||
The following shows authenticating with the Galaxy website using a GitHub username and password:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy login
|
||||
|
||||
We need your GitHub login to identify you.
|
||||
This information will not be sent to Galaxy, only to api.github.com.
|
||||
The password will not be displayed.
|
||||
|
||||
Use --github-token if you do not want to enter your password.
|
||||
|
||||
GitHub Username: dsmith
|
||||
Password for dsmith:
|
||||
Successfully logged into Galaxy as dsmith
|
||||
|
||||
When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
|
||||
It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
|
||||
destroyed.
|
||||
|
||||
If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token
|
||||
that you create.
|
||||
|
||||
|
||||
Import a role
|
||||
-------------
|
||||
|
||||
The ``import`` command requires that you first authenticate using the ``login`` command. Once authenticated you can import any GitHub repository that you own or have
|
||||
been granted access.
|
||||
|
||||
Use the following to import to role:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy import github_user github_repo
|
||||
|
||||
By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses:
|
||||
|
||||
::
|
||||
|
||||
Successfully submitted import request 41
|
||||
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
|
||||
Retrieving GitHub repo githubuser/ansible-role-repo
|
||||
Accessing branch: master
|
||||
Parsing and validating meta/main.yml
|
||||
Parsing galaxy_tags
|
||||
Parsing platforms
|
||||
Adding dependencies
|
||||
Parsing and validating README.md
|
||||
Adding repo tags as role versions
|
||||
Import completed
|
||||
Status SUCCESS : warnings=0 errors=0
|
||||
|
||||
Branch
|
||||
======
|
||||
|
||||
Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used.
|
||||
|
||||
Role name
|
||||
=========
|
||||
|
||||
By default the name given to the role will be derived from the GitHub repository name. However, you can use the *--role-name* option to override this and set the name.
|
||||
|
||||
No wait
|
||||
=======
|
||||
|
||||
If the *--no-wait* option is present, the command will not wait for results. Results of the most recent import for any of your roles is available on the Galaxy web site
|
||||
by visiting *My Imports*.
|
||||
|
||||
Delete a role
|
||||
-------------
|
||||
|
||||
The ``delete`` command requires that you first authenticate using the ``login`` command. Once authenticated you can remove a role from the Galaxy web site. You are only allowed
|
||||
to remove roles where you have access to the repository in GitHub.
|
||||
|
||||
Use the following to delete a role:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy delete github_user github_repo
|
||||
|
||||
This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.
|
||||
|
||||
|
||||
Travis integrations
|
||||
-------------------
|
||||
|
||||
You can create an integration or connection between a role in Galaxy and `Travis <https://travis-ci.org>`_. Once the connection is established, a build in Travis will
|
||||
automatically trigger an import in Galaxy, updating the search index with the latest information about the role.
|
||||
|
||||
You create the integration using the ``setup`` command, but before an integration can be created, you must first authenticate using the ``login`` command; you will
|
||||
also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
|
||||
|
||||
The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described
|
||||
in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The hash is stored in Galaxy and used to verify notifications received from Travis.
|
||||
|
||||
The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the
|
||||
`Travis getting started guide <https://docs.travis-ci.com/user/getting-started/>`_.
|
||||
|
||||
To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
|
||||
|
||||
::
|
||||
|
||||
notifications:
|
||||
webhooks: https://galaxy.ansible.com/api/v1/notifications/
|
||||
|
||||
|
||||
List Travis integrations
|
||||
========================
|
||||
|
||||
Use the *--list* option to display your Travis integrations:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy setup --list
|
||||
|
||||
|
||||
ID Source Repo
|
||||
---------- ---------- ----------
|
||||
2 travis github_user/github_repo
|
||||
1 travis github_user/github_repo
|
||||
|
||||
|
||||
Remove Travis integrations
|
||||
==========================
|
||||
|
||||
Use the *--remove* option to disable and remove a Travis integration:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy setup --remove ID
|
||||
|
||||
Provide the ID of the integration to be disabled. You can find the ID by using the *--list* option.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`playbooks_reuse_roles`
|
||||
All about ansible roles
|
||||
`Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
@ -0,0 +1,63 @@
|
||||
|
||||
|
||||
|
||||
By default running ``ansible-galaxy`` will use the :ref:`galaxy_server` config value or the ``--server`` command line
|
||||
argument when it performs an action against a Galaxy server. The ``ansible-galaxy collection install`` supports
|
||||
installing collections from multiple servers as defined in the :ref:`ansible_configuration_settings_locations` file
|
||||
using the :ref:`galaxy_server_list` configuration option. To define multiple Galaxy servers you have to create the
|
||||
following entries like so:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[galaxy]
|
||||
server_list = automation_hub, my_org_hub, release_galaxy, test_galaxy
|
||||
|
||||
[galaxy_server.automation_hub]
|
||||
url=https://ci.cloud.redhat.com/api/automation-hub/
|
||||
auth_url=https://sso.qa.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
|
||||
token=my_token
|
||||
|
||||
[galaxy_server.my_org_hub]
|
||||
url=https://automation.my_org/
|
||||
username=my_user
|
||||
password=my_pass
|
||||
|
||||
[galaxy_server.release_galaxy]
|
||||
url=https://galaxy.ansible.com/
|
||||
token=my_token
|
||||
|
||||
[galaxy_server.test_galaxy]
|
||||
url=https://galaxy-dev.ansible.com/
|
||||
token=my_token
|
||||
|
||||
.. note::
|
||||
You can use the ``--server`` command line argument to select an explicit Galaxy server in the ``server_list`` and
|
||||
the value of this arg should match the name of the server. If the value of ``--server`` is not a pre-defined server
|
||||
in ``ansible.cfg`` then the value specified will be the URL used to access that server and all pre-defined servers
|
||||
are ignored. Also the ``--api-key`` argument is not applied to any of the pre-defined servers, it is only applied
|
||||
if no server list is defined or a URL was specified by ``--server``.
|
||||
|
||||
|
||||
The :ref:`galaxy_server_list` option is a list of server identifiers in a prioritized order. When searching for a
|
||||
collection, the install process will search in that order, e.g. ``my_org_hub`` first, then ``release_galaxy``, and
|
||||
finally ``test_galaxy`` until the collection is found. The actual Galaxy instance is then defined under the section
|
||||
``[galaxy_server.{{ id }}]`` where ``{{ id }}`` is the server identifier defined in the list. This section can then
|
||||
define the following keys:
|
||||
|
||||
* ``url``: The URL of the galaxy instance to connect to, this is required.
|
||||
* ``token``: A token key to use for authentication against the Galaxy instance, this is mutually exclusive with ``username``
|
||||
* ``username``: The username to use for basic authentication against the Galaxy instance, this is mutually exclusive with ``token``
|
||||
* ``password``: The password to use for basic authentication
|
||||
* ``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO auth (Automation Hub for ex). This is mutually exclusive with ``username``. ``auth_url`` requires ``token``.
|
||||
|
||||
As well as being defined in the ``ansible.cfg`` file, these server options can be defined as an environment variable.
|
||||
The environment variable is in the form ``ANSIBLE_GALAXY_SERVER_{{ id }}_{{ key }}`` where ``{{ id }}`` is the upper
|
||||
case form of the server identifier and ``{{ key }}`` is the key to define. For example I can define ``token`` for
|
||||
``release_galaxy`` by setting ``ANSIBLE_GALAXY_SERVER_RELEASE_GALAXY_TOKEN=secret_token``.
|
||||
|
||||
For operations where only one Galaxy server is used, i.e. ``publish``, ``info``, ``login`` then the first entry in the
|
||||
``server_list`` is used unless an explicit server was passed in as a command line argument.
|
||||
|
||||
.. note::
|
||||
Once a collection is found, any of its requirements are only searched within the same Galaxy instance as the parent
|
||||
collection. The install process will not search for a collection requirement in a different Galaxy instance.
|
||||
@ -0,0 +1,36 @@
|
||||
|
||||
You can use the ``ansible-galaxy collection install`` command to install a collection on your system.
|
||||
|
||||
To install a collection hosted in Galaxy:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection install my_namespace.my_collection
|
||||
|
||||
You can also directly use the tarball from your build:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
|
||||
|
||||
.. note::
|
||||
The install command automatically appends the path ``ansible_collections`` to the one specified with the ``-p`` option unless the
|
||||
parent directory is already in a folder called ``ansible_collections``.
|
||||
|
||||
|
||||
When using the ``-p`` option to specify the install path, use one of the values configured in :ref:`COLLECTIONS_PATHS`, as this is
|
||||
where Ansible itself will expect to find collections. If you don't specify a path, ``ansible-galaxy collection install`` installs
|
||||
the collection to the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``
|
||||
|
||||
You can also keep a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
play.yml
|
||||
├── collections/
|
||||
│ └── ansible_collections/
|
||||
│ └── my_namespace/
|
||||
│ └── my_collection/<collection structure lives here>
|
||||
|
||||
|
||||
See :ref:`collection_structure` for details on the collection directory structure.
|
||||
@ -0,0 +1,24 @@
|
||||
|
||||
You can also setup a ``requirements.yml`` file to install multiple collections in one command. This file is a YAML file in the format:
|
||||
|
||||
.. code-block:: yaml+jinja
|
||||
|
||||
---
|
||||
collections:
|
||||
# With just the collection name
|
||||
- my_namespace.my_collection
|
||||
|
||||
# With the collection name, version, and source options
|
||||
- name: my_namespace.my_other_collection
|
||||
version: 'version range identifiers (default: ``*``)'
|
||||
source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'
|
||||
|
||||
The ``version`` key can take in the same range identifier format documented above.
|
||||
|
||||
Roles can also be specified and placed under the ``roles`` key. The values follow the same format as a requirements
|
||||
file used in older Ansible releases.
|
||||
|
||||
.. note::
|
||||
While both roles and collections can be specified in one requirements file, they need to be installed separately.
|
||||
The ``ansible-galaxy role install -r requirements.yml`` will only install roles and
|
||||
``ansible-galaxy collection install -r requirements.yml -p ./`` will only install collections.
|
||||
@ -0,0 +1,36 @@
|
||||
|
||||
By default ``ansible-galaxy`` installs the latest collection that is available but you can add a version range
|
||||
identifier to install a specific version.
|
||||
|
||||
To install the 1.0.0 version of the collection:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection install my_namespace.my_collection:1.0.0
|
||||
|
||||
To install the 1.0.0-beta.1 version of the collection:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection install my_namespace.my_collection:==1.0.0-beta.1
|
||||
|
||||
To install the collections that are greater than or equal to 1.0.0 or less than 2.0.0:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-galaxy collection install my_namespace.my_collection:>=1.0.0,<2.0.0
|
||||
|
||||
|
||||
You can specify multiple range identifiers which are split by ``,``. You can use the following range identifiers:
|
||||
|
||||
* ``*``: Any version, this is the default used when no range specified is set.
|
||||
* ``!=``: Version is not equal to the one specified.
|
||||
* ``==``: Version must be the one specified.
|
||||
* ``>=``: Version is greater than or equal to the one specified.
|
||||
* ``>``: Version is greater than the one specified.
|
||||
* ``<=``: Version is less than or equal to the one specified.
|
||||
* ``<``: Version is less than the one specified.
|
||||
|
||||
.. note::
|
||||
The ``ansible-galaxy`` command ignores any pre-release versions unless the ``==`` range identifier is used to
|
||||
explicitly set to that pre-release version.
|
||||
Loading…
Reference in New Issue