Использование динамического инвентаря

В этом руководстве описано, как создать файл динамического инвентаря с использованием плагина tarantool.enterprise.generator. В файле динамического инвентаря для плагина задаются параметры кластера Tarantool или продуктов на его основе, серверов, а также компонентов кластера. Плагин входит в поставку Ansible Tarantool Enterprise. Чтобы использовать данный плагин вне коллекции АТЕ, включите его в файле конфигурации Ansible (файл ansible.cfg):

 
[inventory]enable_plugins = tarantool.enterprise.generator

Файл динамического инвентаря написан в формате YAML и состоит из нескольких основных секций:

• plugin: название используемого инвентарного плагина;
• cluster_name: имя кластера;
• product: название продукта -- например tarantool, TCS, TCF, TQE, cartridge, CDC;
• constants: глобальные переменные и настройки;
• servers: список серверов и их параметры;
• components: список компонентов кластера и их параметры;
• changes: список изменений для кластера.

• plugin: плагин, используемый для генерации инвентаря (tarantool.enterprise.generator).
• cluster_name: имя кластера, которое будет использоваться как родительская группа для всех сгенерированных хостов.
• product: название продукта. Возможные значения: tarantool, TCS, TCF, TQE, cartridge, CDC. Для генерации инвентаря для Tarantool DB укажите tarantool в качестве названия продукта.

Секция constants содержит глобальные переменные, применяемые ко всем хостам. Для Tarantool 3.x здесь указывается переменная tarantool_config_global. Некоторые переменные можно посмотреть в соответствующем разделе документации.

Секция servers содержит список физических серверов и виртуальных машин, на которых будут распределены компоненты кластера. Каждый сервер содержит данные поля:

• name (опционально): имя сервера. Значение по умолчанию: экранированное поле host;
• host: хост сервера;
• advertise_host (опционально): адрес для advertise_uri. Значение по умолчанию: host;
• port (опционально): порт для подключения к серверу. Значение по умолчанию: 22;
• user: пользователь для подключения к серверу;
• zone (опционально): зона, к которой относится сервер;
• port_starts (опционально): стартовые порты для генерации. Значение по умолчанию: "iproto": 3301, "http": 8081.

Секция components описывает компоненты кластера, их конфигурацию, а также количество наборов реплик и экземпляров в них:

• name: имя компонента;
• replicasets: количество наборов реплик;
• replicas: количество узлов в каждом наборе реплик;
• config: конфигурация компонента;
• servers (опционально): список серверов, на которых будут размещаться экземпляры данного компонента. Экземпляры распределяются между указанными серверами по round-robin. Если не указано, используется глобальная стратегия распределения (distribution_strategy). Каждый элемент списка может быть строкой (имя сервера) или словарём с полями:
  • name (обязательно): имя сервера;
  • max_instances (опционально): максимальное количество экземпляров данного компонента на этом сервере. Если не указано, лимит не ограничен.

Пример привязки компонента к серверам:

 
components:  - name: storage    replicasets: 2    replicas: 2    servers: [vm_1, vm_2]    config:      replicaset:        memtx:          memory: 512000000      group:        sharding:          roles: [storage]  - name: router    replicasets: 1    replicas: 1    servers: [vm_3]    config:      group:        sharding:          roles: [router]

В данном примере все экземпляры storage будут размещены только на vm_1 и vm_2 (по round-robin), а экземпляры router — только на vm_3.

Привязка с ограничением количества экземпляров на сервер:

Для каждого сервера в списке можно указать max_instances — максимальное количество экземпляров данного компонента на этом сервере:

 
components:  - name: storage    replicasets: 2    replicas: 3    servers:      - name: vm_1        max_instances: 4      - name: vm_2        max_instances: 2    config:      replicaset:        memtx:          memory: 512000000      group:        sharding:          roles: [storage]

В этом примере на vm_1 будет размещено максимум 4 экземпляра storage, а на vm_2 — максимум 2. При необходимости создать 6 экземпляров (2 replicasets × 3 replicas) распределение будет следующим:

• vm_1: 4 экземпляра
• vm_2: 2 экземпляра

Если сумма max_instances всех серверов меньше требуемого количества экземпляров, генератор выдаст ошибку.

Секция changes содержит список изменений, которые будут применены после создания топологии кластера. Возможные типы изменений:

