Развертывание кластера через Ansible¶

В данном разделе приведена информация по развёртыванию кластера Picodata из нескольких инстансов, запущенных на разных серверах посредством роли picodata-ansible.

Внимание!

Информация приведена для версии роли 25.5.1 и выше

Требования к оборудованию и ПО¶

Для промышленной эксплуатации кластера следует учитывать базовые требования к оборудованию и программному обеспечению:

наличие подготовленных серверов с поддерживаемыми ОС на базе Linux (см. список)
минимальный расчет ресурсов на 1 инстанс (без учета ресурсов для ОС): 1 ядро ЦП, 64 МБ ОЗУ, 512 МБ дискового пространства
у пользователя, запускающего роль, должны быть права на запись в текущей директории
версия ansible: 2.9 – 2.15
версия python: 3.8 – 3.13

Установка роли¶

Установите роль из репозитория через ansible-galaxy:

ansible-galaxy install -f git+https://git.picodata.io/core/picodata-ansible.git

или создайте файл requirements.yml со следующим содержимым:

- src: https://git.picodata.io/core/picodata-ansible.git
  scm: git

При необходимости укажите нужную версию роли:

- src: https://git.picodata.io/core/picodata-ansible.git
  scm: git
  version: 25.5.1

и затем выполните команду:

ansible-galaxy install -fr requirements.yml

Создание директорий¶

В текущей директории создайте поддиректории — это нужно для отделения инвентарных файлов от сценариев (плейбуков):

mkdir {hosts,playbooks}

Создание инвентарного файла¶

Рассмотрим два сценария: простой кластер с единственным тиром и кластер из нескольких тиров. Пусть в распоряжении есть два сервера: 192.168.0.1 и 192.168.0.2.

Создайте инвентарный файл hosts/cluster.yml и наполните его в зависимости от нужного сценария содержанием ниже.

Простой кластер на нескольких серверах¶

cluster.yml

all:
  vars:
    install_packages: true                           # для установки пакета picodata из репозитория
    cluster_name: simple_cluster                     # имя кластера
    first_bin_port: 13301                            # начальный бинарный порт для первого инстанса
    first_http_port: 18001                           # начальный http-порт для первого инстанса для веб-интерфейса

    tiers:                                           # описание тиров
      default:                                       # имя тира (default)
        instances_per_server: 2                      # сколько инстансов запустить на каждом сервере этого тира

G1:                                                  # имя датацентра (используется для failure_domain)
  hosts:                                             # далее перечисляем серверы в датацентре
    server-1:                                        # имя сервера в инвентарном файле (используется для failure_domain)
      ansible_host: 192.168.0.1                      # IP-адрес или fqdn если не совпадает с предыдущей строкой
G2:                                                  # имя датацентра (используется для failure_domain)
  hosts:                                             # далее перечисляем серверы в датацентре
    server-2:                                        # имя сервера в инвентарном файле (используется для failure_domain)
      ansible_host: 192.168.0.2                      # IP-адрес или fqdn если не совпадает с предыдущей строкой

Кластер из двух тиров на нескольких серверах¶

Пример инвентарного файла для 4-х серверов, расположенных в 3-х датацентрах (DC1, DC2 и DC3):

cluster.yml

