Файл конфигурации¶

Файл конфигурации содержит параметры кластера и инстанса для запуска Picodata.

Назначение файла конфигурации¶

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

Команда для запуска инстанса Picodata, если файл конфигурации назван picodata.yaml и расположен в директории вызова команды:

picodata run

Команда для запуска инстанса Picodata в остальных случаях:

picodata run --config <PATH>

где <PATH> — путь к файлу конфигурации в формате YAML.

См. также:

picodata run --config

Порядок применения параметров¶

Параметры командной строки имеют более высокий приоритет, чем файл конфигурации. Соответственно, используя параметр --config-parameter, можно переопределить нужные параметры запуска Picodata. Уровни вложения параметра разделяются точкой. Например:

picodata run --config ./picodata_config.yaml -c instance.log.level=verbose

Ограничение

Параметры тиров нельзя переопределить отдельно — вместо этого следует указать в командной строке всю секцию cluster.tier. Например:

picodata run --config ./picodata_config.yaml -c
cluster.tier='{"default": {"replication_factor": 3, "can_vote":
true}}'

Параметры тиров, которые при этом указаны в файле конфигурации, будут проигнорированы

Описание файла конфигурации¶

Для начала работы с файлом конфигурации создайте его шаблон, выполнив команду picodata config default -o picodata.yaml. Файл конфигурации содержит параметры в формате YAML на следующих уровнях вложения:

cluster — расположенные на этом уровне параметры относятся ко всему кластеру
tier — параметры отдельных тиров
instance — параметры текущего инстанса

Таким образом, различающиеся настройки разных инстансов на уровне instance следует разделить по разным файлам конфигурации. Настройки более высоких уровней (cluster и tier) будут использованы только один раз при первоначальном создании кластера и их последующее изменение в файле конфигурации будет проигнорировано.

Структура файла конфигурации:

picodata.yaml

cluster:
  name: demo # (3)!
  tier:
    default:
      replication_factor: 1 # (7)!
      bucket_count: 3000 # (5)!
      can_vote: true # (6)!
  default_replication_factor: 1 # (1)!
  default_bucket_count: 3000 # (2)!
  shredding: false # (4)!
instance:
  instance_dir: . # (14)!
  backup_dir: ./backup # (41)!
  name: null # (22)!
  replicaset_name: null # (28)!
  tier: default # (29)!
  failure_domain: {} # (12)!
  peer: # (23)!
  - 127.0.0.1:3301
  iproto_listen: 127.0.0.1:3301 # (15)!
  iproto_advertise: 127.0.0.1:3301 # (9)!
  http_listen: null # (13)!
  admin_socket: ./admin.sock # (8)!
  share_dir: null # (27)!
  audit: null # (10)!
  log:
    level: info # (19)!
    destination: null # (17)!
    format: plain # (18)!
  memtx:
    memory: 64M # (21)!
    max_tuple_size: 1M # (20)!
  vinyl:
    memory: 128M # (31)!
    cache: 128M # (30)!
    bloom_fpr: 0.05 # (32)!
    max_tuple_size: 1M # (33)!
    page_size: 8K # (34)!
    range_size: 1G # (35)!
    run_count_per_level: 2 # (36)!
    run_size_ratio: 3.5 # (37)!
    read_threads: 1 # (38)!
    write_threads: 4 # (39)!
    timeout: 60.0 # (40)!
  pg:
    listen: 127.0.0.1:4327 # (25)!
    advertise: 127.0.0.1:4327 # (24)!
    ssl: false # (26)!
  iproto_tls:
    enabled: false # (16)!
  boot_timeout: 7200 # (11)!

cluster.default_replication_factor
cluster.default_bucket_count
cluster.name
cluster.shredding
cluster.tier.<tier_name>.bucket_count
cluster.tier.<tier_name>.can_vote
cluster.tier.<tier_name>.replication_factor
instance.admin_socket
instance.iproto_advertise
instance.audit
instance.boot_timeout
instance.failure_domain
instance.http_listen
instance.instance_dir
instance.iproto_listen
instance.iproto_tls
instance.log.destination
instance.log.format
instance.log.level
instance.memtx.max_tuple_size
instance.memtx.memory
instance.name
instance.peer
instance.pg.advertise
instance.pg.listen
instance.pg.ssl
instance.share_dir
instance.replicaset_name
instance.tier
instance.vinyl.cache
instance.vinyl.memory
instance.vinyl.bloom_fpr
instance.vinyl.max_tuple_size
instance.vinyl.page_size
instance.vinyl.range_size
instance.vinyl.run_count_per_level
instance.vinyl.run_size_ratio
instance.vinyl.read_threads
instance.vinyl.write_threads
instance.vinyl.timeout
instance.backup_dir