• set_variables: задаёт переменные для экземпляров;
• remove_instances: удаляет экземпляр из инвентаря;
• add_replicas: добавляет реплики в существующие наборы реплик;
• add_servers: добавляет серверы в кластер;
• remove_servers: удаляет серверы из кластера;
• change_components: изменяет количество наборов реплик и реплик компонента.

 
changes:  - type: set_variables # тип изменения    hosts: # Хост или группа хостов      - kvee-app-r001-s01      - ROUTERS    values: # Переменные, задаваемые для узлов      expelled: true      config:        http_port: 101010301        vinyl_cache: 1        vinyl_memory: 2  - type: add_servers    servers:      - name: vm_3        host: vm3.example.com        user: root        zone: DC2  - type: add_replicas    replicaset_name:      - storage-r01      - storage-r02    replicas: 1  - type: remove_instances    hosts:      - storage-r02-i01      - storage-r02-i02  - type: remove_servers    servers:      - vm_2

Тип изменения add_replicas позволяет добавить реплики в существующие наборы реплик. Новые экземпляры распределяются по серверам согласно distribution_strategy. Создание новых наборов реплик через эту команду не поддерживается.

Для TCF поддержано точечное добавление реплик в существующие наборы реплик gateway-* и destination-* в режиме add-only (без ребаланса шардов), начиная с версии ATE 1.21.0.

• replicaset_name: список имён существующих наборов реплик (обязательно);
• replicas: количество реплик для добавления в каждый набор реплик (опционально, по умолчанию 1, минимум 1);
• servers (опционально): список серверов, на которых будут размещены добавляемые реплики. Каждый элемент может быть строкой (имя сервера) или словарём с полями name и max_instances (аналогично секции components). Если указано, экземпляры распределяются между указанными серверами по round-robin, игнорируя глобальную стратегию распределения и привязку компонента. Если не указано, используется привязка компонента (servers в секции components) или глобальная стратегия распределения.

Добавление реплики в существующие наборы реплик:

 
changes:  - type: add_replicas    replicaset_name:      - storage-r01      - storage-r02    replicas: 1

Добавление реплики на определённые серверы:

 
changes:  - type: add_replicas    replicaset_name: [storage-r01]    replicas: 1    servers: [vm_1]

Добавление реплики с ограничением количества на сервер:

 
changes:  - type: add_replicas    replicaset_name: [storage-r01]    replicas: 3    servers:      - name: vm_1        max_instances: 2      - name: vm_2        max_instances: 1

В этом примере 3 новые реплики будут распределены так: 2 на vm_1 и 1 на vm_2. Лимит max_instances учитывает все экземпляры данного компонента на сервере, включая уже существующие.

Тип изменения change_components позволяет изменить топологию компонента: увеличить количество наборов реплик и/или реплик. Уменьшение количества наборов реплик и реплик не поддерживается — для удаления используйте remove_instances.

• component_name: имя компонента (обязательно);
• replicasets (опционально): целевое количество наборов реплик. Должно быть не меньше текущего. Если не указано, количество наборов реплик не меняется;
• replicas (опционально): целевое количество реплик в каждом наборе реплик. Должно быть не меньше 1. Если не указано, берётся значение из секции components;
• servers (опционально): список серверов, на которых будут размещены новые экземпляры. Каждый элемент может быть строкой (имя сервера) или словарём с полями name и max_instances (аналогично секции components). Если указано, новые экземпляры распределяются между указанными серверами по round-robin. Если не указано, используется привязка компонента (servers в секции components) или глобальная стратегия распределения.

Должно быть указано хотя бы одно из полей: replicasets или replicas.

Увеличение количества наборов реплик:

 
changes:  - type: change_components    component_name: storage    replicasets: 4

В этом примере количество наборов реплик компонента storage будет увеличено до 4. Количество реплик в новых наборах реплик берётся из секции components.

Увеличение количества реплик:

 
changes:  - type: change_components    component_name: storage    replicas: 4

В этом примере каждый набор реплик компонента storage будет дополнен репликами до 4. Реплисеты, в которых уже есть 4 или более реплик, не изменяются.

Изменение топологии с размещением на определённых серверах:

 
changes:  - type: change_components    component_name: storage    replicasets: 4    replicas: 2    servers: [vm_1, vm_2]

