diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index a436c438b16..142b334cb3e 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -275,7 +275,11 @@ You can link from your module documentation to other module docs, other resource .. note:: - - To refer a collection of modules, use ``C(..)``, e.g. ``Refer to the C(win_*) modules.`` + For modules in a collection, you can only use ``L()`` and ``M()`` for content within that collection. Use ``U()`` to refer to content in a different collection. + +.. note:: + + - To refer a group of modules, use ``C(..)``, e.g. ``Refer to the C(win_*) modules.`` - Because it stands out better, using ``seealso`` is preferred for general references over the use of notes or adding links to the description. .. _module_docs_fragments: diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst b/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst new file mode 100644 index 00000000000..db135374acc --- /dev/null +++ b/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst @@ -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 `_. + +See :ref:`developing_collections` for details on how to create collections. diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst b/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst new file mode 100644 index 00000000000..bca976287ce --- /dev/null +++ b/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst @@ -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 `_, 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 `_. 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 `_. 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 `_. 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 `_. + +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 `_ + 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/index.rst b/docs/docsite/rst/galaxy/dev_guide/index.rst new file mode 100644 index 00000000000..468b530fb13 --- /dev/null +++ b/docs/docsite/rst/galaxy/dev_guide/index.rst @@ -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 `_, 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/finding_collections.rst b/docs/docsite/rst/galaxy/user_guide/finding_collections.rst new file mode 100644 index 00000000000..356e8e0146f --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide/finding_collections.rst @@ -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. diff --git a/docs/docsite/rst/galaxy/user_guide/finding_roles.rst b/docs/docsite/rst/galaxy/user_guide/finding_roles.rst new file mode 100644 index 00000000000..4d52fb74db8 --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide/finding_roles.rst @@ -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 diff --git a/docs/docsite/rst/galaxy/user_guide/index.rst b/docs/docsite/rst/galaxy/user_guide/index.rst new file mode 100644 index 00000000000..0aa0a371be5 --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide/index.rst @@ -0,0 +1,26 @@ +.. _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 new file mode 100644 index 00000000000..4d1e4e5c210 --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide/installing_collections.rst @@ -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 diff --git a/docs/docsite/rst/galaxy/user_guide/installing_roles.rst b/docs/docsite/rst/galaxy/user_guide/installing_roles.rst new file mode 100644 index 00000000000..172df19d809 --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide/installing_roles.rst @@ -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 `_ +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 5a22b660134..ce4e8cf8b54 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -60,13 +60,20 @@ Ansible releases a new major release of Ansible approximately three to four time network/index +.. toctree:: + :maxdepth: 2 + :caption: Ansible Galaxy + + galaxy/user_guide/index + galaxy/dev_guide/index + + .. toctree:: :maxdepth: 1 :caption: Reference & Appendices ../modules/modules_by_category reference_appendices/playbooks_keywords - reference_appendices/galaxy reference_appendices/common_return_values reference_appendices/config reference_appendices/general_precedence diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index a0c18cbde82..5f376b5881a 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -59,7 +59,7 @@ In Ansible 2.7 and older:: Module option conversion to string ---------------------------------- -Beginning in version 2.8, Ansible will warn if a module expects a string, but a non-string value is passed and automatically converted to a string. This highlights potential problems where, for example, a ``yes`` or ``true`` (parsed as truish boolean value) would be converted to the string ``'True'``, or where a version number ``1.10`` (parsed as float value) would be converted to ``'1.0'``. Such conversions can result in unexpected behavior depending on context. +Beginning in version 2.8, Ansible will warn if a module expects a string, but a non-string value is passed and automatically converted to a string. This highlights potential problems where, for example, a ``yes`` or ``true`` (parsed as truish boolean value) would be converted to the string ``'True'``, or where a version number ``1.10`` (parsed as float value) would be converted to ``'1.1'``. Such conversions can result in unexpected behavior depending on context. This behavior can be changed to be an error or to be ignored by setting the ``ANSIBLE_STRING_CONVERSION_ACTION`` environment variable, or by setting the ``string_conversion_action`` configuration in the ``defaults`` section of ``ansible.cfg``. diff --git a/docs/docsite/rst/reference_appendices/galaxy.rst b/docs/docsite/rst/reference_appendices/galaxy.rst deleted file mode 100644 index e37a9603d89..00000000000 --- a/docs/docsite/rst/reference_appendices/galaxy.rst +++ /dev/null @@ -1,529 +0,0 @@ -.. _ansible_galaxy: - -Ansible Galaxy -++++++++++++++ - -*Ansible Galaxy* refers to the `Galaxy `_ website where users can share roles, and to a command line tool for installing, -creating and managing roles. - -.. contents:: Topics - -The Website -``````````` - -`Galaxy `_, 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 `_. - -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 `_ -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 `_ - -:: - - $ 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: /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 `_, 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 `_. 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 `_. 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 `_. 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 `_. - -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 `_ - Questions? Help? Ideas? Stop by the list on Google Groups - `irc.freenode.net `_ - #ansible IRC chat channel diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst index ae830fe0596..e893c9d0458 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_vmware_http.rst @@ -85,7 +85,7 @@ This is a generic example to show how Ansible can be utilized to consume VMware options: 'Config.HostAgent.log.level': 'error' validate_certs: no - with_items: "{{ vchosts.json.value }}" + loop: "{{ vchosts.json.value }}" register: host_config_results diff --git a/docs/docsite/rst/shared_snippets/galaxy_server_list.txt b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt new file mode 100644 index 00000000000..5e9f94f0c45 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt @@ -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. diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt new file mode 100644 index 00000000000..f721feda1ac --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_collections.txt @@ -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/ + + +See :ref:`collection_structure` for details on the collection directory structure. diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt new file mode 100644 index 00000000000..eb535d809f8 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt @@ -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. diff --git a/docs/docsite/rst/shared_snippets/installing_older_collection.txt b/docs/docsite/rst/shared_snippets/installing_older_collection.txt new file mode 100644 index 00000000000..95e1b6a2b59 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_older_collection.txt @@ -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. diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index 163aa2f206e..aea06332b0f 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -17,178 +17,29 @@ You can install and use collections through `Ansible Galaxy - - -See :ref:`collection_structure` for details on the collection directory structure. +.. include:: ../shared_snippets/installing_collections.txt .. _collections_older_version: Installing an older version of a collection ------------------------------------------- -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. - +.. include:: ../shared_snippets/installing_older_collection.txt .. _collection_requirements_file: Install multiple collections with a requirements file ----------------------------------------------------- -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. +.. include:: ../shared_snippets/installing_multiple_collections.txt -.. 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. .. _galaxy_server_config: Galaxy server configuration list -------------------------------- -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. +.. include:: ../shared_snippets/galaxy_server_list.txt .. _using_collections: diff --git a/lib/ansible/modules/cloud/ovirt/ovirt_vm.py b/lib/ansible/modules/cloud/ovirt/ovirt_vm.py index 9980ec4d102..25d2bb519e1 100644 --- a/lib/ansible/modules/cloud/ovirt/ovirt_vm.py +++ b/lib/ansible/modules/cloud/ovirt/ovirt_vm.py @@ -853,6 +853,8 @@ notes: I(REBOOTING), I(POWERING_UP), I(RESTORING_STATE), I(WAIT_FOR_LAUNCH). If VM is in I(PAUSED) or I(DOWN) state, we start the VM. Then we suspend the VM. When user specify I(absent) C(state), we forcibly stop the VM in any state and remove it. + - "If you update a VM parameter that requires a reboot, the oVirt engine always creates a new snapshot for the VM, + and an Ansible playbook will report this as changed." extends_documentation_fragment: ovirt ''' diff --git a/lib/ansible/modules/files/ini_file.py b/lib/ansible/modules/files/ini_file.py index bc7e9e652ad..1b650a1ce8b 100644 --- a/lib/ansible/modules/files/ini_file.py +++ b/lib/ansible/modules/files/ini_file.py @@ -59,10 +59,6 @@ options: the original file back if you somehow clobbered it incorrectly. type: bool default: no - others: - description: - - All arguments accepted by the M(file) module also work here. - type: str state: description: - If set to C(absent) the option or section will be removed if present instead of created. diff --git a/lib/ansible/modules/files/synchronize.py b/lib/ansible/modules/files/synchronize.py index 4d4f50f16c0..e4c520b7cf7 100644 --- a/lib/ansible/modules/files/synchronize.py +++ b/lib/ansible/modules/files/synchronize.py @@ -83,6 +83,7 @@ options: description: - Delete files in C(dest) that don't exist (after transfer, not before) in the C(src) path. - This option requires C(recursive=yes). + - This option ignores excluded files and behaves like the rsync opt --delete-excluded. type: bool default: no dirs: diff --git a/lib/ansible/modules/files/unarchive.py b/lib/ansible/modules/files/unarchive.py index 58a69085d2b..03d6a5bcc47 100644 --- a/lib/ansible/modules/files/unarchive.py +++ b/lib/ansible/modules/files/unarchive.py @@ -72,6 +72,8 @@ options: extra_opts: description: - Specify additional options by passing in an array. + - Each space-separated command-line option should be a new element of the array. See examples. + - Command-line options with multiple elements must use multiple lines in the array, one for each element. type: list default: "" version_added: "2.1" diff --git a/lib/ansible/modules/network/sros/sros_config.py b/lib/ansible/modules/network/sros/sros_config.py index 23bdc8b824a..ebb79bc1346 100644 --- a/lib/ansible/modules/network/sros/sros_config.py +++ b/lib/ansible/modules/network/sros/sros_config.py @@ -114,7 +114,7 @@ options: - This argument specifies whether or not to collect all defaults when getting the remote device running config. When enabled, the module will get the current config by issuing the command - C(show running-config all). + C(admin display-config detail). type: bool default: 'no' aliases: ['detail'] diff --git a/lib/ansible/modules/system/nosh.py b/lib/ansible/modules/system/nosh.py index 72d2cc7366b..8b09fad082f 100644 --- a/lib/ansible/modules/system/nosh.py +++ b/lib/ansible/modules/system/nosh.py @@ -125,7 +125,7 @@ preset: description: whether the enabled status reflects the one set in the relevant C(*.preset) file returned: success type: bool - sample: False + sample: 'False' state: description: service process run state, C(None) if the service is not loaded and will not be started returned: if state option is used @@ -135,56 +135,143 @@ status: description: a dictionary with the key=value pairs returned by `system-control show-json` or C(None) if the service is not loaded returned: success type: complex - contains: { - "After": [ - "/etc/service-bundles/targets/basic", - "../sshdgenkeys", - "log" - ], - "Before": [ - "/etc/service-bundles/targets/shutdown" - ], - "Conflicts": [], - "DaemontoolsEncoreState": "running", - "DaemontoolsState": "up", - "Enabled": true, - "LogService": "../cyclog@sshd", - "MainPID": 661, - "Paused": false, - "ReadyAfterRun": false, - "RemainAfterExit": false, - "Required-By": [], - "RestartExitStatusCode": 0, - "RestartExitStatusNumber": 0, - "RestartTimestamp": 4611686019935648081, - "RestartUTCTimestamp": 1508260140, - "RunExitStatusCode": 0, - "RunExitStatusNumber": 0, - "RunTimestamp": 4611686019935648081, - "RunUTCTimestamp": 1508260140, - "StartExitStatusCode": 1, - "StartExitStatusNumber": 0, - "StartTimestamp": 4611686019935648081, - "StartUTCTimestamp": 1508260140, - "StopExitStatusCode": 0, - "StopExitStatusNumber": 0, - "StopTimestamp": 4611686019935648081, - "StopUTCTimestamp": 1508260140, - "Stopped-By": [ - "/etc/service-bundles/targets/shutdown" - ], - "Timestamp": 4611686019935648081, - "UTCTimestamp": 1508260140, - "Want": "nothing", - "Wanted-By": [ - "/etc/service-bundles/targets/server", - "/etc/service-bundles/targets/sockets" - ], - "Wants": [ - "/etc/service-bundles/targets/basic", - "../sshdgenkeys" - ] - } + contains: + After: + returned: success + type: list + sample: ["/etc/service-bundles/targets/basic","../sshdgenkeys", "log"] + Before: + returned: success + type: list + sample: ["/etc/service-bundles/targets/shutdown"] + Conflicts: + returned: success + type: list + sample: '[]' + DaemontoolsEncoreState: + returned: success + type: str + sample: "running" + DaemontoolsState: + returned: success + type: str + sample: "up" + Enabled: + returned: success + type: bool + sample: True + LogService: + returned: success + type: str + sample: "../cyclog@sshd" + MainPID: + returned: success + type: int + sample: 661 + Paused: + returned: success + type: bool + sample: 'False' + ReadyAfterRun: + returned: success + type: bool + sample: 'False' + RemainAfterExit: + returned: success + type: bool + sample: 'False' + Required-By: + returned: success + type: list + sample: '[]' + RestartExitStatusCode: + returned: success + type: int + sample: '0' + RestartExitStatusNumber: + returned: success + type: int + sample: '0' + RestartTimestamp: + returned: success + type: int + sample: 4611686019935648081 + RestartUTCTimestamp: + returned: success + type: int + sample: 1508260140 + RunExitStatusCode: + returned: success + type: int + sample: '0' + RunExitStatusNumber: + returned: success + type: int + sample: '0' + RunTimestamp: + returned: success + type: int + sample: 4611686019935648081 + RunUTCTimestamp: + returned: success + type: int + sample: 1508260140 + StartExitStatusCode: + returned: success + type: int + sample: 1 + StartExitStatusNumber: + returned: success + type: int + sample: '0' + StartTimestamp: + returned: success + type: int + sample: 4611686019935648081 + StartUTCTimestamp: + returned: success + type: int + sample: 1508260140 + StopExitStatusCode: + returned: success + type: int + sample: '0' + StopExitStatusNumber: + returned: success + type: int + sample: '0' + StopTimestamp: + returned: success + type: int + sample: 4611686019935648081 + StopUTCTimestamp: + returned: success + type: int + sample: 1508260140 + Stopped-By: + returned: success + type: list + sample: ["/etc/service-bundles/targets/shutdown"] + Timestamp: + returned: success + type: int + sample: 4611686019935648081 + UTCTimestamp: + returned: success + type: int + sample: 1508260140 + Want: + returned: success + type: str + sample: "nothing" + Wanted-By: + returned: success + type: list + sample: ["/etc/service-bundles/targets/server","/etc/service-bundles/targets/sockets"] + Wants: + returned: success + type: list + sample: ["/etc/service-bundles/targets/basic","../sshdgenkeys"] user: description: whether the user-level service manager is called returned: success diff --git a/lib/ansible/modules/system/ufw.py b/lib/ansible/modules/system/ufw.py index 573ee07e64a..4fe7e8ef509 100644 --- a/lib/ansible/modules/system/ufw.py +++ b/lib/ansible/modules/system/ufw.py @@ -149,7 +149,7 @@ EXAMPLES = r''' - name: Set logging ufw: - logging: on + logging: 'on' # Sometimes it is desirable to let the sender know when traffic is # being denied, rather than simply ignoring it. In these cases, use @@ -185,7 +185,7 @@ EXAMPLES = r''' - name: Deny all access to port 53 ufw: rule: deny - port: 53 + port: '53' - name: Allow port range 60000-61000 ufw: @@ -196,7 +196,7 @@ EXAMPLES = r''' - name: Allow all access to tcp port 80 ufw: rule: allow - port: 80 + port: '80' proto: tcp - name: Allow all access from RFC1918 networks to this host @@ -213,7 +213,7 @@ EXAMPLES = r''' rule: deny proto: udp src: 1.2.3.4 - port: 514 + port: '514' comment: Block syslog - name: Allow incoming access to eth0 from 1.2.3.5 port 5469 to 1.2.3.4 port 5469 @@ -223,9 +223,9 @@ EXAMPLES = r''' direction: in proto: udp src: 1.2.3.5 - from_port: 5469 + from_port: '5469' dest: 1.2.3.4 - to_port: 5469 + to_port: '5469' # Note that IPv6 must be enabled in /etc/default/ufw for IPv6 firewalling to work. - name: Deny all traffic from the IPv6 2001:db8::/32 to tcp port 25 on this host @@ -233,14 +233,14 @@ EXAMPLES = r''' rule: deny proto: tcp src: 2001:db8::/32 - port: 25 + port: '25' - name: Deny all IPv6 traffic to tcp port 20 on this host # this should be the first IPv6 rule ufw: rule: deny proto: tcp - port: 20 + port: '20' to_ip: "::" insert: 0 insert_relative_to: first-ipv6 @@ -254,7 +254,7 @@ EXAMPLES = r''' ufw: rule: deny proto: tcp - port: 20 + port: '20' to_ip: "::" insert: -1 insert_relative_to: last-ipv4 diff --git a/lib/ansible/plugins/doc_fragments/ovirt_info.py b/lib/ansible/plugins/doc_fragments/ovirt_info.py index 2b753e4009c..b16356a230c 100644 --- a/lib/ansible/plugins/doc_fragments/ovirt_info.py +++ b/lib/ansible/plugins/doc_fragments/ovirt_info.py @@ -12,7 +12,8 @@ options: fetch_nested: description: - If I(yes) the module will fetch additional data from the API. - - It will fetch IDs of the VMs disks, snapshots, etc. User can configure to fetch other + - It will fetch only IDs of nested entity. It doesn't fetch multiple levels of nested attributes. + Only the attributes of the current entity. User can configure to fetch other attributes of the nested entities by specifying C(nested_attributes). type: bool version_added: "2.3" diff --git a/test/sanity/ignore.txt b/test/sanity/ignore.txt index 1e9594f5c63..2d95c52ffca 100644 --- a/test/sanity/ignore.txt +++ b/test/sanity/ignore.txt @@ -2285,7 +2285,6 @@ lib/ansible/modules/files/file.py validate-modules:undocumented-parameter lib/ansible/modules/files/file.py validate-modules:doc-default-does-not-match-spec lib/ansible/modules/files/find.py use-argspec-type-path # fix needed lib/ansible/modules/files/find.py validate-modules:parameter-type-not-in-doc -lib/ansible/modules/files/ini_file.py validate-modules:nonexistent-parameter-documented lib/ansible/modules/files/iso_extract.py validate-modules:doc-default-does-not-match-spec lib/ansible/modules/files/lineinfile.py validate-modules:nonexistent-parameter-documented lib/ansible/modules/files/lineinfile.py validate-modules:doc-default-does-not-match-spec