Написание инвентаря

Инвентарь — это описание кластера для Ansible: какие экземпляры Tarantool в него входят, на каких серверах они размещены, как объединены в наборы реплик, по каким параметрам подключаться к серверам и какой конфигурацией запускать экземпляры. Плейбуки коллекции Ansible Tarantool Enterprise работают с инвентарём стандартными средствами Ansible, поэтому задать его можно двумя способами:

• генератор инвентаря — инвентарный плагин tarantool.enterprise.generator, входящий в состав коллекции. В файле для генератора описывается желаемый результат — серверы и компоненты кластера, — а группы, хосты и переменные генерируются автоматически;
• статический инвентарь — вручную написанный файл, в котором явно перечислены все группы, хосты и переменные.

Для большинства задач рекомендуется генератор инвентаря: он берёт на себя рутинную работу по построению топологии. В каких случаях уместен статический инвентарь — см. раздел Выбор типа инвентаря ниже.

В этой статье объясняется устройство обоих способов и приведён короткий рецепт написания инвентаря для генератора с нуля. Полное описание всех секций и полей — в разделе Справочник генератора.

Инвентарь — только описание кластера. Перед тем как его писать, убедитесь, что выполнены общие требования к развёртыванию: подготовлена машина с Ansible или Docker-образ ATE, ко всем целевым серверам есть SSH-доступ и права, достаточные для установки пакетов и создания служб. Полный список — в разделе Настройка среды.

Инвентарь в Ansible — это три сущности: хосты, группы и переменные.

Хост — единица управления: именно к хостам Ansible применяет плейбуки. Хост не обязательно соответствует реальной машине: это может быть просто абстрактное имя вроде storage-r01-i01, никак не связанное с сетевым адресом. Адрес подключения задаётся отдельно — переменной ansible_host.

Группы объединяют хосты, к которым применяются одни и те же действия и переменные. Группы могут вкладываться друг в друга, образуя иерархию.

Переменные задают параметры хостов. Переменная хоста может быть присвоена на уровне самого хоста, на уровне группы, в которую он входит, или глобально (группа all); при конфликте действует присваивание на уровне, ближайшем к хосту.

В коллекции ATE хостами инвентаря служат экземпляры Tarantool — по одному хосту на каждый запущенный процесс. Экземпляры группируются по наборам реплик, по типам компонентов и по физическим серверам, на которых они размещены; параметры SSH-подключения задаются на уровне группы сервера.

Генератор инвентаря лучше подходит, когда:

• топологию удобно описать декларативно — списком серверов и списком компонентов, без ручного выстраивания иерархии групп;
• важно снизить объём ручной работы и число ошибок: порты назначаются автоматически, имена групп и экземпляров генерируются, поэтому опечатки в них исключены;
• кластер будет масштабироваться или мигрировать: изменения описываются секцией changes поверх базовой топологии;
• TCM должен разворачиваться вместе с кластером — он описывается в том же файле;
• экземпляров много и они распределены по большому количеству серверов: файл инвентаря для генератора не растёт с количеством экземпляров, в отличие от статического инвентаря, — это избавляет от ручных ошибок при назначении портов;
• используется один из продуктов (TCS, TCF, TQE, CDC, tdb_redis) — их схемы генератор понимает сам.

Статический инвентарь лучше подходит, когда:

• кластер небольшой и нужен полный ручной контроль: каждая группа, каждый экземпляр и каждая переменная видны в файле напрямую, и генератор ничего не добавляет от себя;
• нужна топология, которую генератор не поддерживает.

Генератор инвентаря — это инвентарный плагин tarantool.enterprise.generator, входящий в поставку коллекции. Вы описываете в YAML-файле желаемый результат, а генератор при каждом запуске Ansible строит по этому описанию хосты, группы и переменные.

Файл для генератора состоит из четырёх секций:

• constants — общие переменные, применяемые ко всем хостам кластера;
• servers — физические серверы, на которых размещаются экземпляры;
• components — компоненты кластера: наборы реплик и их конфигурация;
• changes — опциональная секция изменений поверх базовой топологии.

