summaryrefslogtreecommitdiffstats
path: root/docs/docsite/rst/shared_snippets
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docsite/rst/shared_snippets')
-rw-r--r--docs/docsite/rst/shared_snippets/basic_concepts.txt69
-rw-r--r--docs/docsite/rst/shared_snippets/download_tarball_collections.txt8
-rw-r--r--docs/docsite/rst/shared_snippets/galaxy_server_list.txt78
-rw-r--r--docs/docsite/rst/shared_snippets/installing_collections.txt72
-rw-r--r--docs/docsite/rst/shared_snippets/installing_collections_file.rst24
-rw-r--r--docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt105
-rw-r--r--docs/docsite/rst/shared_snippets/installing_multiple_collections.txt77
-rw-r--r--docs/docsite/rst/shared_snippets/installing_older_collection.txt25
8 files changed, 458 insertions, 0 deletions
diff --git a/docs/docsite/rst/shared_snippets/basic_concepts.txt b/docs/docsite/rst/shared_snippets/basic_concepts.txt
new file mode 100644
index 0000000..f2648cb
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/basic_concepts.txt
@@ -0,0 +1,69 @@
+Control node
+============
+The machine from which you run the Ansible CLI tools (``ansible-playbook`` , ``ansible``, ``ansible-vault`` and others).
+You can use any computer that meets the software requirements as a control node - laptops, shared desktops, and servers can all run Ansible.
+Multiple control nodes are possible, but Ansible itself does not coordinate across them, see ``AAP`` for such features.
+
+
+Managed nodes
+=============
+Also referred to as 'hosts', these are the target devices (servers, network appliances or any computer) you aim to manage with Ansible.
+Ansible is not normally installed on managed nodes, unless you are using ``ansible-pull``, but this is rare and not the recommended setup.
+
+
+Inventory
+=========
+A list of managed nodes provided by one or more 'inventory sources'. Your inventory can specify information specific to each node, like IP address.
+It is also used for assigning groups, that both allow for node selection in the Play and bulk variable assignment.
+To learn more about inventory, see :ref:`the Working with Inventory<intro_inventory>` section. Sometimes an inventory source file is also referred to as a 'hostfile'.
+
+
+Playbooks
+=========
+They contain Plays (which are the basic unit of Ansible execution). This is both an 'execution concept' and how we describe the files on which ``ansible-playbook`` operates.
+Playbooks are written in YAML and are easy to read, write, share and understand. To learn more about playbooks, see :ref:`about_playbooks`.
+
+Plays
+-----
+The main context for Ansible execution, this playbook object maps managed nodes (hosts) to tasks.
+The Play contains variables, roles and an ordered lists of tasks and can be run repeatedly.
+It basically consists of an implicit loop over the mapped hosts and tasks and defines how to iterate over them.
+
+Roles
+.....
+A limited distribution of reusable Ansible content (tasks, handlers, variables, plugins, templates and files) for use inside of a Play.
+To use any Role resource, the Role itself must be imported into the Play.
+
+Tasks
+.....
+The definition of an 'action' to be applied to the managed host. Tasks must always be contained in a Play, directly or indirectly (Role, or imported/included task list file).
+You can execute a single task once with an ad hoc command using ``ansible`` or ``ansible-console`` (both create a virtual Play).
+
+Handlers
+........
+A special form of a Task, that only executes when notified by a previous task which resulted in a 'changed' status.
+
+
+Modules
+=======
+The code or binaries that Ansible copies to and executes on each managed node (when needed) to accomplish the action defined in each Task.
+Each module has a particular use, from administering users on a specific type of database to managing VLAN interfaces on a specific type of network device.
+You can invoke a single module with a task, or invoke several different modules in a playbook.
+Ansible modules are grouped in collections. For an idea of how many collections Ansible includes, see the :ref:`list_of_collections`.
+
+
+Plugins
+=======
+Pieces of code that expand Ansible's core capabilities, they can control how you connect to a managed node (connection plugins),
+manipulate data (filter plugins) and even control what is displayed in the console (callback plugins).
+See :ref:`working_with_plugins` for details.
+
+
+Collections
+===========
+A format in which Ansible content is distributed that can contain playbooks, roles, modules, and plugins. You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_. To learn more about collections, see :ref:`collections`. Collection resources can be used independently and discretely from each other.
+
+
+AAP
+===
+Short for 'Ansible Automation Platform'. This is a product that includes enterprise level features and integrates many tools of the Ansible ecosystem: ansible-core, awx, galaxyNG, and so on.
diff --git a/docs/docsite/rst/shared_snippets/download_tarball_collections.txt b/docs/docsite/rst/shared_snippets/download_tarball_collections.txt
new file mode 100644
index 0000000..045004b
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/download_tarball_collections.txt
@@ -0,0 +1,8 @@
+
+
+To download the collection tarball from Galaxy for offline use:
+
+#. Navigate to the collection page.
+#. Click on :guilabel:`Download tarball`.
+
+You may also need to manually download any dependent collections.
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 0000000..9991d85
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/galaxy_server_list.txt
@@ -0,0 +1,78 @@
+
+
+By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`).
+
+You can use either option below to configure ``ansible-galaxy collection`` to use other servers (such as a custom Galaxy server):
+
+* Set the server list in the :ref:`galaxy_server_list` configuration option in :ref:`ansible_configuration_settings_locations`.
+* Use the ``--server`` command line argument to limit to an individual server.
+
+To configure a Galaxy server list in ``ansible.cfg``:
+
+
+#. Add the ``server_list`` option under the ``[galaxy]`` section to one or more server names.
+#. Create a new section for each server name.
+#. Set the ``url`` option for each server name.
+#. Optionally, set the API token for each server name. Go to https://galaxy.ansible.com/me/preferences and click :guilabel:`Show API key`.
+
+.. note::
+ The ``url`` option for each server name must end with a forward slash ``/``. If you do not set the API token in your Galaxy server list, use the ``--api-key`` argument to pass in the token to the ``ansible-galaxy collection publish`` command.
+
+
+The following example shows how to configure multiple servers:
+
+.. code-block:: ini
+
+ [galaxy]
+ server_list = my_org_hub, release_galaxy, test_galaxy, my_galaxy_ng
+
+ [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_test_token
+
+ [galaxy_server.my_galaxy_ng]
+ url=http://my_galaxy_ng:8000/api/automation-hub/
+ auth_url=http://my_keycloak:8080/auth/realms/myco/protocol/openid-connect/token
+ client_id=galaxy-ng
+ token=my_keycloak_access_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 argument should match the name of the server. To use a server not in the server list, set the value to the URL to access that server (all servers in the server list will be ignored). Also you cannot use the ``--api-key`` argument for any of the predefined servers. You can only use the ``api_key`` argument if you did not define a server list or if you specify a URL in the
+ ``--server`` argument.
+
+**Galaxy server list configuration options**
+
+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, for example, ``automation_hub`` first, then ``my_org_hub``, ``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. Required.
+* ``token``: An API token key to use for authentication against the Galaxy instance. Mutually exclusive with ``username``.
+* ``username``: The username to use for basic authentication against the Galaxy instance. Mutually exclusive with ``token``.
+* ``password``: The password to use, in conjunction with ``username``, for basic authentication.
+* ``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO authentication (for example, galaxyNG). Mutually exclusive with ``username``. Requires ``token``.
+* ``validate_certs``: Whether or not to verify TLS certificates for the Galaxy server. This defaults to True unless the ``--ignore-certs`` option is provided or ``GALAXY_IGNORE_CERTS`` is configured to True.
+* ``client_id``: The Keycloak token's client_id to use for authentication. Requires ``auth_url`` and ``token``. The default ``client_id`` is cloud-services to work with Red Hat SSO.
+
+As well as defining these server options in the ``ansible.cfg`` file, you can also define them as environment variables.
+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 that use only one Galaxy server (for example, the ``publish``, ``info``, or ``install`` commands). the ``ansible-galaxy collection`` command uses the first entry in the
+``server_list``, unless you pass in an explicit server with the ``--server`` argument.
+
+.. note::
+ ``ansible-galaxy`` can seek out dependencies on other configured Galaxy instances to support the use case where a collection can depend on a collection from another 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 0000000..23f5c3e
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/installing_collections.txt
@@ -0,0 +1,72 @@
+
+
+By default, ``ansible-galaxy collection install`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the
+:file:`ansible.cfg` file under :ref:`galaxy_server`). You do not need any
+further configuration.
+
+See :ref:`Configuring the ansible-galaxy client <galaxy_server_config>` if you are using any other Galaxy server, such as Red Hat Automation Hub.
+
+To install a collection hosted in Galaxy:
+
+.. code-block:: bash
+
+ ansible-galaxy collection install my_namespace.my_collection
+
+To upgrade a collection to the latest available version from the Galaxy server you can use the ``--upgrade`` option:
+
+.. code-block:: bash
+
+ ansible-galaxy collection install my_namespace.my_collection --upgrade
+
+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
+
+You can build and install a collection from a local source directory. The ``ansible-galaxy`` utility builds the collection using the ``MANIFEST.json`` or ``galaxy.yml``
+metadata in the directory.
+
+.. code-block:: bash
+
+ ansible-galaxy collection install /path/to/collection -p ./collections
+
+You can also install multiple collections in a namespace directory.
+
+.. code-block:: text
+
+ ns/
+ ├── collection1/
+ │   ├── MANIFEST.json
+ │   └── plugins/
+ └── collection2/
+ ├── galaxy.yml
+ └── plugins/
+
+.. code-block:: bash
+
+ ansible-galaxy collection install /path/to/ns -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/<collection structure lives here>
+
+
+See :ref:`collection_structure` for details on the collection directory structure.
+
diff --git a/docs/docsite/rst/shared_snippets/installing_collections_file.rst b/docs/docsite/rst/shared_snippets/installing_collections_file.rst
new file mode 100644
index 0000000..7c4fbcd
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/installing_collections_file.rst
@@ -0,0 +1,24 @@
+Ansible can also install from a source directory in several ways:
+
+.. code-block:: yaml
+
+ collections:
+ # directory containing the collection
+ - source: ./my_namespace/my_collection/
+ type: dir
+
+ # directory containing a namespace, with collections as subdirectories
+ - source: ./my_namespace/
+ type: subdirs
+
+Ansible can also install a collection collected with ``ansible-galaxy collection build`` or downloaded from Galaxy for offline use by specifying the output file directly:
+
+.. code-block:: yaml
+
+ collections:
+ - name: /tmp/my_namespace-my_collection-1.0.0.tar.gz
+ type: file
+
+.. note::
+
+ Relative paths are calculated from the current working directory (where you are invoking ``ansible-galaxy install -r`` from). They are not taken relative to the ``requirements.yml`` file.
diff --git a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt
new file mode 100644
index 0000000..ba11d25
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt
@@ -0,0 +1,105 @@
+You can install a collection from a git repository instead of from Galaxy or Automation Hub. As a developer, installing from a git repository lets you review your collection before you create the tarball and publish the collection. As a user, installing from a git repository lets you use collections or versions that are not in Galaxy or Automation Hub yet.
+
+The repository must contain a ``galaxy.yml`` or ``MANIFEST.json`` file. This file provides metadata such as the version number and namespace of the collection.
+
+Installing a collection from a git repository at the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To install a collection from a git repository at the command line, use the URI of the repository instead of a collection name or path to a ``tar.gz`` file. Use the prefix ``git+``, unless you're using SSH authentication with the user ``git`` (for example, ``git@github.com:ansible-collections/ansible.windows.git``). You can specify a branch, commit, or tag using the comma-separated `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ syntax.
+
+For example:
+
+.. code-block:: bash
+
+ # Install a collection in a repository using the latest commit on the branch 'devel'
+ ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel
+
+ # Install a collection from a private github repository
+ ansible-galaxy collection install git@github.com:organization/repo_name.git
+
+ # Install a collection from a local git repository
+ ansible-galaxy collection install git+file:///home/user/path/to/repo_name.git
+
+.. warning::
+
+ Embedding credentials into a git URI is not secure. Use safe authentication options to prevent your credentials from being exposed in logs or elsewhere.
+
+ * Use `SSH <https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_ authentication
+ * Use `netrc <https://linux.die.net/man/5/netrc>`_ authentication
+ * Use `http.extraHeader <https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpextraHeader>`_ in your git configuration
+ * Use `url.<base>.pushInsteadOf <https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtpushInsteadOf>`_ in your git configuration
+
+Specifying the collection location within the git repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you install a collection from a git repository, Ansible uses the collection ``galaxy.yml`` or ``MANIFEST.json`` metadata file to build the collection. By default, Ansible searches two paths for collection ``galaxy.yml`` or ``MANIFEST.json`` metadata files:
+
+* The top level of the repository.
+* Each directory in the repository path (one level deep).
+
+If a ``galaxy.yml`` or ``MANIFEST.json`` file exists in the top level of the repository, Ansible uses the collection metadata in that file to install an individual collection.
+
+.. code-block:: text
+
+ ├── galaxy.yml
+ ├── plugins/
+ │   ├── lookup/
+ │   ├── modules/
+ │   └── module_utils/
+ └─── README.md
+
+If a ``galaxy.yml`` or ``MANIFEST.json`` file exists in one or more directories in the repository path (one level deep), Ansible installs each directory with a metadata file as a collection. For example, Ansible installs both collection1 and collection2 from this repository structure by default:
+
+.. code-block:: text
+
+ ├── collection1
+ │   ├── docs/
+ │   ├── galaxy.yml
+ │   └── plugins/
+ │    ├── inventory/
+ │   └── modules/
+ └── collection2
+    ├── docs/
+    ├── galaxy.yml
+    ├── plugins/
+   |   ├── filter/
+    | └── modules/
+    └── roles/
+
+If you have a different repository structure or only want to install a subset of collections, you can add a fragment to the end of your URI (before the optional comma-separated version) to indicate the location of the metadata file or files. The path should be a directory, not the metadata file itself. For example, to install only collection2 from the example repository with two collections:
+
+.. code-block:: text
+
+ ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/collection2/
+
+In some repositories, the main directory corresponds to the namespace:
+
+.. code-block:: text
+
+ namespace/
+ ├── collectionA/
+ | ├── docs/
+ | ├── galaxy.yml
+ | ├── plugins/
+ | │   ├── README.md
+ | │   └── modules/
+ | ├── README.md
+ | └── roles/
+ └── collectionB/
+ ├── docs/
+ ├── galaxy.yml
+ ├── plugins/
+ │   ├── connection/
+ │   └── modules/
+ ├── README.md
+ └── roles/
+
+You can install all collections in this repository, or install one collection from a specific commit:
+
+.. code-block:: bash
+
+ # Install all collections in the namespace
+ ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/
+
+ # Install an individual collection using a specific commit
+ ansible-galaxy collection install git+https://github.com/organization/repo_name.git#/namespace/collectionA/,7b60ddc245bc416b72d8ea6ed7b799885110f5e5
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 0000000..a1b18b5
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
@@ -0,0 +1,77 @@
+
+You can set up 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: ">=1.2.0" # Version range identifiers (default: ``*``)
+ source: ... # The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)
+
+You can specify the following keys for each collection entry:
+
+ * ``name``
+ * ``version``
+ * ``signatures``
+ * ``source``
+ * ``type``
+
+The ``version`` key uses the same range identifier format documented in :ref:`collections_older_version`.
+
+The ``signatures`` key accepts a list of signature sources that are used to supplement those found on the Galaxy server during collection installation and ``ansible-galaxy collection verify``. Signature sources should be URIs that contain the detached signature. The ``--keyring`` CLI option must be provided if signatures are specified.
+
+Signatures are only used to verify collections on Galaxy servers. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files.
+
+.. code-block:: yaml
+
+ collections:
+ - name: namespace.name
+ version: 1.0.0
+ type: galaxy
+ signatures:
+ - https://examplehost.com/detached_signature.asc
+ - file:///path/to/local/detached_signature.asc
+
+The ``type`` key can be set to ``file``, ``galaxy``, ``git``, ``url``, ``dir``, or ``subdirs``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection.
+
+When you install a collection with ``type: git``, the ``version`` key can refer to a branch or to a `git commit-ish <https://git-scm.com/docs/gitglossary#def_commit-ish>`_ object (commit or tag). For example:
+
+.. code-block:: yaml
+
+ collections:
+ - name: https://github.com/organization/repo_name.git
+ type: git
+ version: devel
+
+You can also add roles to a ``requirements.yml`` file, under the ``roles`` key. The values follow the same format as a requirements file used in older Ansible releases.
+
+.. code-block:: yaml
+
+ ---
+ roles:
+ # Install a role from Ansible Galaxy.
+ - name: geerlingguy.java
+ version: "1.9.6" # note that ranges are not supported for roles
+
+
+ collections:
+ # Install a collection from Ansible Galaxy.
+ - name: geerlingguy.php_roles
+ version: ">=0.9.3"
+ source: https://galaxy.ansible.com
+
+To install both roles and collections at the same time with one command, run the following:
+
+.. code-block:: bash
+
+ $ ansible-galaxy install -r requirements.yml
+
+Running ``ansible-galaxy collection install -r`` or ``ansible-galaxy role install -r`` will only install collections, or roles respectively.
+
+.. note::
+ Installing both roles and collections from the same requirements file will not work when specifying a custom collection or role install path. In this scenario the collections will be skipped and the command will process each like ``ansible-galaxy role install`` would.
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 0000000..511dd2a
--- /dev/null
+++ b/docs/docsite/rst/shared_snippets/installing_older_collection.txt
@@ -0,0 +1,25 @@
+
+You can only have one version of a collection installed at a time. By default ``ansible-galaxy`` installs the latest available version. If you want to install a specific version, you can add a version range identifier. For example, 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
+
+You can specify multiple range identifiers separated by ``,``. Use single quotes so the shell passes the entire command, including ``>``, ``!``, and other operators, along. For example, to install the most recent version that is greater than or equal to 1.0.0 and less than 2.0.0:
+
+.. code-block:: bash
+
+ ansible-galaxy collection install 'my_namespace.my_collection:>=1.0.0,<2.0.0'
+
+Ansible will always install the most recent version that meets the range identifiers you specify. You can use the following range identifiers:
+
+* ``*``: The most recent version. This is the default.
+* ``!=``: Not equal to the version specified.
+* ``==``: Exactly the version specified.
+* ``>=``: Greater than or equal to the version specified.
+* ``>``: Greater than the version specified.
+* ``<=``: Less than or equal to the version specified.
+* ``<``: Less than the version specified.
+
+.. note::
+ By default ``ansible-galaxy`` ignores pre-release versions. To install a pre-release version, you must use the ``==`` range identifier to require it explicitly.