all:
  vars:
    ansible_user: vagrant      # пользователь для ssh-доступа к серверам

    repo: 'https://download.picodata.io'  # репозиторий, откуда инсталлировать пакет picodata

    cluster_name: 'demo'           # имя кластера
    admin_password: '123asdZXV'    # пароль пользователя admin

    default_bucket_count: 23100    # количество бакетов в каждом тире (по умолчанию 30000)

    audit: false                   # состояние аудита (отключен)
    log_level: 'info'              # уровень отладки
    log_to: 'file'                 # вывод журнала в файлы (а не в journald)

    conf_dir: '/etc/picodata'         # директория для хранения конфигурационных файлов
    data_dir: '/var/lib/picodata'     # директория для хранения данных
    run_dir: '/var/run/picodata'      # директория для хранения sock-файлов
    log_dir: '/var/log/picodata'      # директория для журналов и файлов аудита
    share_dir: '/usr/share/picodata'  # директория для размещения служебных данных (плагинов)

    listen_address: '{{ ansible_fqdn }}'     # адрес, который будет слушать инстанс. Для IP указать {{ ansible_default_ipv4.address }}
    pg_address: '{{ listen_address }}'       # адрес, который будет слушать PostgreSQL-протокол инстанса

    first_bin_port: 13301          # начальный бинарный порт для первого инстанса
    first_http_port: 18001         # начальный http-порт для первого инстанса для веб-интерфейса
    first_pg_port: 15001           # начальный номер порта для PostgreSQL-протокола инстансов кластера

    tiers:                         # описание тиров
      arbiter:                     # имя тира
        replicaset_count: 1        # количество репликасетов
        replication_factor: 1      # фактор репликации
        config:
          memtx:
            memory: 64M            # количество памяти, выделяемое каждому инстансу тира
        host_groups:
          - ARBITERS               # целевая группа серверов для установки инстансов тира

      default:                     # имя тира
        replicaset_count: 3        # количество репликасетов
        replication_factor: 3      # фактор репликации
        bucket_count: 16384        # количество бакетов в тире
        config:
          memtx:
            memory: 71M            # количество памяти, выделяемое каждому инстансу тира
        host_groups:
          - STORAGES               # целевая группа серверов для установки инстансов тира

    db_config:                     # параметры конфигурации кластера (см. https://docs.picodata.io/picodata/stable/reference/db_config)
      governor_auto_offline_timeout: 30
      iproto_net_msg_max: 500
      memtx_checkpoint_count: 1
      memtx_checkpoint_interval: 7200

    plugins:
      example:                                                  # плагин
        path: '../plugins/weather_0.1.0-ubuntu-focal.tar.gz'    # путь до пакета плагина
        config: '../plugins/weather-config.yml'                 # путь до файла с настройками плагина
        services:
          weather_service:
            tiers:                                                  # список тиров, в которые устанавливается сервис плагина
              - default                                             # указано значение по умолчанию (default)

DC1:                                # имя датацентра (failure_domain)
  hosts:                            # серверы в датацентре
    server-1-1:                     # имя сервера в инвентарном файле
      ansible_host: '192.168.19.21' # IP-адрес или fqdn если не совпадает с предыдущей строкой
      host_group: 'STORAGES'        # определение целевой группы серверов для установки инстансов

    server-1-2:                     # имя сервера в инвентарном файле
      ansible_host: '192.168.19.22' # IP-адрес или fqdn если не совпадает с предыдущей строкой
      host_group: 'ARBITERS'        # определение целевой группы серверов для установки инстансов тира arbiter

DC2:                                # имя датацентра (failure_domain)
  hosts:                            # серверы в датацентре
    server-2-1:                     # имя сервера в инвентарном файле
      ansible_host: '192.168.20.21' # IP-адрес или fqdn если не совпадает с предыдущей строкой
      host_group: 'STORAGES'        # определение целевой группы серверов для установки инстансов

DC3:                                # имя датацентра (failure_domain)
  hosts:                            # серверы в датацентре
    server-3-1:                     # имя сервера в инвентарном файле
      ansible_host: '192.168.21.21' # IP-адрес или fqdn если не совпадает с предыдущей строкой
      host_group: 'STORAGES'        # определение целевой группы серверов для установки инстансов

Изменение параметров роли¶

Параметры роли, используемые по умолчанию, располагаются в файле defaults/main.yml; их также можно переопределять в инвентарном файле.

Помимо параметров по умолчанию, используется словарь tiers с указанием внутри:

имени тира (например arbiter)
количества инстансов на каждом сервере (instances_per_server) или количества репликасетов (replicaset_count)
фактора репликации (replication_factor) для тира (по умолчанию равен 1)

Пример словаря tiers:

