diff options
Diffstat (limited to 'docs/docsite/rst/shared_snippets')
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. |