См. также:

picodata config default

Параметры файла конфигурации¶

cluster.default_bucket_count¶

Число бакетов в кластере по умолчанию.

Данные:

Тип: int
Значение по умолчанию: 3000

Данный параметр задается только в файле конфигурации.

cluster.default_replication_factor¶

Число реплик — инстансов с одинаковым набором хранимых данных — для каждого репликасета.

Данные:

Тип: int
Значение по умолчанию: 1

Аналогичная переменная окружения: PICODATA_INIT_REPLICATION_FACTOR
Аналогичная команда: picodata run --init-replication-factor

cluster.name¶

Имя кластера. Инстанс не сможет присоединиться к кластеру с другим именем.

Данные:

Тип: str
Значение по умолчанию: demo

Аналогичная переменная окружения: PICODATA_CLUSTER_NAME
Аналогичная команда: picodata run --cluster-name

cluster.shredding¶

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

Данные:

Тип: bool
Значение по умолчанию: false

Аналогичная переменная окружения: PICODATA_SHREDDING
Аналогичная команда: picodata run --shredding

cluster.tier.<tier_name>.bucket_count¶

Число бакетов в данном тире.

Данные:

Тип: int
Значение по умолчанию: 3000

Данный параметр задается только в файле конфигурации.

cluster.tier.<tier_name>.can_vote¶

Признак тира <tier_name>, определяющий возможность инстансов участвовать в голосовании на выборах raft-лидера.

Данные:

Тип: bool
Значение по умолчанию: true

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c cluster.tier='{"default": {"replication_factor": 1, "can_vote": false}}'

См. также:

Динамическое переключение голосующих узлов в Raft

cluster.tier.<tier_name>.replication_factor¶

Фактор репликации тира <tier_name>.

Данные:

Тип: int
Значение по умолчанию: 1

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c cluster.tier='{"default": {"replication_factor": 3, "can_vote": true}}'

instance.admin_socket¶

Путь к unix-сокету для подключения к консоли администратора с помощью команды picodata admin. В отличие от пользовательской консоли, коммуникация осуществляется в виде обычного текста и всегда происходит под учетной записью администратора.

Данные:

Тип: str
Значение по умолчанию: ./admin.sock

Аналогичная переменная окружения: PICODATA_ADMIN_SOCK
Аналогичная команда: picodata run --admin-sock

instance.audit¶

Конфигурация журнала аудита. Доступны следующие варианты:

file:<FILE> или просто <FILE> — запись в файл
pipe:<COMMAND> или | <COMMAND> — перенаправление вывода в подпроцесс
syslog: — перенаправление вывода в службу syslog защищенной ОС

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_AUDIT_LOG
Аналогичная команда: picodata run --audit

instance.backup_dir¶

Директория для хранения резервных копий, создаваемых командой BACKUP. Каждый инстанс сохраняет данные в поддиректории внутри backup-dir в файле, имя которого формируется в формате YYYYMMDDThhmmss.

Данные:

Тип: str
Значение по умолчанию: <instance-dir>/backup

Аналогичная переменная окружения: PICODATA_BACKUP_DIR
Аналогичная команда: picodata run --backup-dir

instance.boot_timeout¶

Максимальное время в секундах, в течение которого instance может находиться в ожидании загрузки перед присоединением к кластеру, после чего он автоматически отключается.

Данные:

Тип: int
Значение по умолчанию: 7200 (2 часа)

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.boot_timeout=3600

instance.failure_domain¶