tiers:
  default:                     # имя тира default
    replicaset_count: 2        # количество репликасетов
    replication_factor: 3      # фактор репликации
    bucket_count: 16384        # количество бакетов в тире
    config:
      memtx:
        memory: 128M           # количество памяти, предоставляемое непосредственно на хранение данных

См также:

Переменные, используемые в роли Ansible

Расчет количества инстансов/репликасетов¶

В инвентарном файле для тиров можно указывать количество как инстансов на каждом сервере, так и репликасетов. При этом, во втором случае значение instances_per_server будет рассчитано автоматически. Если при расчете будет получено дробное значение, то роль остановится с ошибкой.

Если указаны оба параметра, то приоритет у instances_per_server

Количество репликасетов в кластере¶

replicaset_count = instances_per_server * SERVER_COUNT / replication_factor

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

Количество инстансов на одном сервере¶

instances_per_server = replicaset_count * replication_factor / SERVER_COUNT

Аналогично, если при расчете вы получаете дробное число, значит количество серверов или фактор репликации подобраны некорректно и это необходимо исправить.

Создание плейбука¶

Для подключения роли создайте плейбук playbooks/picodata.yml, добавив в него следующее содержание:

picodata.yml

---
- name: Deploy picodata cluster
  hosts: all
  become: true

  tasks:

  - name: Import picodata-ansible role
    ansible.builtin.import_role:
      name: picodata-ansible

Установка кластера¶

Выполните установку кластера командой:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml

При успешном окончании выполнения плейбука будет создан yaml-файл report.yml с перечислением всех инстансов и портов кластера.

Более подробно о доступных переменных в инвентарном файле можно узнать в статье Переменные, используемые в роли Ansible

См. также:

Управление кластером¶

Для управления кластером используйте теги роли, указав их после параметра -t.

Список поддерживаемых тегов:

Имя	Описание
backup	Создание резервной копии кластера
command	Выполнение lua-команд на инстансах
crash_dump	Сбор файлов необходимых для анализа разработчиками в случае сбоя кластера
deploy	Установка кластера. Используется по умолчанию, если не указаны другие тэги
deploy_become, remove_become	Используются для установки/удаления кластера в режиме rootless
expand	Добавление новых инстансов в кластер на существующих серверах
genin	Получить список инстансов в разбивке для каждого сервера (используется в других сценариях )
install_pkgs	Установка пакета Picodata. Также используется при установке кластера
plugins	Установка и конфигурация плагинов
rebootstrap	Ребутстрап инстанса
remove	Удаление кластера
report	Генерация файлов `report`
restart	Перезапуск всех инстансов на всех серверах
restore	Восстановление из резервной копии кластера
restore_full	Установка кластера и восстановление из резервной копии
start	Запуск всех инстансов на всех серверах после остановки
stop	Остановка всех инстансов на всех серверах

Установка пакета picodata¶

Пример команды для установки пакета picodata (если не указана переменная picodata_package_path, то на серверах будет подключен репозиторий picodata):

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t install_pkgs

Получение информации о кластере¶

Пример команды для получения информации об именах инстансов кластера с их привязкой к серверам:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t genin

Удаление кластера¶

Пример команды для удаления кластера:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t remove

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

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

Внимание!

Для добавления новых серверов в кластер нужно запускать роль с тегом deploy

Укажите новое количество инстансов или репликасетов в инвентарном файле и выполните команду:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t expand

Ребутстрап инстанса¶

Применяется в случае выхода инстанса из строя и невозможности его ввода в репликасет кластера в обычном порядке.

Внимание!

Проводить ребутстрап инстанса можно только в репликасетах с фактором репликации 2 и более, при этом инстанс не должен быть последним работающим в репликасете

Пример команды для ребутстрапа инстанса с именем default_1_2:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t rebootstrap -e "instance=default_1_2"

Резервное копирование и восстановление кластера¶

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

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t backup

Пример команды для восстановления кластера в случае, если кластер уже развернут:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t restore