По этому описанию генератор:

• создаёт иерархию групп: имя кластера (родительская группа), зоны, серверы, компоненты и наборы реплик;
• распределяет экземпляры по серверам с помощью стратегии распределения: StrategyRoundRobin (по умолчанию, по кругу) или StrategyEvenByZone (равномерно по зонам; все серверы при этом должны иметь заполненное поле zone);
• назначает порты автоматически: каждому экземпляру на сервере выделяется свой порт, начиная со стартового. Значения по умолчанию: iproto — 3301, http — 8081, для TCS http_tcs — 7777; стартовые порты переопределяются полем port_starts на уровне сервера или компонента;
• генерирует хосты — по одному на каждый экземпляр, — группирует их по наборам реплик и компонентам и заполняет для каждого экземпляра секцию конфигурации с прописанными портами;
• понимает продуктовые схемы: поле product принимает значения tarantool, TCS, TCF, TQE, CDC и tdb_redis, и для каждого продукта генератор знает его особенности. Например, для TQE это обязательный компонент с grpc_server в имени.

Секция changes описывает изменения поверх базовой топологии, поэтому масштабирование и миграции не требуют переписывания инвентаря: add_servers и remove_servers управляют составом серверов, change_components и add_replicas увеличивают количество наборов реплик и реплик, relocate_instances переносит экземпляры с сервера на сервер с автоматическим планом миграции, set_variables задаёт переменные, remove_instances исключает экземпляры.

Секция tcm позволяет описать Tarantool Cluster Manager в том же файле, что и продуктовый кластер, — TCM развернётся вместе с кластером, а управляемый кластер автоматически попадёт в его начальную конфигурацию.

Генератор назначает порты отдельно для каждого сервера: у каждого компонента на сервере есть свой счётчик для каждого типа порта, и отсчёт ведётся от стартового порта. Переопределить стартовый порт можно полем port_starts на уровне сервера или компонента; действует приоритет: port_starts компонента, затем port_starts сервера, затем значение по умолчанию.

Типы портов и их значения по умолчанию:

Выданные порты резервируются на уровне сервера в едином списке, поэтому порты разных компонентов и разных типов на одном сервере не конфликтуют: каждый следующий экземпляр получает следующий свободный порт. Счётчики разных серверов независимы — одинаковые порты на разных серверах не мешают друг другу.

Рассмотрим пример: два сервера и один компонент storage из трёх экземпляров, стратегия распределения по умолчанию (StrategyRoundRobin):

 
servers:  - name: vm_1    host: 192.168.1.10    user: admin  - name: vm_2    host: 192.168.1.11    user: admincomponents:  - name: storage    replicasets: 1 # Один набор реплик    replicas: 3 # Три реплики — три экземпляра

Стратегия StrategyRoundRobin раскладывает экземпляры по серверам по кругу, а порты назначаются счётчиком своего сервера:

• storage-r01-i01 — на vm_1, iproto-порт 3301: первый экземпляр на этом сервере получает стартовый порт;
• storage-r01-i02 — на vm_2, тоже iproto-порт 3301: счётчик vm_2 независим от счётчика vm_1, поэтому одинаковый порт на другом сервере — не конфликт;
• storage-r01-i03 — снова на vm_1, iproto-порт 3302: следующий свободный порт на vm_1.

Базовая схема — шардированный кластер Tarantool 3.x (такой строится в разделе Инвентарь за пять шагов ниже). Для остальных продуктов различия сводятся к нескольким полям и переменным:

• TCS (Tarantool Column Store) — требует компоненты coordinator, scheduler и >= 1 storage-компонент; используются специальные переменные tcs_*.
• TCF (Tarantool Clusters Federation) — двухкластерная топология (секции cluster_1 + cluster_2 + tcf: блок); обязательные tcf_package_path и tcf_user_password.
• TQE (Tarantool Queue Enterprise) — обязательный компонент с grpc_server в имени; порты grpc/http не переопределяются.
• CDC (Change Data Capture) — требует cdc_package_path/cdc_package_name; поддерживает shard_per_worker для распределения обработчиков по шардам.
• TCM (Tarantool Cluster Manager) — описывается в секции tcm: в том же файле; управляемый кластер попадает в начальную конфигурацию автоматически.