Список пар ключ-значение, разделенных запятыми, определяющий домен отказа инстанса. Набор параметров домена отказа позволяет указать расположение сервера, на котором запущен инстанс, в стойке, датацентре, регионе и т.д. Набор ключей может быть произвольным. Picodata не будет объединять два инстанса в один репликасет, если у них совпадают значения хотя бы в одном ключе — вместо этого будет создан новый репликасет. Репликасеты формируются из инстансов с разными доменами отказа до тех пор, пока не будет достигнут желаемый фактор репликации.

Данные:

Тип: Block Mappings of { str: str }
Значение по умолчанию: {}

Аналогичная переменная окружения: PICODATA_FAILURE_DOMAIN
Аналогичная команда: picodata run --failure-domain

Синтаксис значений домена отказа различается при работе c файлом конфигурации (массив данных) и при использовании в командной строке (список пар ключ=значение). Примеры показаны ниже.

Использование в файле конфигурации:

failure_domain: { "region":"['us']","zone":"us-west-1" }

failure_domain: { "rack":"['12-90']","server":"srv_007", "vm":"rhel8" }

Использование в командной строке:

picodata run --failure-domain=region=us,zone=us-west-1

picodata run --failure-domain=rack=12-90,server=srv_007,vm=rhel8

Использование в переменной:

export PICODATA_FAILURE_DOMAIN=region=us,zone=us-west-1

export PICODATA_FAILURE_DOMAIN=rack=12-90,server=srv_007,vm=rhel8

Значения домена отказа во всех случаях не зависят от регистра.

instance.http_listen¶

Адрес HTTP-сервера.

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_HTTP_LISTEN
Аналогичная команда: picodata run --http-listen

instance.instance_dir¶

Рабочая директория инстанса. Здесь Picodata хранит все данные.

Данные:

Тип: str
Значение по умолчанию: .

Аналогичная переменная окружения: PICODATA_INSTANCE_DIR
Аналогичная команда: picodata run --instance-dir

instance.iproto_advertise¶

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

Данные:

Тип: str
Значение по умолчанию: 127.0.0.1:3301

Аналогичная переменная окружения: PICODATA_IPROTO_ADVERTISE
Аналогичная команда: picodata run --iproto-advertise

instance.iproto_listen¶

Сетевой адрес инстанса.

Данные:

Тип: str
Значение по умолчанию: 127.0.0.1:3301

Аналогичная переменная окружения: PICODATA_IPROTO_LISTEN
Аналогичная команда: picodata run --iproto-listen

instance.iproto_tls¶

Конфигурация защищенного режима для внутренней коммуникации между узлами кластера по протоколу Iproto. Основной параметр instance.iproto_tls.enabled отвечает за включение/отключение режима шифрования mutual TLS (mTLS).

Тип: bool
Значение по умолчанию: false

При установке значения true требуется использовать 3 дополнительных параметра:

instance.iproto_tls.cert_file (str) — путь к файлу сертификата
instance.iproto_tls.key_file (str) — путь к файлу с закрытым ключом
instance.iproto_tls.ca_file (str) — путь к файлу корневого сертификата

При включенном mTLS блок настроек файла конфигурации будет иметь следующий вид:

  iproto_tls:
    enabled: true
    cert_file: tls/server.crt
    key_file: tls/server.key
    ca_file: tls/ca.crt

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.iproto_tls.enabled=true -c instance.iproto_tls.cert_file=tls/server.crt -c instance.iproto_tls.key_file=tls/server.key -c instance.iproto_tls.ca_file=tls/ca.crt

Режим mTLS настраивается глобально во всем кластере. Для параметров instance.iproto_tls.cert_file и instance.iproto_tls.key_file содержимое файлов должно быть идентичным на каждом инстансе.

instance.log.destination¶

Конфигурация отладочного журнала. Доступны следующие варианты:

file:<FILE> или просто <FILE> — запись в файл
pipe:<COMMAND> или | <COMMAND> — перенаправление вывода в подпроцесс
syslog: — перенаправление вывода в службу syslog защищенной ОС

По умолчанию отладочный журнал выводится в stderr.

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_LOG
Аналогичная команда: picodata run --log

instance.log.format¶

Формат отладочного журнала.

Возможные значения: plain, json

Данные:

Тип: str
Значение по умолчанию: plain