Пример команды для восстановления кластера на пустых серверах (будет развернут кластер и выполнено восстановление из последней резервной копии):

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t restore_full

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

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t restore -e restore_dir=20250716203059

Внимание!

Восстановление из последней резервной копии работает только при выставленной переменной backup_fetch в true (т.е. когда резервные копии выкачиваются на станцию запуска Ansible). В остальных случаях необходимо указывать переменную restore_dir!

См. также:

Резервное копирование и восстановление

Управление плагинами¶

C помощью роли picodata-ansible можно также добавлять в кластер плагины и их конфигурации. Для этого модифицируйте инвентарный файл hosts/cluster.yml, добавив в него блок plugins. Пример инвентарного файла, поддерживающего установку в кластер c одним тиром тестового плагина weather:

cluster.yml

all:
  vars:
    install_packages: true                           # для установки пакета picodata из репозитория
    cluster_name: simple_cluster                     # имя кластера
    first_bin_port: 13301                            # начальный бинарный порт для первого инстанса (он же main_peer)
    first_http_port: 18001                           # начальный http-порт для первого инстанса для веб-интерфейса

    tiers:                                           # описание тиров
      default:                                       # имя тира (default)
        bucket_count: 20000                          # сколько бакетов будет размещено на данном тире
        instances_per_server: 2                      # сколько инстансов запустить на каждом сервере этого тира

    plugins:                                         # описание плагинов
      example:                                       # имя плагина в Ansible (может не совпадать с именем в Picodata)
        path: '../plugins/weather_0.1.0.tar.gz'      # путь к архиву с плагином
        config: '../plugins/weather-config.yml'      # путь к файлу конфигурации плагина
        services:
          weather_service:
            tiers:                                   # список тиров, в которые устанавливается сервис плагина
              - default                              # указано значение по умолчанию (default)

G1:                                                  # имя группы серверов (используется для failure_domain)
  hosts:                                             # далее перечисляем серверы в датацентре
    server-1:                                        # имя сервера в инвентарном файле (используется для failure_domain)
      ansible_host: 192.168.0.1                      # IP-адрес или fqdn если не совпадает с предыдущей строкой
G2:                                                  # имя группы серверов (используется для failure_domain)
  hosts:                                             # далее перечисляем серверы в датацентре
    server-2:                                        # имя сервера в инвентарном файле (используется для failure_domain)
      ansible_host: 192.168.0.2                      # IP-адрес или fqdn если не совпадает с предыдущей строкой

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

См. также:

Управление плагинами

Модифицировать файл плейбука не требуется.

Выполните установку плагинов в кластер командой:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t plugins

Примечание

С помощью роли Ansible можно только добавлять и обновлять плагины в кластере. Удаление производится вручную.

Действия при авариях¶

Пример команды для сбора информации после сбоя кластера для отправки ее в техподдержку Picodata:

ansible-playbook -i hosts/cluster.yml playbooks/picodata.yml -t crash_dump

Будет собрана вся информация для расследования инцидента. После выполнения следует передать файлы "*_crash_dump.tar.gz" из директории backup_fetch_dir/cluster_name/ (backup_fetch_dir и cluster_name — переменные из инвентарного файла. Если не определены, то используются значения по умолчанию) в техническую поддержку компании Picodata.

Мониторинг кластера¶

Для мониторинга развернутого кластера Picodata используйте dashboard для Grafana. Мы предоставляем заранее сконфигурированный dashboard-файл Picodata.json, который можно импортировать в интерфейсе Grafana и использовать для отслеживания состояния кластера (в том числе, отслеживать изменения состава и роли узлов), а также для оперативного доступа к метрикам Picodata.

Dashboard позволяет следить за производительностью кластера, оперативно реагировать на инциденты и устранять неполадки.

Для удобства добавления инстансов в конфигурационный файл Prometheus можно взять секцию prometheus из файла report.yml, который создается после выполнения роли Ansible.

Читайте далее:

Dashboard для Grafana