В этом примере новые наборы реплик и отдельные реплики будут размещены только на серверах vm_1 и vm_2 по round-robin, игнорируя привязку компонента из секции components. Существующие реплисеты, в которых уже достаточно реплик, не изменяются.

Изменение топологии с ограничением количества на сервер:

 
changes:  - type: change_components    component_name: storage    replicasets: 4    replicas: 2    servers:      - name: vm_1        max_instances: 3      - name: vm_2        max_instances: 3

Лимит max_instances учитывает все экземпляры данного компонента на сервере, включая уже существующие. Если все указанные серверы достигли лимита, генератор выдаст ошибку.

Тип изменения add_servers позволяет добавить серверы в кластер динамически. Добавленные серверы участвуют в распределении экземпляров при последующих операциях add_replicas.

• servers: список серверов для добавления (обязательно);
  • name (опционально): имя сервера;
  • host (обязательно): хост сервера;
  • user (обязательно): пользователь для подключения;
  • zone (опционально): зона, к которой относится сервер.

Добавление сервера в кластер:

 
changes:  - type: add_servers    servers:      - name: vm_3        host: vm3.example.com        user: root        zone: DC2

Тип изменения remove_servers позволяет удалить серверы из кластера. Сервер может быть удалён только если на нём нет экземпляров — перед удалением необходимо использовать remove_instances для удаления всех экземпляров с данного сервера.

• servers: список имён серверов для удаления (обязательно).

Удаление сервера из кластера:

 
changes:  - type: remove_instances    hosts:      - storage-r02-i01      - storage-r02-i02  - type: remove_servers    servers:      - vm_2

В начале инвентаря добавьте строку с подключением плагина динамического инвентаря ATE:

 
plugin: tarantool.enterprise.generator

Придумайте имя кластера Tarantool, а затем укажите желаемый продукт -- tarantool, TCS, TCF, TQE, cartridge или CDC:

 
cluster_name: my_cluster_nameproduct: tarantool

В секции constants укажите глобальные переменные, которые будут применяться ко всем хостам:

 
constants:  cartridge_app_name: my_app_name  tarantool_etcd_host: "{{ tarantool_etcd_host }}"  tarantool_config_global:    credentials:      users:        client:          password: 'secret'          roles: [super]        replicator:          password: 'secret'          roles: [replication]        storage:          password: 'secret'          roles: [sharding]    roles_cfg:      my-role:        variable_1: 10    iproto:      advertise:        peer:          login: replicator        sharding:          login: storage        client: 'unix/:{{ cartridge_run_dir }}/{% raw %}{{ instance_name }}{% endraw %}.iproto'      listen:        - uri: unix/:/app/tarantool/kvee/run/{% raw %}{{ instance_name }}{% endraw %}.iproto

В секции servers укажите список серверов и их параметры:

 
servers:  - name: 'vm_1'    host: '{{ tarantool_ansible_host }}'    user: '{{ super_user }}'  - name: 'vm_2'    host: '{{ tarantool_ansible_host }}'    advertise_host: '127.0.0.1'    port: 2201    zone: 'DC5'    user: '{{ super_user }}'    port_starts:      iproto: 3401      http: 9091

В секции components укажите компоненты кластера, их конфигурацию, количество наборов реплик и узлов в каждом из них:

 
components:  - name: storage    replicasets: 2    replicas: 2    config:      replicaset:        memtx:          memory: 512000000      group:        app:          module: storage          cfg:            space_name: super-duper-space        sharding:          roles: [storage]        memtx:          memory: 1000241024        roles:          - roles.my-role  - name: router    replicasets: 2    replicas: 1    config:      replicaset:      group:        app:          module: router        sharding:          roles: [router]        roles:          - roles.another-role

Tarantool 3.x позволяет задавать параметры конфигурации на различных уровнях (scope) — например для всех узлов кластера или отдельного набора реплик. Вы можете задать конфигурацию для группы и набора реплик в секции config.

TCS имеет обязательные компоненты scheduler (для TCS 0.x) и coordinator, а также компонент storage, который может иметь произвольное имя.

Для установки TCS версии 1.x укажите переменную tcs_v1_support: true и заполните инвентарь в соответствии с документацией TCS (без компонента scheduler).