Подробный минимум переменных для каждого продукта — в справочнике переменных генератора. Полные примеры с пояснениями — в Конфигурация Tarantool и продуктов ниже.

В статическом инвентаре топология кластера — это иерархия групп. У приложения (продукта) есть своя родительская группа; внутри неё — группы наборов реплик, а членами этих групп — экземпляры. Параллельно экземпляры объединяются в группы физических серверов, к которым относятся параметры подключения.

Переменные распределяются по уровням этой иерархии:

• на уровне сервера — параметры SSH-подключения: ansible_host, ansible_user, ansible_become;
• на уровне группы набора реплик — имя набора реплик (replicaset_alias) и конфигурация Tarantool 3.x уровня набора реплик (tarantool_config_replicaset);
• на уровне группы или кластера — конфигурация Tarantool 3.x уровня группы (tarantool_config_group) и глобальная конфигурация кластера (tarantool_config_global);
• на уровне экземпляра — адреса подключения (iproto.listen, iproto.advertise.client) и метки (labels).

Кроме того, для отдельных продуктов существуют специальные переменные уровня экземпляра: например, в TCS и Tarantool DB экземпляр-координатор выделяется переменной tarantool_coordinator: true — для него создаётся отдельная служба systemd.

Минимальный скелет статического инвентаря:

Обратная сторона полного контроля — объём ручной работы. Каждый новый экземпляр нужно вручную добавить в нужные группы, придумать ему свободный порт и скопировать однотипные блоки переменных. На кластере из десятков экземпляров файл разрастается, а ошибки в номерах портов и именах групп обнаруживаются только при запуске плейбука. Полные примеры статических инвентарей по продуктам — в разделе Примеры инвентарей.

Ниже — минимальный путь написания инвентаря для генератора с нуля. Каждый шаг добавляет одну секцию; после пятого шага инвентарь готов к использованию в плейбуках коллекции.

В начале файла укажите инвентарный плагин, имя кластера и продукт. Имя кластера станет родительской группой для всех сгенерированных хостов; если не задать tarantool_app_name, имя приложения возьмётся из имени кластера.

 
plugin: tarantool.enterprise.generator # Инвентарный плагин коллекцииcluster_name: myapp # Имя кластера и родительской группыproduct: tarantool # Продукт: tarantool, TCS, TCF, TQE, CDC, tdb_redis

В секции servers перечислите физические серверы или виртуальные машины, на которых будут размещены экземпляры. Обязательные поля — host и user; опционально задаются SSH-порт, зона, адрес для анонса экземпляров и стартовые порты.

 
servers:  - name: vm_1 # Имя сервера (группа в инвентаре)    host: 192.168.1.10 # Адрес сервера    user: admin # Пользователь для подключения по SSH    port: 22 # SSH-порт (значение по умолчанию)  - name: vm_2    host: 192.168.1.11    user: admin    zone: DC2 # Зона доступности — нужна для StrategyEvenByZone

В секции components задайте компоненты кластера: сколько наборов реплик и реплик в каждом и какая у них конфигурация. Конфигурация Tarantool 3.x указывается в поле config на уровнях набора реплик (replicaset) и группы (group).

 
components:  - name: storage # Имя компонента    replicasets: 2 # Количество наборов реплик    replicas: 2 # Количество реплик в каждом наборе реплик    config:      replicaset: # Конфигурация уровня набора реплик        memtx:          memory: 512000000      group: # Конфигурация уровня группы        sharding:          roles: [storage]  - name: router    replicasets: 2    replicas: 1    config:      group:        sharding:          roles: [router]

Секция constants содержит переменные, применяемые ко всем хостам кластера: адреса хранилища конфигурации, учётные данные, глобальную конфигурацию Tarantool 3.x (tarantool_config_global) и другие переменные из справочника переменных. Эта секция не обязательна, но для реального кластера почти всегда нужна.

 
constants:  tarantool_config_storage_endpoints: # Адреса хранилища конфигурации    - http://etcd:2379  tarantool_config_global: # Глобальная конфигурация Tarantool 3.x    credentials:      users:        client:          password: 'secret'          roles: [super]        replicator:          password: 'secret'          roles: [replication]    iproto:      advertise:        peer:          login: replicator

