ansible/docsite/rst/galaxy.rst

457 lines
16 KiB
ReStructuredText
Raw Normal View History

Ansible Galaxy
2014-09-10 18:52:57 +02:00
++++++++++++++
2013-12-25 00:05:41 +01:00
2016-10-24 16:59:44 +02:00
*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.
2013-12-25 00:05:41 +01:00
2014-08-22 00:53:36 +02:00
.. contents:: Topics
The Website
```````````
2016-10-24 16:59:44 +02:00
`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.
2016-10-24 16:59:44 +02:00
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.
2013-12-25 00:05:41 +01:00
2016-10-24 16:59:44 +02:00
Learn more by viewing `the About page <https://galaxy.ansible.com/intro>`_.
2013-12-25 00:05:41 +01:00
2016-10-24 16:59:44 +02:00
The command line tool
`````````````````````
2016-10-24 16:59:44 +02:00
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.
2016-10-24 16:59:44 +02:00
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* visit `Galaxy Settings <./intro_configuration.html#galaxy-settings>`_.
Installing Roles
----------------
2016-10-24 16:59:44 +02:00
Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy install username.role_name
roles_path
==========
2016-10-24 16:59:44 +02:00
Be aware that by default Ansible downloads roles to the path specified by the environment variable *ANSIBLE_ROLES_PATH*. This can be set to a series of
directories (i.e. */etc/ansible/roles:~/.ansible/roles*), in which case the first writable path will be used. When Ansible is first installed it defaults
to */etc/ansible/roles*, which requires *root* privileges.
2016-10-24 16:59:44 +02:00
You can override this by setting the environment variable 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:
2016-10-24 16:59:44 +02:00
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy install --roles-path . geerlingguy.apache
2016-10-24 16:59:44 +02:00
.. seealso::
2016-10-24 16:59:44 +02:00
:doc:`intro_configuration`
All about configuration files
2016-10-24 16:59:44 +02:00
version
=======
2016-10-24 16:59:44 +02:00
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:
2016-10-24 16:59:44 +02:00
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy install geerlingguy.apache,v1.0.0
2016-10-24 16:59:44 +02:00
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:
2016-07-23 21:31:47 +02:00
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
Installing multiple roles from a file
=====================================
Beginning with Asible 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*.
2016-10-24 16:59:44 +02:00
Use the following command to install roles included in *requirements.yml*:
2016-07-23 21:31:47 +02:00
::
2016-10-24 16:59:44 +02:00
$ 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.
2016-10-24 16:59:44 +02:00
Each role in the file will have one or more of the following attributes:
2016-10-24 16:59:44 +02:00
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 supported. 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 *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.
2016-10-24 16:59:44 +02:00
Use the following example as a guide for specifying roles in *requirements.yml*:
2016-10-24 16:59:44 +02:00
::
2014-08-22 00:48:02 +02:00
# from galaxy
- src: yatesr.timezone
# from GitHub
2014-08-22 00:48:02 +02:00
- src: https://github.com/bennojoy/nginx
# from GitHub, overriding the name and specifying a specific tag
2014-08-22 00:48:02 +02:00
- src: https://github.com/bennojoy/nginx
version: master
2014-08-22 00:48:02 +02:00
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
# from Bitbucket
- src: git+http://bitbucket.org/willthames/git-ansible-galaxy
version: v1.4
# from Bitbucket, alternative syntax and caveats
- src: http://bitbucket.org/willthames/hg-ansible-galaxy
scm: hg
2016-10-24 16:59:44 +02:00
# from GitLab or other git-based scm
- 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
2016-10-24 16:59:44 +02:00
Dependencies
============
2016-10-24 16:59:44 +02:00
Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependenices 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*. The more complex format used in *requirements.yml* is also supported, allowing you to provide src, scm, version and name.
Dependencies found in Galaxy can be specified as follows:
::
dependencies:
- geerlingguy.apache
- geerlingguy.ansible
The complex form can also be used as follows:
::
2016-10-24 16:59:44 +02:00
dependencies:
- src: geerlingguy.ansible
- src: git+https://github.com/geerlingguy/ansible-role-composer.git
version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
name: composer
2016-10-24 16:59:44 +02:00
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 :doc:`playbooks_roles`.
2016-10-24 16:59:44 +02:00
.. note::
2013-12-25 00:05:41 +01:00
2016-10-24 16:59:44 +02:00
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.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Create roles
------------
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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
2015-12-09 16:51:12 +01:00
The above will create the following directory structure in the current working directory:
::
README.md
2015-12-14 18:06:35 +01:00
.travis.yml
2015-12-09 16:51:12 +01:00
defaults/
main.yml
files/
handlers/
main.yml
meta/
main.yml
templates/
tests/
inventory
test.yml
vars/
main.yml
Force
=====
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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.
2015-12-09 16:51:12 +01:00
Container Enabled
=================
If you are creating a Container Enabled role, use the *--container-enabled* option. 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.
2016-10-24 16:59:44 +02:00
Search for roles
2015-12-09 16:51:12 +01:00
----------------
2016-10-24 16:59:44 +02:00
Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
2015-12-09 16:51:12 +01:00
::
$ 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.
2016-10-24 16:59:44 +02:00
Get more information about a role
2015-12-09 16:51:12 +01:00
---------------------------------
2016-10-24 16:59:44 +02:00
Use the ``info`` command to view more detail about a specific role:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy info username.role_name
This returns everything found in Galaxy for the role:
::
2016-10-24 16:59:44 +02:00
Role: username.role_name
2015-12-09 16:51:12 +01:00
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
2016-10-24 16:59:44 +02:00
List installed roles
2015-12-09 16:51:12 +01:00
--------------------
2016-10-24 16:59:44 +02:00
Use ``list`` to show the name and version of each role installed in the *roles_path*.
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy list
- chouseknecht.role-install_mongod, master
- chouseknecht.test-role-1, v1.0.2
- chrismeyersfsu.role-iptables, master
- chrismeyersfsu.role-required_vars, master
2016-10-24 16:59:44 +02:00
Remove an installed role
2015-12-09 16:51:12 +01:00
------------------------
2016-10-24 16:59:44 +02:00
Use ``remove`` to delete a role from *roles_path*:
2015-12-09 16:51:12 +01:00
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy remove username.role_name
2015-12-09 16:51:12 +01:00
Authenticate with Galaxy
------------------------
2016-10-24 16:59:44 +02:00
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:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy login
2016-10-24 16:59:44 +02:00
We need your GitHub login to identify you.
2015-12-09 16:51:12 +01:00
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:
2016-10-24 16:59:44 +02:00
Successfully logged into Galaxy as dsmith
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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.
2016-10-24 16:59:44 +02:00
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.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Import a role
2015-12-09 16:51:12 +01:00
-------------
2016-10-24 16:59:44 +02:00
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.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Use the following to import to role:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy import github_user github_repo
2016-10-24 16:59:44 +02:00
By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses:
2015-12-09 16:51:12 +01:00
::
Successfully submitted import request 41
Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
2016-10-24 16:59:44 +02:00
Retrieving GitHub repo githubuser/ansible-role-repo
2015-12-09 16:51:12 +01:00
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
======
2016-10-24 16:59:44 +02:00
Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used.
2015-12-09 16:51:12 +01:00
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
2016-10-24 16:59:44 +02:00
by visiting *My Imports*.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Delete a role
2015-12-09 16:51:12 +01:00
-------------
2016-10-24 16:59:44 +02:00
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:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy delete github_user github_repo
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Travis integrations
-------------------
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
You can create an integration or connection between a role in Galaxy and `Travis <http://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.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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:
2015-12-09 16:51:12 +01:00
::
2016-10-24 16:59:44 +02:00
$ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
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/>`_.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
2015-12-09 16:51:12 +01:00
::
notifications:
webhooks: https://galaxy.ansible.com/api/v1/notifications/
2016-10-24 16:59:44 +02:00
List Travis integrations
========================
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
Use the *--list* option to display your Travis integrations:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy setup --list
ID Source Repo
---------- ---------- ----------
2 travis github_user/github_repo
1 travis github_user/github_repo
2016-10-24 16:59:44 +02:00
Remove Travis integrations
2015-12-09 16:51:12 +01:00
==========================
2016-10-24 16:59:44 +02:00
Use the *--remove* option to disable and remove a Travis integration:
2015-12-09 16:51:12 +01:00
::
$ ansible-galaxy setup --remove ID
2016-10-24 16:59:44 +02:00
Provide the ID of the integration to be disabled. You can find the ID by using the *--list* option.
2015-12-09 16:51:12 +01:00
2016-10-24 16:59:44 +02:00
.. seealso::
:doc:`playbooks_roles`
All about ansible roles
`Mailing List <http://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