В инвентаре TCF есть три обязательные секции:

• tcf - переменные для компонентов Gateway и Destination;
• cluster_1 и cluster_2 - описание первого и второго кластера;

По умолчанию генератор создаёт по одному экземпляру Gateway и Destination на каждое направление репликации (A→B и B→A). С помощью параметра scaling можно увеличить количество репликаторов и автоматически распределить шарды между ними (см. раздел "Масштабирование репликаторов" ниже).

Начиная с TCF 0.11.0 поддерживается запуск нескольких экземпляров Gateway и Destination на каждом направлении репликации. Это позволяет распределить нагрузку по репликации между несколькими процессами.

Масштабирование настраивается через параметр scaling в секции tcf. Поддерживаются два режима:

• count — точное количество репликаторов каждого типа на направление;
• shards_per_instance — один репликатор на каждые N шардов (наборов реплик хранилищ). Количество вычисляется как ⌈общее_число_шардов / N⌉.

Эти режимы взаимоисключающие. Если scaling не задан, создаётся по одному экземпляру Gateway и Destination на направление (поведение по умолчанию).

Шарды распределяются между репликаторами равномерно по round-robin. Например, 6 шардов на 4 Gateway дадут распределение: [r01, r02], [r03, r04], [r05], [r06].

Все Destination одного направления получают одинаковый tcf_gateway_clusters — они подключаются ко всем Gateway этого направления. Различаются у них только tcf_destination_shards.

При масштабировании генератор автоматически заполняет следующие переменные (если они не заданы вручную в tcf):

• tcf_gateway_alias — уникальный алиас для каждого Gateway (формат: gateway-{src}-{dst}-{N:02d});
• tcf_destination_alias — уникальный алиас для каждого Destination (формат: destination-{src}-{dst}-{N:02d});
• tcf_gateway_metrics_labels — метки для метрик Gateway (содержат tcf_cluster, direction, component, instance);
• tcf_destination_metrics_labels — метки для метрик Destination;
• tcf_destination_shards — список шардов, закреплённых за данным Destination;
• tcf_gateway_clusters — описание подключения ко всем Gateway направления (для Destination);
• tcf_gateway_storage_uris — список URI storage-экземпляров, которые читает данный Gateway.

Если какая-либо из этих переменных задана вручную в секции tcf, автогенерация для неё пропускается — используется пользовательское значение.

Если в константах кластера задан параметр tarantool_iproto_ssl_params с transport: ssl (или tls), генератор автоматически заполняет переменные для TLS-подключений репликаторов к экземплярам Tarantool по протоколу iproto:

• tcf_gateway_iproto_ssl_opts — параметры TLS для подключения Gateway к экземплярам хранилищ кластера-источника;
• tcf_destination_iproto_ssl_opts — параметры TLS для подключения Destination к роутерам целевого кластера.

Обе переменные содержат ключи ssl_cert_file, ssl_key_file и опционально ssl_ca_file, значения которых копируются из tarantool_iproto_ssl_params соответствующего кластера. В конфигурации репликаторов эти параметры попадают в секцию ssl_opts с полями key_file, cert_file, ca_file.

Если переменные заданы вручную в секции tcf, автогенерация не выполняется.

TQE имеет обязательный компонент, который должен содержать строку grpc_server (например grpc_server_consumer, grpc_server_producer). У компонента, содержащего строку grpc_server, достаточно указать словарь очередей для публикации и подписки - это можно сделать в секции инвентаря producer/consumer для задания очередей. Генератор автоматически заполнит секцию advertise_uri для экземпляров хранилища и роутера соответственно. Если требуется задать свои собственные параметры подключения, их можно указать в поле connections.

CDC (Change Data Capture) — продукт для репликации данных между различными источниками и приёмниками. Динамический инвентарь для CDC генерирует хосты с параметрами обработчиков CDC, включая конфигурацию source- и sink-коннекторов.

Поддерживаемые типы offset storage (cdc_offset_params.storage.type):

• tqe — хранение контрольных точек в Tarantool Queue Enterprise;
• file — хранение контрольных точек в файле;
• kafka — хранение контрольных точек в Kafka.

Примеры инвентарей для наиболее употребимых конфигураций CDC (TDB → TQE → PostgreSQL, TDB → PostgreSQL) приведены в разделе Change Data Capture.