Опциональная секция changes описывает изменения поверх базовой топологии, а секция tcm — серверы Tarantool Cluster Manager в том же файле. Секцию tcm при использовании нескольких файлов инвентаря указывают ровно в одном из них.

 
changes: # Изменения поверх базовой топологии  - type: change_components # Увеличить количество наборов реплик компонента    component_name: storage    replicasets: 3tcm: # Tarantool Cluster Manager в том же файле  servers:    - name: vm_tcm      host: 192.168.1.20      user: admin  tcm_bootstrap_password: 'secret'

Как проверить получившуюся топологию — см. раздел Проверка инвентаря ниже.

Чтобы проверить, правильно ли генератор построил инвентарь, используйте одну из следующих команд:

 
ansible-inventory -i inventory.yml --graph

Пример вывода --graph:

 
@all:  |--@ungrouped:  |--@myapp:  |  |--@storage:  |  |  |--@storage-r01:  |  |  |  |--storage-r01-i01  |  |  |  |--storage-r01-i02  |  |--@storage-r02:  |  |  |  |--storage-r02-i01  |  |  |  |--storage-r02-i02  |  |--@router:  |  |  |--@router-r01:  |  |  |  |--router-r01-i01  |  |--@router-r02:  |  |  |  |--router-r02-i01  |--@DC2:  |  |--@vm_2:  |  |  |--storage-r01-i02  |  |  |--storage-r02-i02  |  |  |--router-r02-i01  |--@vm_1:  |  |--storage-r01-i01  |  |--storage-r02-i01  |  |--router-r01-i01

Чтобы посмотреть переменные хостов, вызовите команду с флагом --list:

 
ansible-inventory -i inventory.yml --list

Вывод — JSON, где каждый хост содержит переменные: ansible_host, ansible_port, ansible_user, ate_instance_type, cluster_name, iproto, labels, replicaset_alias, roles_cfg, tarantool_app_name, tarantool_config_global, tarantool_config_group, tarantool_config_replicaset, tarantool_config_storage_endpoints.

Если генератор встречает в инвентаре некорректные данные, он возвращает сообщение об ошибке:

После того как файл инвентаря готов, его можно использовать с плейбуками коллекции. Типовой способ запуска — через Docker-образ ATE:

 
docker run --network host -it --rm \    -v ${PATH_TO_PRIVATE_KEY}:/ansible/.ssh/id_private_key:Z \    -v ${PATH_TO_INVENTORY}:/ansible/inventories/hosts.yml:Z \    -v ${PATH_TO_PACKAGE}/${PACKAGE_NAME}:/ansible/packages/${PACKAGE_NAME}:Z \    -e SUPER_USER_NAME=${SUPER_USER_NAME} \    ansible-tarantool-enterprise:${DEPLOY_TOOL_VERSION_TAG} \    ansible-playbook -i /ansible/inventories/hosts.yml \    --extra-vars '{        "tarantool_package_path":"/ansible/packages/${PACKAGE_NAME}",        "ansible_ssh_private_key_file":"/ansible/.ssh/id_private_key",        "super_user":"'${SUPER_USER_NAME}'"    }' \    playbooks/install.yml

Локальный вариант (если Ansible установлен на хосте):

 
ansible-playbook -i ${PATH_TO_INVENTORY} --user ${SUPER_USER_NAME} \    -e ansible_ssh_private_key_file=${PATH_TO_PRIVATE_KEY} \    -e tarantool_package_path="${PATH_TO_PACKAGE}/${PACKAGE_NAME}" \    playbooks/install.yml

• Справочник генератора — подробное описание структуры инвентаря, полей генератора, типов изменений и конфигурации продуктов;
• Примеры инвентарей — готовые аннотированные примеры инвентарей по продуктам;
• Справочник переменных — переменные коллекции.