Skip to content

Commit

Permalink
Prepare Galaxy guides for GalaxyNG (#388) (#508)
Browse files Browse the repository at this point in the history 
(cherry picked from commit 17c138a)

Co-authored-by: Sandra McCann <[email protected]>
  • Loading branch information
@oraNod @samccann
oraNod and samccann authored Oct 4, 2023
1 parent e6785d8 commit 17b2098
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 83 deletions.
65 changes: 18 additions & 47 deletions docs/docsite/rst/galaxy/dev_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Galaxy Developer Guide
**********************

You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formatted in pre-packaged units of work such as :ref:`roles <playbooks_reuse_roles>`, and new in Galaxy 3.2, :ref:`collections <collections>`.
You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formatted in pre-packaged units of work such as :ref:`roles <playbooks_reuse_roles>`, and :ref:`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.

.. contents::
Expand All @@ -31,22 +31,23 @@ Use the ``init`` command to initialize the base structure of a new role, saving

.. code-block:: bash
$ ansible-galaxy init role_name
$ ansible-galaxy role 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
tasks/
main.yml
templates/
tests/
inventory
Expand Down Expand Up @@ -98,41 +99,24 @@ 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.
To create an authentication token:

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 want 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.
#. Click :guilabel:`Collections > API Token`.
#. Click :guilabel:`Load Token` and then copy it.
#. Save your token in the path set in the :ref:`GALAXY_TOKEN_PATH`.


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.
The ``import``command requires that you authenticate with the API token. You can include it in your ``ansible.cfg`` file or use the ``--token`` command option. You are only allowed to remove roles where you have access to the repository in GitHub.

Use the following to import to role:
To import a new role:

.. code-block:: bash
$ ansible-galaxy import github_user github_repo
$ ansible-galaxy role 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:

Expand All @@ -151,31 +135,18 @@ By default the command will wait for Galaxy to complete the import process, disp
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*.
See :ref:`ansible-galaxy` for other command options.

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.
The ``delete`` command requires that you authenticate with the API token. You can include it in your ``ansible.cfg`` file or use the ``--token`` command option. 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
$ ansible-galaxy role delete github_user github_repo
This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.

Expand All @@ -186,12 +157,12 @@ 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
You create the integration using the ``setup`` command with your API token. 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
$ ansible-galaxy role 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.
Expand All @@ -214,7 +185,7 @@ Use the ``--list`` option to display your Travis integrations:

.. code-block:: bash
$ ansible-galaxy setup --list
$ ansible-galaxy setup --list travis github_user github_repo xxx-travis-token-xxx
ID Source Repo
Expand All @@ -230,7 +201,7 @@ Use the ``--remove`` option to disable and remove a Travis integration:

.. code-block:: bash
$ ansible-galaxy setup --remove ID
$ ansible-galaxy role setup --remove ID
Provide the ID of the integration to be disabled. You can find the ID by using the ``--list`` option.

Expand Down
73 changes: 37 additions & 36 deletions docs/docsite/rst/galaxy/user_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ 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 collections and 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 :ref:`roles <playbooks_reuse_roles>`, and :ref:`collections <collections>`.
The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins.
The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. See the `Galaxy documentation <https://ansible.readthedocs.io/projects/galaxy-ng/en/latest/>`_ for full details on Galaxy.

.. contents::
:local:
Expand All @@ -20,9 +20,8 @@ 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`.
#. Click :guilabel:`Collections > Collections` in the left-hand navigation.
#. Type in your search term. You can filter by keyword, tags, and namespaces.

Galaxy presents a list of collections that match your search criteria.

Expand All @@ -37,23 +36,32 @@ See :ref:`collections` for complete details on installing and using collections.
Finding roles on Galaxy
=======================

Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
To find standalone roles (that is roles that are not part of a collection):

#. Click :guilabel:`Roles > Roles` in the left-hand navigation.
#. Type in your search term. You can filter by keyword, tags, and namespaces.

Galaxy presents a list of roles that match your search criteria.

You can optionally search the Galaxy database by tags, platforms, author and multiple keywords using the ``ansible-galaxy`` CLI command.

.. code-block:: bash
$ ansible-galaxy search elasticsearch --author geerlingguy
$ ansible-galaxy role 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:
Found 6 roles matching your search:
Name Description
---- -----------
Name Description
---- -----------
geerlingguy.elasticsearch Elasticsearch for Linux.
geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.
geerlingguy.filebeat Filebeat for Linux.
geerlingguy.fluentd Fluentd for Linux.
geerlingguy.kibana Kibana for Linux.
Get more information about a role
---------------------------------
Expand All @@ -62,7 +70,7 @@ Use the ``info`` command to view more detail about a specific role:

.. code-block:: bash
$ ansible-galaxy info username.role_name
$ ansible-galaxy role info username.role_name
This returns everything found in Galaxy for the role:

Expand All @@ -78,24 +86,21 @@ This returns everything found in Galaxy for the role:
created: 2015-12-08T14:17:52.773Z
download_count: 1
forks_count: 0
github_branch:
github_branch: main
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
min_ansible_version: 2.15
modified: YYYY-MM-DDTHH:MM:SS.000Z
namespace: username
open_issues_count: 0
path: /Users/username/projects/roles
scm: None
src: username.repo_name
role_type: ANS
stargazers_count: 0
travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=main
version:
watchers_count: 1
.. _installing_galaxy_roles:
Expand All @@ -107,8 +112,8 @@ The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to
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*. If you run your own internal Galaxy server
and 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
the Galaxy server value in your ``ansible.cfg`` file to use it . For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`.
and want to use it instead of the default one, pass the ``--server`` option followed by the address of this galaxy server. You can set this option permanently by setting
the Galaxy server value in your ``ansible.cfg`` file. See :ref:`galaxy_server` for details on setting the value in *ansible.cfg* .


Installing roles
Expand All @@ -118,7 +123,7 @@ Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <h

.. code-block:: bash
$ ansible-galaxy install namespace.role_name
$ ansible-galaxy role install namespace.role_name
Setting where to install roles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -135,7 +140,7 @@ The following provides an example of using ``--roles-path`` to install the role

.. code-block:: bash
$ ansible-galaxy install --roles-path . geerlingguy.apache
$ ansible-galaxy role install --roles-path . geerlingguy.apache
.. seealso::

Expand All @@ -153,20 +158,19 @@ 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 /<namespace>/<role name>. For example, to view the role geerlingguy.apache, go to `<https://galaxy.ansible.com/geerlingguy/apache>`_.

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,1.0.0
$ ansible-galaxy role install geerlingguy.apache,3.2.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
$ ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
Installing multiple roles from a file
-------------------------------------
Expand Down Expand Up @@ -245,7 +249,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
.. warning::

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.
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 credentials from being exposed in logs.

Installing roles and collections from the same requirements.yml file
---------------------------------------------------------------------
Expand All @@ -262,8 +266,8 @@ You can install roles and collections from the same requirements files
collections:
# Install a collection from Ansible Galaxy.
- name: geerlingguy.php_roles
version: 0.9.3
- name: community.general
version: ">=7.0.0"
source: https://galaxy.ansible.com
Installing multiple roles from multiple files
Expand Down Expand Up @@ -297,7 +301,7 @@ command line, as follows:

.. code-block:: bash
$ ansible-galaxy install -r requirements.yml
$ ansible-galaxy role install -r requirements.yml
.. _galaxy_dependencies:

Expand Down Expand Up @@ -398,12 +402,9 @@ Use ``list`` to show the name and version of each role installed in the *roles_p

.. 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
$ ansible-galaxy role list
- namespace-1.foo, v2.7.2
- namespace2.bar, v2.6.2
Remove an installed role
------------------------
Expand All @@ -412,7 +413,7 @@ Use ``remove`` to delete a role from *roles_path*:

.. code-block:: bash
$ ansible-galaxy remove namespace.role_name
$ ansible-galaxy role remove namespace.role_name
.. seealso::
Expand Down

0 comments on commit 17b2098

Please sign in to comment.