Встраиваемые модули и плагины в ролях
Если вы пишете собственный модуль (см. ) Или подключаемый модуль (см. подключаемых модулей ), вы можете захотеть распространить его как часть роли. Например, если вы пишете модуль, который помогает настроить внутреннее программное обеспечение вашей компании, и хотите, чтобы другие люди в вашей организации использовали этот модуль, но вы не хотите рассказывать всем, как настроить путь к их библиотеке Ansible, вы можете включить модуль в вашей роли internal_config.
Чтобы добавить модуль или подключаемый модуль к роли: Наряду со структурой «задачи» и «обработчики» роли добавьте каталог с именем «библиотека», а затем включите модуль непосредственно в каталог «библиотека».
Если предположить,что у тебя это было:
roles/
my_custom_modules/
library/
module1
module2
Модуль будет использоваться в самой роли, а также в любых ролях, которые вызываются после этой роли, следующим образом:
---
- hosts: webservers
roles:
- my_custom_modules
- some_other_role_using_my_custom_modules
- yet_another_role_using_my_custom_modules
При необходимости вы также можете встроить модуль в роль, чтобы изменить модуль в основном дистрибутиве Ansible. Например, вы можете использовать разрабатываемую версию определенного модуля до того, как он будет выпущен в производственные выпуски, скопировав модуль и встроив копию в роль
Используйте этот подход с осторожностью, так как сигнатуры API могут измениться в основных компонентах, и это обходное решение не гарантируется
Этот же механизм может быть использован для встраивания и распределения плагинов в роли,используя ту же самую схему.Например,для плагина-фильтра:
roles/
my_custom_filter/
filter_plugins
filter1
filter2
Эти фильтры затем можно использовать в шаблоне Jinja в любой роли, названной после my_custom_filter.
Embedding modules and plugins in roles
If you write a custom module (see ) or a plugin (see ), you might wish to distribute it as part of a role. For example, if you write a module that helps configure your company’s internal software, and you want other people in your organization to use this module, but you do not want to tell everyone how to configure their Ansible library path, you can include the module in your internal_config role.
To add a module or a plugin to a role:
Alongside the ‘tasks’ and ‘handlers’ structure of a role, add a directory named ‘library’ and then include the module directly inside the ‘library’ directory.
Assuming you had this:
roles/
my_custom_modules/
library/
module1
module2
The module will be usable in the role itself, as well as any roles that are called after this role, as follows:
---
- hosts webservers
roles
- my_custom_modules
- some_other_role_using_my_custom_modules
- yet_another_role_using_my_custom_modules
If necessary, you can also embed a module in a role to modify a module in Ansible’s core distribution. For example, you can use the development version of a particular module before it is released in production releases by copying the module and embedding the copy in a role. Use this approach with caution, as API signatures may change in core components, and this workaround is not guaranteed to work.
The same mechanism can be used to embed and distribute plugins in a role, using the same schema. For example, for a filter plugin:
roles/
my_custom_filter/
filter_plugins
filter1
filter2
Пользовательский файл инвентаря
Файл инвентаря по умолчанию обычно находится в /etc/ansible/hosts, но вы можете использовать опцию -i для указания пользовательских файлов при запуске команд и плейбуков Ansible. Это удобный способ настройки индивидуального инвентаря для каждого проекта, который можно включить в системы контроля версий, такие как Git:
Такая опция действительна и для ansible-playbook:
Динамический файл инвентаря
Ansible поддерживает сценарии инвентаризации для создания динамических файлов. Это полезно, если ваш инвентарь часто меняется, когда серверы создаются и уничтожаются.
Вы можете найти ряд скриптов с открытым исходным кодом в официальном репозитории Ansible GitHub. После загрузки требуемого сценария на Ansible control machine и настройки необходимых параметров (например, учетных данных API) вы можете запустить исполняемый файл в качестве пользовательского инвентаря с любой командой Ansible, которая поддерживает эту опцию.
Следующая команда использует скрипт инвентаря my_inventory.py с командой ping для проверки подключения ко всем текущим активным серверам:
За более подробной информацией о том, как использовать динамические файлы инвентаризации, пожалуйста, обратитесь к официальной документации Ansible.
Embedding Modules and Plugins In Roles¶
This is an advanced topic that should not be relevant for most users.
If you write a custom module (see Developing Modules) or a plugin (see Developing Plugins), you may wish to distribute it as part of a role.
Generally speaking, Ansible as a project is very interested in taking high-quality modules into ansible core for inclusion, so this shouldn’t be the norm, but it’s quite easy to do.
A good example for this is if you worked at a company called AcmeWidgets, and wrote an internal module that helped configure your internal software, and you wanted other
people in your organization to easily use this module – but you didn’t want to tell everyone how to configure their Ansible library path.
Alongside the ‘tasks’ and ‘handlers’ structure of a role, add a directory named ‘library’. In this ‘library’ directory, then include the module directly inside of it.
Assuming you had this:
roles/
my_custom_modules/
library/
module1
module2
The module will be usable in the role itself, as well as any roles that are called after this role, as follows:
- hosts webservers
roles
- my_custom_modules
- some_other_role_using_my_custom_modules
- yet_another_role_using_my_custom_modules
This can also be used, with some limitations, to modify modules in Ansible’s core distribution, such as to use development versions of modules before they are released in production releases. This is not always advisable as API signatures may change in core components, however, and is not always guaranteed to work. It can be a handy way of carrying a patch against a core module, however, should you have good reason for this. Naturally the project prefers that contributions be directed back to github whenever possible via a pull request.
The same mechanism can be used to embed and distribute plugins in a role, using the same schema. For example, for a filter plugin:
roles/
my_custom_filter/
filter_plugins
filter1
filter2
Role Metadata¶
When Galaxy imports a role, the import process looks for metadata found in the role’s file. The following shows
the default metadata file created by the command:
galaxy_info
role_name foo
author your name
description your description
company your company (optional)
# If the issue tracker for your role is not on github, uncomment the
# next line and provide a value
# issue_tracker_url: http://example.com/issue/tracker
# Some suggested licenses:
# - BSD (default)
# - MIT
# - GPLv2
# - GPLv3
# - Apache
# - CC-BY
license license (GPLv2, CC-BY, etc)
min_ansible_version 1.2
# If this a Container Enabled role, provide the minimum Ansible Container version.
# min_ansible_container_version:
# Optionally specify the branch Galaxy will use when accessing the GitHub
# repo for this role. During role install, if no tags are available,
# Galaxy will use this branch. During import Galaxy will access files on
# this branch. If Travis integration is configured, only notifications for this
# branch will be accepted. Otherwise, in all cases, the repo's default branch
# (usually master) will be used.
#github_branch:
#
# platforms is a list of platforms, and each platform has a name and a list of versions.
#
# platforms:
# - name: Fedora
# versions:
# - all
# - 25
# - name: SomePlatform
# versions:
# - all
# - 1.0
# - 7
# - 99.99
galaxy_tags []
# List tags for your role here, one per line. A tag is a keyword that describes
# and categorizes the role. Users find roles by searching for tags. Be sure to
# remove the '[]' above, if you add tags to this list.
#
# NOTE: A tag is limited to a single word comprised of alphanumeric characters.
# Maximum 20 tags per role.
dependencies []
# List your role dependencies here, one per line. Be sure to remove the '[]' above,
# if you add dependencies to this list.
The following provides guidance on setting some of the metadata values that may not be so obvious:
Запуск роли несколько раз в одной пьесе.
Ansible выполняет каждую роль только один раз, даже если вы определяете ее несколько раз, если только параметры, определенные для роли, не отличаются для каждого определения. Например, Ansible запускает роль только один раз в такой игре:
---
- hosts: webservers
roles:
- foo
- bar
- foo
У вас есть два варианта,чтобы заставить Ansible выполнять роль не один раз.
Передача различных параметров
Если вы передаете разные параметры в каждом определении роли, Ansible запускает роль более одного раза. Предоставление разных значений переменных — это не то же самое, что передача разных параметров роли. Для этого поведения необходимо использовать ключевое слово , поскольку и не принимают параметры роли.
Этот сценарий дважды запускает роль :
---
- hosts: webservers
roles:
- { role: foo, message: "first" }
- { role: foo, message: "second" }
Этот синтаксис также дважды запускает роль ;
---
- hosts: webservers
roles:
- role: foo
message: "first"
- role: foo
message: "second"
В этих примерах Ansible запускает дважды, потому что каждое определение роли имеет разные параметры.
Использование
Добавьте в файл для роли:
---
- hosts: webservers
roles:
- foo
- foo
---
allow_duplicates: true
В этом примере Ansible запускает дважды, потому что мы явно разрешили ему это делать.
Упрощение имен модулей с помощью ключевого слова collections
В ключевых слов позволяет определить список коллекций, ваша роль или пьесы следует искать неквалифицированные модуль и действие имен. Таким образом, вы можете использовать ключевое слово , а затем просто ссылаться на модули и плагины действий по их кратким именам в этой роли или учебнике.
Warning
Если в вашей пьесе используется как ключевое слово и одна или несколько ролей, роли не наследуют коллекции, заданные пьесой. Это одна из причин, по которой мы рекомендуем всегда использовать FQCN. Подробнее о ролях см. Ниже.
Использование в ролях
Внутри роли вы можете управлять тем, в каких коллекциях Ansible будет искать задачи внутри роли, используя ключевое слово в . Ansible будет использовать список коллекций, определенный внутри роли, даже если книга воспроизведения, вызывающая роль, определяет разные коллекции в отдельной записи ключевого слова . Роли, определенные внутри коллекции, всегда сначала неявно выполняют поиск в своей собственной коллекции, поэтому вам не нужно использовать ключевое слово для доступа к модулям, действиям или другим ролям, содержащимся в той же коллекции.
# myrole/meta/main.yml collections: - my_namespace.first_collection - my_namespace.second_collection - other_namespace.other_collection
Использование в playbooks
В playbook вы можете управлять коллекциями, в которых Ansible ищет модули и плагины действий для выполнения. Однако любые роли, которые вы вызываете в своей книге, определяют свой собственный порядок поиска в коллекциях; они не наследуют настройки вызывающей книги. Это верно, даже если роль не определяет собственное ключевое слово .
- hosts: all
collections:
- my_namespace.my_collection
tasks:
- import_role:
name: role1
- mymodule:
option1: value
- debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", "param1")| my_namespace.my_collection.filter1 }}'
В ключевых слов просто создает упорядоченный «путь поиска» для не-пространство имен плагинов и роль ссылок. Он не устанавливает контент или иным образом не изменяет поведение Ansible при загрузке плагинов или ролей
Обратите внимание, что FQCN по-прежнему требуется для плагинов, не связанных с действием или модулей (например, для поиска, фильтров, тестов)
Role Duplication and Execution¶
Ansible will only allow a role to execute once, even if defined multiple times, if the parameters defined on the role are not different for each definition. For example:
--- - hosts webservers roles - foo - foo
Given the above, the role will only be run once.
To make roles run more than once, there are two options:
- Pass different parameters in each role definition.
- Add to the file for the role.
Example 1 — passing different parameters:
---
- hosts webservers
roles
- { role foo, message "first" }
- { role foo, message "second" }
In this example, because each role definition has different parameters, will run twice.
Example 2 — using :
# playbook.yml --- - hosts webservers roles - foo - foo # roles/foo/meta/main.yml --- allow_duplicates true
Using Roles¶
The classic (original) way to use roles is via the option for a given play:
---
- hosts webservers
roles
- common
- webservers
This designates the following behaviors, for each role ‘x’:
- If roles/x/tasks/main.yml exists, tasks listed therein will be added to the play.
- If roles/x/handlers/main.yml exists, handlers listed therein will be added to the play.
- If roles/x/vars/main.yml exists, variables listed therein will be added to the play.
- If roles/x/defaults/main.yml exists, variables listed therein will be added to the play.
- If roles/x/meta/main.yml exists, any role dependencies listed therein will be added to the list of roles (1.3 and later).
- Any copy, script, template or include tasks (in the role) can reference files in roles/x/{files,templates,tasks}/ (dir depends on task) without having to path them relatively or absolutely.
When used in this manner, the order of execution for your playbook is as follows:
- Any defined in the play.
- Any handlers triggered so far will be run.
- Each role listed in will execute in turn. Any role dependencies defined in the roles will be run first, subject to tag filtering and conditionals.
- Any defined in the play.
- Any handlers triggered so far will be run.
- Any defined in the play.
- Any handlers triggered so far will be run.
Note
See below for more information regarding role dependencies.
Note
If using tags with tasks (described later as a means of only running part of a playbook), be sure to also tag your pre_tasks, post_tasks, and role dependencies and pass those along as well, especially if the pre/post tasks and role dependencies are used for monitoring outage window control or load balancing.
As of Ansible 2.4, you can now use roles inline with any other tasks using or :
---
- hosts webservers
tasks
- debug
msg "beforewerunourrole"
- import_role
name example
- include_role
name example
- debug
msg "afterweranourrole"
When roles are defined in the classic manner, they are treated as static imports and processed during playbook parsing.
Note
The option was introduced in Ansible 2.3. The usage has changed slightly as of Ansible 2.4 to match the include (dynamic) vs. import (static) usage. See for more details.
The name used for the role can be a simple name (see below), or it can be a fully qualified path:
---
- hosts webservers
roles
- { role '/path/to/my/roles/common' }
Roles can accept parameters:
---
- hosts webservers
roles
- common
- { role foo_app_instance, dir '/opt/a', app_port 5000 }
- { role foo_app_instance, dir '/opt/b', app_port 5001 }
Or, using the newer syntax:
---
- hosts webservers
tasks
- include_role
name foo_app_instance
vars
dir '/opt/a'
app_port 5000
...
You can conditionally execute a role. This is not generally recommended with the classic syntax, but is common when using or :
---
- hosts webservers
tasks
- include_role
name some_role
when "ansible_os_family=='RedHat'"
Finally, you may wish to assign tags to the roles you specify. You can do so inline:
---
- hosts webservers
roles
- { role foo, tags "bar", "baz" }
Or, again, using the newer syntax:
---
- hosts webservers
tasks
- import_role
name foo
tags
- bar
- baz
Скачать коллекции
Чтобы загрузить коллекцию и ее зависимости для автономной установки, запустите . Это загружает указанные коллекции и их зависимости в указанную папку и создает файл , который можно использовать для установки этих коллекций на хосте без доступа к серверу Galaxy. По умолчанию все коллекции загружаются в папку .
Как и в случае с командой , коллекции создаются на основе . Даже если коллекция для загрузки была указана с помощью URL-адреса или пути к архиву, коллекция будет повторно загружена с настроенного сервера Galaxy.
Коллекции могут быть указаны как одна или несколько коллекций или с файлом , как при .
Скачать одну коллекцию и ее зависимости:
ansible-galaxy collection download my_namespace.my_collection
Загрузить одну коллекцию в определенной версии:
ansible-galaxy collection download my_namespace.my_collection:1..
Чтобы загрузить несколько коллекций, укажите несколько коллекций в качестве аргументов командной строки, как показано выше, или используйте файл требований в формате, задокументированном в разделе .
ansible-galaxy collection download -r requirements.yml
Вы также можете скачать каталог исходной коллекции. Коллекция построена с использованием обязательного файла .
ansible-galaxy collection download /path/to/collection ansible-galaxy collection download git+file:///path/to/collection/.git
Вы можете загрузить несколько коллекций источников из одного пространства имен,указав путь к пространству имен.
ns/
├── collection1/
│ ├── galaxy.yml
│ └── plugins/
└── collection2/
├── galaxy.yml
└── plugins/
ansible-galaxy collection install /path/to/ns
Все коллекции по умолчанию папку ./collections, но вы можете использовать или , чтобы указать другой путь:
ansible-galaxy collection download my_namespace.my_collection -p ~/offline-collections
После того, как вы загрузили коллекции, папка будет содержать указанные коллекции, их зависимости и файл . Вы можете использовать эту папку как есть при для установки коллекций на хосте без доступа к серверу Galaxy или Automation Hub.
cd ~/offline-collections ansible-galaxy collection install -r requirements.yml
Понимание ролей Ansible
Роль Ansible – это набор файлов, задач, шаблонов, переменных и обработчиков, которые вместе служат определенной цели, например, для настройки службы. Роли позволяют легко повторно использовать код и делиться решениями Ansible с другими пользователями, что делает работу с большими средами более управляемой.
Типичная роль Ansible следует определенной структуре каталогов, которая обычно состоит из следующих каталогов:
- defaults: содержит переменные по умолчанию для роли, которые должны быть легко перезаписаны.
- vars: содержит стандартные переменные для роли, которые не должны быть перезаписаны в вашей книге.
- tasks: содержит набор задач, которые должна выполнять роль.
- handlers: содержит набор обработчиков, которые будут использоваться в роли.
- templates: содержит шаблоны Jinja2, которые будут использоваться в роли.
- files: содержит статические файлы, необходимые из ролевых задач.
- tests: может содержать дополнительный файл инвентаря, а также playbook test.yml, который можно использовать для тестирования роли.
- meta: содержит метаданные роли, такие как информация об авторе, лицензия, зависимости и т. д.
Имейте в виду, что у роли могут быть все вышеупомянутые каталоги или только их часть. Фактически, вы можете определить пустую роль, у которой нет каталогов, но это бесполезно!
Хранение и расположение ролей
По умолчанию Ansible будет искать роли в двух местах:
- В каталоге role (тот же уровень каталога, что и ваш файл playbook).
- В каталоге /etc/ansible/roles.
Однако вы можете сохранить свои роли в другом месте; если вы решите это сделать, вы должны указать и установить параметр конфигурации roles_path в файле конфигурации Ansible ( ansible.cfg ).
Использование ролей Ansible в Playbooks
Есть два разных способа, которыми вы можете импортировать роли в пьесе Ansible :
- Использование ключевого слова roles для статического импорта ролей.
- Использование модуля include_role для динамического импорта ролей.
Например, чтобы статически импортировать роли в playbook, вы можете использовать ключевое слово роли в заголовке playbook следующим образом:
---
- name: Including roles statically
hosts: all
roles:
- role1
- role2
Динамически импортировать роли; вы можете использовать модуль include_role следующим образом:
---
- name: Including roles dynamically
hosts: all
tasks:
- name: import dbserver role
include_role:
name: db_role
when: inventory_hostname in groups