Аналогичная переменная окружения: PICODATA_LOG
Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.log.format=json

instance.log.level¶

Уровень важности событий, регистрируемых в отладочном журнале.

Возможные значения: fatal, system, error, crit, warn, info, verbose, debug

Данные:

Тип: str
Значение по умолчанию: info

Аналогичная переменная окружения: PICODATA_LOG_LEVEL
Аналогичная команда: picodata run --log-level

instance.memtx.max_tuple_size¶

Максимальный размер кортежа в байтах для движка хранения memtx.

Данные:

Тип: int
Значение по умолчанию: 1M (1048576 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.memtx.max_tuple_size=2M

Аналогичная переменная окружения: PICODATA_MEMTX_MAX_TUPLE_SIZE
Аналогичная команда: picodata run --memtx-max-tuple-size

instance.memtx.memory¶

Объем памяти в байтах, выделяемый для хранения кортежей. Когда достигается лимит использования памяти, запросы команд INSERT и UPDATE начинают отклоняться с ошибкой ER_MEMORY_ISSUE. Сервер хранит в выделяемом объеме памяти только кортежи — для хранения индексов и информации о соединениях используется дополнительная память.

Минимальное значение — 33,554,432 байтов (32 МБ)

Данные:

Тип: int
Значение по умолчанию: 64M (67108864 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Пример:

picodata run -c instance.memtx.memory=128M

Аналогичная переменная окружения: PICODATA_MEMTX_MEMORY
Аналогичная команда: picodata run --memtx-memory

instance.memtx.system_memory¶

Объем памяти в байтах, выделяемый для хранения кортежей и индексов системных таблиц. Когда достигается лимит использования памяти, запросы команд INSERT и UPDATE начинают отклоняться с ошибкой ER_MEMORY_ISSUE. Сервер хранит в выделяемом объеме памяти только кортежи — для хранения индексов и информации о соединениях используется дополнительная память.

Минимальное значение — 33,554,432 байтов (32 МБ)

Данные:

Тип: int
Значение по умолчанию: 256M (268435456 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Пример:

picodata run -c instance.memtx.system_memory=128M

Аналогичная переменная окружения: PICODATA_MEMTX_SYSTEM_MEMORY
Аналогичная команда: picodata run --memtx-system-memory

instance.name¶

Имя инстанса. При отсутствии параметра значение будет автоматически сгенерировано raft-лидером в момент присоединения инстанса к кластеру. Генератор имен использует следующую схему: имя тира, номер репликасета, номер инстанса в данном репликасете, с разделением через знак подчеркивания.

Пример: default_1_1.

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_INSTANCE_NAME
Аналогичная команда: picodata run --instance-name

instance.peer¶

Список сетевых адресов других инстансов, разделенных запятыми. Используется при инициализации кластера и присоединении инстанса к уже существующему кластеру.

Данные:

Тип: Block Sequence of str
Значение по умолчанию: - 127.0.0.1:3301

Пример:

picodata run -c instance.peer='["127.0.0.1:3301", "127.0.0.1:3302"]'

Аналогичная переменная окружения: PICODATA_PEER
Аналогичная команда: picodata run --peer

instance.pg.advertise¶

Публичный адрес сервера для подключения по протоколу PostgreSQL. Анонсируется кластеру при запуске инстанса.

Данные:

Тип: str
Значение по умолчанию: 127.0.0.1:4327

Аналогичная переменная окружения: PICODATA_PG_ADVERTISE
Аналогичная команда: picodata run --pg-advertise

instance.pg.listen¶

Адрес сервера для подключения по протоколу PostgreSQL.

Данные:

Тип: str
Значение по умолчанию: 127.0.0.1:4327

Аналогичная переменная окружения: PICODATA_PG_LISTEN
Аналогичная команда: picodata run --pg-listen

instance.pg.ssl¶

Признак использования протокола TLS/SSL или mTLS при подключении по протоколу PostgreSQL.

Если для признака указано значение true, в рабочей директории инстанса <INSTANCE_DIR> должны находиться TLS-сертификат и закрытый ключ:

server.crt
server.key

Для двусторонней проверки подлинности (mTLS) требуется разместить рядом файл корневого сертификата:

ca.crt

Данные:

Тип: bool
Значение по умолчанию: false

Размещение файлов сертификатов и закрытого ключа можно переопределить, используя следующие 3 дополнительных параметра:

instance.pg.cert_file (str) — путь к файлу сертификата
instance.pg.key_file (str) — путь к файлу с закрытым ключом
instance.pg.ca_file (str) — путь к файлу корневого сертификата

При включенном mTLS блок настроек файла конфигурации будет иметь следующий вид:

  pg:
    enabled: true
    cert_file: tls/server.crt
    key_file: tls/server.key
    ca_file: tls/ca.crt

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.pg_ssl.enabled=true -c instance.pg.cert_file=tls/server.crt -c instance.pg.key_file=tls/server.key -c instance.pg.ca_file=tls/ca.crt

Режим mTLS настраивается глобально во всем кластере. Для параметров instance.iproto_tls.cert_file и instance.iproto_tls.key_file содержимое файлов должно быть идентичным на каждом инстансе.

instance.replicaset_name¶

Имя репликасета. Используется при инициализации кластера и присоединении инстанса к уже существующему кластеру. При отсутствии параметра имя репликасета будет сгенерировано автоматически. Генератор имен использует следующую схему: имя тира, номер репликасета в данном тире, с разделением через знак подчеркивания.

Пример: default_1.

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_REPLICASET_NAME
Аналогичная команда: picodata run --replicaset-name

instance.share_dir¶

Путь к директории, содержащей файлы плагинов.

Данные:

Тип: str
Значение по умолчанию: null

Аналогичная переменная окружения: PICODATA_SHARE_DIR
Аналогичная команда: picodata run --share-dir

instance.tier¶

Имя тира, которому будет принадлежать инстанс. Используется при инициализации кластера и присоединении инстанса к уже существующему кластеру.

Данные:

Тип: str
Значение по умолчанию: default

Аналогичная переменная окружения: PICODATA_INSTANCE_TIER
Аналогичная команда: picodata run --tier

instance.vinyl.bloom_fpr¶

Вероятность ложноположительного срабатывания фильтра Блума для движка хранения vinyl, измеряемая в долях единицы.

Предельные значения:

bloom_fpr: 0 — ложноположительные срабатывания отсутствуют
bloom_fpr: 1 — все срабатывания ложноположительные

Данные:

Тип: float
Значение по умолчанию: 0.05

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.bloom_fpr=0.10

instance.vinyl.cache¶

Размер кэша в байтах для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 128M (134217728 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.cache=256M

instance.vinyl.max_tuple_size¶

Максимальный размер кортежа в байтах для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 1M (1048576 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.max_tuple_size=2M

instance.vinyl.memory¶

Максимальное количество оперативной памяти в байтах, которое использует движок хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 128M (134217728 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.memory=256M

instance.vinyl.page_size¶

Размер страницы в байтах, используемой движком хранения vinyl для операций чтения и записи на диск.

Данные:

Тип: int
Значение по умолчанию: 8K (8192 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.page_size=16M

instance.vinyl.range_size¶

Максимальный размер LSM-поддерева по умолчанию в байтах для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 1G (1073741824 Б)

Для удобства при указании значения можно использовать суффиксы (K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), 1K = 1024).

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.range_size=2G

instance.vinyl.read_threads¶

Максимальное количество потоков чтения для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 1

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.read_threads=2

instance.vinyl.run_count_per_level¶

Максимальное количество файлов на уровне в LSM-дереве для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 2

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.run_count_per_level=4

instance.vinyl.run_size_ratio¶

Соотношение между размерами разных уровней в LSM-дереве для движка хранения vinyl.

Данные:

Тип: float
Значение по умолчанию: 3.5

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.run_size_ratio=7.0

instance.vinyl.timeout¶

Максимальное время обработки запроса движком хранения vinyl в секундах.

Данные:

Тип: float
Значение по умолчанию: 60.0

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.timeout=120.0

instance.vinyl.write_threads¶

Максимальное количество потоков записи для движка хранения vinyl.

Данные:

Тип: int
Значение по умолчанию: 4

Аналогичная команда — picodata run --config-parameter. Пример:

picodata run -c instance.vinyl.write_threads=8