diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst b/docs/docsite/rst/galaxy/dev_guide.rst similarity index 81% rename from docs/docsite/rst/galaxy/dev_guide/creating_roles.rst rename to docs/docsite/rst/galaxy/dev_guide.rst index bca976287ce..4ee2467da28 100644 --- a/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst +++ b/docs/docsite/rst/galaxy/dev_guide.rst @@ -1,8 +1,31 @@ +.. _developing_galaxy: + +********************** +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 `_, and new in Galaxy 3.2, `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. + +.. contents:: + :local: + :depth: 2 + +.. _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 `_. + +See :ref:`developing_collections` for details on how to create collections. + .. _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 @@ -34,20 +57,20 @@ The above will create the following directory structure in the current working d 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 -================= +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 `_, and the meta directory includes a *container.yml* file. -Using a Custom Role Skeleton -============================ +Using a custom role skeleton +---------------------------- A custom role skeleton directory can be supplied as follows: @@ -70,7 +93,7 @@ Alternatively, the role_skeleton and ignoring of files can be configured via ans 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. @@ -101,7 +124,7 @@ If you do not wish to use your GitHub password, or if you have two-factor authen 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. @@ -129,22 +152,22 @@ By default the command will wait for Galaxy to complete the import process, disp 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. @@ -158,7 +181,7 @@ This only removes the role from Galaxy. It does not remove or alter the actual G Travis integrations -=================== +------------------- You can create an integration or connection between a role in Galaxy and `Travis `_. 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. @@ -185,7 +208,7 @@ To instruct Travis to notify Galaxy when a build completes, add the following to List Travis integrations ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Use the *--list* option to display your Travis integrations: @@ -201,7 +224,7 @@ Use the *--list* option to display your Travis integrations: Remove Travis integrations ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the *--remove* option to disable and remove a Travis integration: @@ -213,10 +236,13 @@ Provide the ID of the integration to be disabled. You can find the ID by using t .. seealso:: - - :ref:`playbooks_reuse_roles` - All about ansible roles - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - `irc.freenode.net `_ - #ansible IRC chat channel + `collections `_ + Sharable collections of modules, playbooks and roles + `roles `_ + Reusable tasks, handlers, and other files in a known directory structure + :ref:`playbooks_reuse_roles` + All about ansible roles + `Mailing List `_ + Questions? Help? Ideas? Stop by the list on Google Groups + `irc.freenode.net `_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst b/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst deleted file mode 100644 index db135374acc..00000000000 --- a/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _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 `_. - -See :ref:`developing_collections` for details on how to create collections. diff --git a/docs/docsite/rst/galaxy/dev_guide/index.rst b/docs/docsite/rst/galaxy/dev_guide/index.rst deleted file mode 100644 index 468b530fb13..00000000000 --- a/docs/docsite/rst/galaxy/dev_guide/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _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 `_, and new in Galaxy 3.2, `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 `_ - Sharable collections of modules, playbooks and roles - `roles `_ - Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst new file mode 100644 index 00000000000..a80141e07fc --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -0,0 +1,391 @@ +.. _using_galaxy: +.. _ansible_galaxy: + +***************** +Galaxy User Guide +***************** + +:dfn:`Ansible Galaxy` refers to the `Galaxy `_ 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 `_, and new in Galaxy 3.2, `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. + +.. contents:: + :local: + :depth: 2 +.. _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 :guilabel:`enter`. + +Galaxy presents a list of collections that match your search criteria. + +.. _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 + + +.. _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 + + +.. _installing_galaxy_roles: + +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 `_ +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 `_ + +.. code-block:: bash + + $ ansible-galaxy install namespace.role_name + +Setting where to install roles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 installs roles in the home directory of the user running ``ansible-galaxy``. + +You can override this with one of the following options: + +* Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session. +* Define ``roles_path`` in an ``ansible.cfg`` file. +* Use the ``--roles-path`` option for the ``ansible-galaxy`` command. + +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 +--------------------------------------- + +When the Galaxy server imports a role, it imports any git tags matching the Semantic Version format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. + +To see the available versions for a role: + +#. Locate the role on the Galaxy search page. +#. Click on the name to view more details, including the available versions. + +You can also navigate directly to the role using the //. For example, to view the role geerlingguy.apache, go to ``_. + +To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example: + +.. code-block:: bash + + $ ansible-galaxy install geerlingguy.apache,v1.0.0 + +It is 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 +------------------------------------- + +You can install multiple roles by including the roles in a :file:`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 :file:`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 *namespace.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:: yaml + + # 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 +--------------------------------------------- + +For large projects, the ``include`` directive in a :file:`requirements.yml` file provides the ability to split a large file into multiple smaller files. + +For example, a project may have a :file:`requirements.yml` file, and a :file:`webserver.yml` file. + +Below are the contents of the :file:`webserver.yml` file: + +.. code-block:: bash + + # from github + - src: https://github.com/bennojoy/nginx + + # from Bitbucket + - src: git+http://bitbucket.org/willthames/git-ansible-galaxy + version: v1.4 + +The following shows the contents of the :file:`requirements.yml` file that now includes the :file:`webserver.yml` file: + +.. code-block:: bash + + # from galaxy + - src: yatesr.timezone + - include: /webserver.yml + +To install all the roles from both files, pass the root file, in this case :file:`requirements.yml` on the +command line, as follows: + +.. code-block:: bash + + $ ansible-galaxy install -r requirements.yml + +.. _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 ``namespace.role_name``. You can also use the more complex format in ``requirements.yml``, allowing you to provide ``src``, ``scm``, ``version``, and ``name``. + +The following shows an example ``meta/main.yml`` file with dependent roles: + +.. code-block:: yaml + + --- + dependencies: + - geerlingguy.java + + galaxy_info: + author: geerlingguy + description: Elasticsearch for Linux. + company: "Midwestern Mac, LLC" + license: "license (BSD, MIT)" + min_ansible_version: 2.4 + platforms: + - name: EL + versions: + - all + - name: Debian + versions: + - all + - name: Ubuntu + versions: + - all + galaxy_tags: + - web + - system + - monitoring + - logging + - lucene + - elk + - elasticsearch + +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. + +If the source of a role is Galaxy, specify the role in the format *namespace.role_name*: + +.. code-block:: yaml + + dependencies: + - geerlingguy.apache + - geerlingguy.ansible + + +Alternately, you can specify the role dependencies in the complex form used in :file:`requirements.yml` as follows: + +.. code-block:: yaml + + 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:: + + Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the + ``namespace.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 + - ansible-network.network-engine, v2.7.2 + - ansible-network.config_manager, v2.6.2 + - ansible-network.cisco_nxos, v2.7.1 + - ansible-network.vyos, v2.7.3 + - ansible-network.cisco_ios, v2.7.0 + +Remove an installed role +------------------------ + +Use ``remove`` to delete a role from *roles_path*: + +.. code-block:: bash + + $ ansible-galaxy remove namespace.role_name + + +.. seealso:: + `collections `_ + Sharable collections of modules, playbooks and roles + `roles `_ + Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide/finding_collections.rst b/docs/docsite/rst/galaxy/user_guide/finding_collections.rst deleted file mode 100644 index 356e8e0146f..00000000000 --- a/docs/docsite/rst/galaxy/user_guide/finding_collections.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. _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. diff --git a/docs/docsite/rst/galaxy/user_guide/finding_roles.rst b/docs/docsite/rst/galaxy/user_guide/finding_roles.rst deleted file mode 100644 index 4d52fb74db8..00000000000 --- a/docs/docsite/rst/galaxy/user_guide/finding_roles.rst +++ /dev/null @@ -1,66 +0,0 @@ - -.. _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 diff --git a/docs/docsite/rst/galaxy/user_guide/index.rst b/docs/docsite/rst/galaxy/user_guide/index.rst deleted file mode 100644 index 0aa0a371be5..00000000000 --- a/docs/docsite/rst/galaxy/user_guide/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _using_galaxy: -.. _ansible_galaxy: - -********** -User Guide -********** - -:dfn:`Ansible Galaxy` refers to the `Galaxy `_ 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 `_, and new in Galaxy 3.2, `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 `_ - Sharable collections of modules, playbooks and roles - `roles `_ - Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide/installing_collections.rst b/docs/docsite/rst/galaxy/user_guide/installing_collections.rst deleted file mode 100644 index 4d1e4e5c210..00000000000 --- a/docs/docsite/rst/galaxy/user_guide/installing_collections.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _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 diff --git a/docs/docsite/rst/galaxy/user_guide/installing_roles.rst b/docs/docsite/rst/galaxy/user_guide/installing_roles.rst deleted file mode 100644 index 172df19d809..00000000000 --- a/docs/docsite/rst/galaxy/user_guide/installing_roles.rst +++ /dev/null @@ -1,218 +0,0 @@ -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 `_ -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 `_ - -.. 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: /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 diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index ce4e8cf8b54..53e38ac6e05 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -64,8 +64,8 @@ Ansible releases a new major release of Ansible approximately three to four time :maxdepth: 2 :caption: Ansible Galaxy - galaxy/user_guide/index - galaxy/dev_guide/index + galaxy/user_guide.rst + galaxy/dev_guide.rst .. toctree::