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

В этом руководстве описано, как создать файл динамического инвентаря с использованием плагина 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: удаляет серверы из кластера.

 
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. Создание новых репликасетов через эту команду не поддерживается.

• 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 учитывает все экземпляры данного компонента на сервере, включая уже существующие.

Тип изменения 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 шардов (storage-репликасетов). Количество вычисляется как ⌈общее_число_шардов / 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, автогенерация для неё пропускается — используется пользовательское значение.

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

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

В секции 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 автоматически.

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

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

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

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