В секции config каждого компонента укажите следующие переменные:

• cdc_worker_params — параметры обработчика (shutdown timeout и др.). worker.id генерируется автоматически из имени экземпляра;
• cdc_sink_connector_params — параметры sink-коннектора (подключение к целевому кластеру, топик, режимы вставки/удаления);
• cdc_source_connector_params — параметры source-коннектора (подключение к исходному кластеру, репликация, spaces, топик). group.id генерируется автоматически;
• cdc_offset_params — параметры хранения оффсетов (flush, storage type/address/queue). storage.connection.id генерируется автоматически;
• cdc_throttle_params — параметры троттлинга (максимальный rps).

Опциональные переменные:

• cdc_log_params — параметры журналирования. Если не заданы, генерируется автоматически: file.name: /app/cdc/logs/<имя_экземпляра>.log;
• cdc_group — системная группа для сервиса CDC (по умолчанию: tarantool);
• cdc_user — системный пользователь для сервиса CDC (по умолчанию: tarantool);
• cdc_file_mode — права доступа к файлам (по умолчанию: 0755).

Количество компонентов и их имена задаются произвольно, что позволяет развернуть несколько CDC-воркеров с разной конфигурацией.

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

Поля секции tcm::

• servers — список серверов TCM (dict). Каждый entry содержит:
  • name (обязательный): имя сервера;
  • host (опциональный): хост для SSH-подключения;
  • port (опциональный): SSH-порт (по умолчанию: 22);
  • user (обязательный, если сервер не из servers:): пользователь для подключения;
  • tcm_host (опциональный): адрес, на котором TCM слушает HTTP. По умолчанию: host;
  • tcm_port (опциональный): HTTP-порт TCM. По умолчанию: 8080.
• tcm_bootstrap_password: начальный пароль администратора;
• tcm_bootstrap_api_token: начальный API-токен;
• tcm_features: словарь флагов (ttgraph, api_token, tqe, column_store).

Особенности:

• Если name совпадает с сервером из servers: кластера — TCM размещается на этом же сервере. Сервер должен находиться в том же файле, что и секция tcm:;
• Если name не найден в servers: — создаётся новый сервер TCM. В этом случае обязательно укажите host и user, иначе Ansible не сможет подключиться по SSH;
• tcm_initial_clusters генерируется автоматически из кластеров текущего файла;
• При использовании нескольких файлов динамического инвентаря (например, --inventory file1.yml --inventory file2.yml) секцию tcm: достаточно указать в одном из файлов. Кластеры из всех файлов аккумулируются в tcm_initial_clusters автоматически.

Блок TLS в tcm_initial_clusters для каждого кластера генерируется автоматически на основе переменных из секции constants::

• TLS включается, если tarantool_etcd_schema_definition имеет значение "https";
• cert-file, key-file, trusted-ca-file берутся из tarantool_config_etcd_ssl_cert_file, tarantool_config_etcd_ssl_key_file, tarantool_config_etcd_ssl_ca_file (общие переменные, также используемые экземплярами Tarantool);
• insecure-skip-verify и skip-client-san-verify управляются переменными tcm_cluster_etcd_tls_skip_verify и tcm_cluster_etcd_tls_skip_san_verify соответственно (только для TCM, не влияют на Tarantool);
• Jinja2-выражения в значениях переменных (например, {{ tarantool_config_etcd_ssl_ca_path }}/rootCA.crt) разрешаются автоматически на этапе генерации инвентаря.

Подробнее о переменных TLS для initial_clusters — в разделе TCM → etcd кластера через initial_clusters.

{alert} Секция tcm: и секция constants: настраивают разные подключения TCM к etcd:

• tcm_etcd_tls_* в секции tcm: — подключение TCM к собственному etcd (хранение состояния TCM);
• tarantool_config_etcd_ssl_* и tcm_cluster_etcd_tls_* в секции constants: — подключение TCM к etcd кластера (через initial_clusters).

Если TCM и кластер используют один и тот же etcd, значения переменных могут совпадать, но это разные подключения с независимыми настройками TLS. {/alert}

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

 
ansible-inventory -i path/to/config.yml --graph

Чтобы посмотреть переменные у хостов, вызовите команду ниже:

 
ansible-inventory -i path/to/config.yml --list