1.. _using_galaxy: 2.. _ansible_galaxy: 3 4***************** 5Galaxy User Guide 6***************** 7 8:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_ website, a free site for finding, downloading, and sharing community developed roles. 9 10Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as :ref:`roles <playbooks_reuse_roles>`, and new in Galaxy 3.2, :ref:`collections <collections>` 11You 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. 12 13.. contents:: 14 :local: 15 :depth: 2 16.. _finding_galaxy_collections: 17 18Finding collections on Galaxy 19============================= 20 21To find collections on Galaxy: 22 23#. Click the :guilabel:`Search` icon in the left-hand navigation. 24#. Set the filter to *collection*. 25#. Set other filters and press :guilabel:`enter`. 26 27Galaxy presents a list of collections that match your search criteria. 28 29.. _installing_galaxy_collections: 30 31 32Installing collections 33====================== 34 35 36Installing a collection from Galaxy 37----------------------------------- 38 39.. include:: ../shared_snippets/installing_collections.txt 40 41.. _installing_ah_collection: 42 43Downloading a collection from Automation Hub 44---------------------------------------------------- 45 46You can download collections from Automation Hub at the command line. Automation Hub content is available to subscribers only, so you must download an API token and configure your local environment to provide it before you can you download collections. To download a collection from Automation Hub with the ``ansible-galaxy`` command: 47 481. Get your Automation Hub API token. Go to https://cloud.redhat.com/ansible/automation-hub/token/ and click :guilabel:`Get API token` from the version dropdown to copy your API token. 492. Configure Red Hat Automation Hub server in the ``server_list`` option under the ``[galaxy]`` section in your :file:`ansible.cfg` file. 50 51 .. code-block:: ini 52 53 [galaxy] 54 server_list = automation_hub 55 56 [galaxy_server.automation_hub] 57 url=https://cloud.redhat.com/api/automation-hub/ 58 auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token 59 token=my_ah_token 60 613. Download the collection hosted in Automation Hub. 62 63 .. code-block:: bash 64 65 ansible-galaxy collection install my_namespace.my_collection 66 67.. seealso:: 68 `Getting started with Automation Hub <https://www.ansible.com/blog/getting-started-with-ansible-hub>`_ 69 An introduction to Automation Hub 70 71Installing an older version of a collection 72------------------------------------------- 73 74.. include:: ../shared_snippets/installing_older_collection.txt 75 76Install multiple collections with a requirements file 77----------------------------------------------------- 78 79.. include:: ../shared_snippets/installing_multiple_collections.txt 80 81Downloading a collection for offline use 82----------------------------------------- 83 84.. include:: ../shared_snippets/download_tarball_collections.txt 85 86Installing a collection from a git repository 87--------------------------------------------- 88 89.. include:: ../shared_snippets/installing_collections_git_repo.txt 90 91Listing installed collections 92----------------------------- 93 94To list installed collections, run ``ansible-galaxy collection list``. See :ref:`collections_listing` for more details. 95 96 97Configuring the ``ansible-galaxy`` client 98------------------------------------------ 99 100.. include:: ../shared_snippets/galaxy_server_list.txt 101 102.. _finding_galaxy_roles: 103 104Finding roles on Galaxy 105======================= 106 107Search the Galaxy database by tags, platforms, author and multiple keywords. For example: 108 109.. code-block:: bash 110 111 $ ansible-galaxy search elasticsearch --author geerlingguy 112 113The search command will return a list of the first 1000 results matching your search: 114 115.. code-block:: text 116 117 Found 2 roles matching your search: 118 119 Name Description 120 ---- ----------- 121 geerlingguy.elasticsearch Elasticsearch for Linux. 122 geerlingguy.elasticsearch-curator Elasticsearch curator for Linux. 123 124 125Get more information about a role 126--------------------------------- 127 128Use the ``info`` command to view more detail about a specific role: 129 130.. code-block:: bash 131 132 $ ansible-galaxy info username.role_name 133 134This returns everything found in Galaxy for the role: 135 136.. code-block:: text 137 138 Role: username.role_name 139 description: Installs and configures a thing, a distributed, highly available NoSQL thing. 140 active: True 141 commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57 142 commit_message: Adding travis 143 commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab 144 company: My Company, Inc. 145 created: 2015-12-08T14:17:52.773Z 146 download_count: 1 147 forks_count: 0 148 github_branch: 149 github_repo: repo_name 150 github_user: username 151 id: 6381 152 is_valid: True 153 issue_tracker_url: 154 license: Apache 155 min_ansible_version: 1.4 156 modified: 2015-12-08T18:43:49.085Z 157 namespace: username 158 open_issues_count: 0 159 path: /Users/username/projects/roles 160 scm: None 161 src: username.repo_name 162 stargazers_count: 0 163 travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master 164 version: 165 watchers_count: 1 166 167 168.. _installing_galaxy_roles: 169 170Installing roles from Galaxy 171============================ 172 173The ``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 174also use it to create a new role, remove roles, or perform tasks on the Galaxy website. 175 176The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. If you run your own internal Galaxy server 177and want to use it instead of the default one, pass the ``--server`` option following the address of this galaxy server. You can set permanently this option by setting 178the Galaxy server value in your ``ansible.cfg`` file to use it . For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`. 179 180 181Installing roles 182---------------- 183 184Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_ 185 186.. code-block:: bash 187 188 $ ansible-galaxy install namespace.role_name 189 190Setting where to install roles 191^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 192 193By default, Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/local/share/py38-ansible/roles:/usr/local/etc/ansible/roles``. This installs roles in the home directory of the user running ``ansible-galaxy``. 194 195You can override this with one of the following options: 196 197* Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session. 198* Use the ``--roles-path`` option for the ``ansible-galaxy`` command. 199* Define ``roles_path`` in an ``ansible.cfg`` file. 200 201The following provides an example of using ``--roles-path`` to install the role into the current working directory: 202 203.. code-block:: bash 204 205 $ ansible-galaxy install --roles-path . geerlingguy.apache 206 207.. seealso:: 208 209 :ref:`intro_configuration` 210 All about configuration files 211 212Installing a specific version of a role 213--------------------------------------- 214 215When the Galaxy server imports a role, it imports any git tags matching the `Semantic Version <https://semver.org/>`_ format as versions. 216In turn, you can download a specific version of a role by specifying one of the imported tags. 217 218To see the available versions for a role: 219 220#. Locate the role on the Galaxy search page. 221#. Click on the name to view more details, including the available versions. 222 223You can also navigate directly to the role using the /<namespace>/<role name>. For example, to view the role geerlingguy.apache, go to `<https://galaxy.ansible.com/geerlingguy/apache>`_. 224 225To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example: 226 227.. code-block:: bash 228 229 $ ansible-galaxy install geerlingguy.apache,v1.0.0 230 231It 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 232install a specific commit: 233 234.. code-block:: bash 235 236 $ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25 237 238Installing multiple roles from a file 239------------------------------------- 240 241You can install multiple roles by including the roles in a :file:`requirements.yml` file. The format of the file is YAML, and the 242file extension must be either *.yml* or *.yaml*. 243 244Use the following command to install roles included in :file:`requirements.yml:` 245 246.. code-block:: bash 247 248 $ ansible-galaxy install -r requirements.yml 249 250Again, the extension is important. If the *.yml* extension is left off, the ``ansible-galaxy`` CLI assumes the file is in an older, now deprecated, 251"basic" format. 252 253Each role in the file will have one or more of the following attributes: 254 255 src 256 The source of the role. Use the format *namespace.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing 257 to a repository within a git based SCM. See the examples below. This is a required attribute. 258 scm 259 Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*. 260 version: 261 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*. 262 name: 263 Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults 264 to the name of the repository. 265 266Use the following example as a guide for specifying roles in *requirements.yml*: 267 268.. code-block:: yaml 269 270 # from galaxy 271 - name: yatesr.timezone 272 273 # from locally cloned git repository (git+file:// requires full paths) 274 - src: git+file:///home/bennojoy/nginx 275 276 # from GitHub 277 - src: https://github.com/bennojoy/nginx 278 279 # from GitHub, overriding the name and specifying a specific tag 280 - name: nginx_role 281 src: https://github.com/bennojoy/nginx 282 version: master 283 284 # from GitHub, specifying a specific commit hash 285 - src: https://github.com/bennojoy/nginx 286 version: "ee8aa41" 287 288 # from a webserver, where the role is packaged in a tar.gz 289 - name: http-role-gz 290 src: https://some.webserver.example.com/files/master.tar.gz 291 292 # from a webserver, where the role is packaged in a tar.bz2 293 - name: http-role-bz2 294 src: https://some.webserver.example.com/files/master.tar.bz2 295 296 # from a webserver, where the role is packaged in a tar.xz (Python 3.x only) 297 - name: http-role-xz 298 src: https://some.webserver.example.com/files/master.tar.xz 299 300 # from Bitbucket 301 - src: git+https://bitbucket.org/willthames/git-ansible-galaxy 302 version: v1.4 303 304 # from Bitbucket, alternative syntax and caveats 305 - src: https://bitbucket.org/willthames/hg-ansible-galaxy 306 scm: hg 307 308 # from GitLab or other git-based scm, using git+ssh 309 - src: git@gitlab.company.com:mygroup/ansible-base.git 310 scm: git 311 version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value 312 313.. warning:: 314 315 Embedding credentials into a SCM URL is not secure. Make sure to use safe auth options for security reasons. For example, use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_, `netrc <https://linux.die.net/man/5/netrc>`_ or `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_/`url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in Git config to prevent your creds from being exposed in logs. 316 317Installing roles and collections from the same requirements.yml file 318--------------------------------------------------------------------- 319 320You can install roles and collections from the same requirements files, with some caveats. 321 322.. code-block:: yaml 323 324 --- 325 roles: 326 # Install a role from Ansible Galaxy. 327 - name: geerlingguy.java 328 version: 1.9.6 329 330 collections: 331 # Install a collection from Ansible Galaxy. 332 - name: geerlingguy.php_roles 333 version: 0.9.3 334 source: https://galaxy.ansible.com 335 336.. note:: 337 While both roles and collections can be specified in one requirements file, they need to be installed separately. 338 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. 339 340Installing multiple roles from multiple files 341--------------------------------------------- 342 343For large projects, the ``include`` directive in a :file:`requirements.yml` file provides the ability to split a large file into multiple smaller files. 344 345For example, a project may have a :file:`requirements.yml` file, and a :file:`webserver.yml` file. 346 347Below are the contents of the :file:`webserver.yml` file: 348 349.. code-block:: bash 350 351 # from github 352 - src: https://github.com/bennojoy/nginx 353 354 # from Bitbucket 355 - src: git+http://bitbucket.org/willthames/git-ansible-galaxy 356 version: v1.4 357 358The following shows the contents of the :file:`requirements.yml` file that now includes the :file:`webserver.yml` file: 359 360.. code-block:: bash 361 362 # from galaxy 363 - name: yatesr.timezone 364 - include: <path_to_requirements>/webserver.yml 365 366To install all the roles from both files, pass the root file, in this case :file:`requirements.yml` on the 367command line, as follows: 368 369.. code-block:: bash 370 371 $ ansible-galaxy install -r requirements.yml 372 373.. _galaxy_dependencies: 374 375Dependencies 376------------ 377 378Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed to the ``roles_path``. 379 380There are two ways to define the dependencies of a role: 381 382* using ``meta/requirements.yml`` 383* using ``meta/main.yml`` 384 385Using ``meta/requirements.yml`` 386^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 387 388.. versionadded:: 2.10 389 390You can create the file ``meta/requirements.yml`` and define dependencies in the same format used for :file:`requirements.yml` described in the `Installing multiple roles from a file`_ section. 391 392From there, you can import or include the specified roles in your tasks. 393 394Using ``meta/main.yml`` 395^^^^^^^^^^^^^^^^^^^^^^^ 396 397Alternatively, you can specify role dependencies in the ``meta/main.yml`` file by providing a list of roles under the ``dependencies`` section. If the source of a role is Galaxy, you can simply specify the role in 398the format ``namespace.role_name``. You can also use the more complex format in :file:`requirements.yml`, allowing you to provide ``src``, ``scm``, ``version``, and ``name``. 399 400Dependencies installed that way, depending on other factors described below, will also be executed **before** this role is executed during play execution. 401To better understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`. 402 403The following shows an example ``meta/main.yml`` file with dependent roles: 404 405.. code-block:: yaml 406 407 --- 408 dependencies: 409 - geerlingguy.java 410 411 galaxy_info: 412 author: geerlingguy 413 description: Elasticsearch for Linux. 414 company: "Midwestern Mac, LLC" 415 license: "license (BSD, MIT)" 416 min_ansible_version: 2.4 417 platforms: 418 - name: EL 419 versions: 420 - all 421 - name: Debian 422 versions: 423 - all 424 - name: Ubuntu 425 versions: 426 - all 427 galaxy_tags: 428 - web 429 - system 430 - monitoring 431 - logging 432 - lucene 433 - elk 434 - elasticsearch 435 436Tags 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. 437 438Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on 439what tags and conditionals are applied. 440 441If the source of a role is Galaxy, specify the role in the format *namespace.role_name*: 442 443.. code-block:: yaml 444 445 dependencies: 446 - geerlingguy.apache 447 - geerlingguy.ansible 448 449 450Alternately, you can specify the role dependencies in the complex form used in :file:`requirements.yml` as follows: 451 452.. code-block:: yaml 453 454 dependencies: 455 - name: geerlingguy.ansible 456 - name: composer 457 src: git+https://github.com/geerlingguy/ansible-role-composer.git 458 version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 459 460.. note:: 461 462 Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the 463 ``namespace.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail. 464 465List installed roles 466-------------------- 467 468Use ``list`` to show the name and version of each role installed in the *roles_path*. 469 470.. code-block:: bash 471 472 $ ansible-galaxy list 473 - ansible-network.network-engine, v2.7.2 474 - ansible-network.config_manager, v2.6.2 475 - ansible-network.cisco_nxos, v2.7.1 476 - ansible-network.vyos, v2.7.3 477 - ansible-network.cisco_ios, v2.7.0 478 479Remove an installed role 480------------------------ 481 482Use ``remove`` to delete a role from *roles_path*: 483 484.. code-block:: bash 485 486 $ ansible-galaxy remove namespace.role_name 487 488 489.. seealso:: 490 :ref:`collections` 491 Shareable collections of modules, playbooks and roles 492 :ref:`playbooks_reuse_roles` 493 Reusable tasks, handlers, and other files in a known directory structure 494