2.16. Конфигурация системы (config.yml) | Tdg
Документация на русском языке
поддерживается сообществом
2. Руководство по эксплуатации 2.16. Конфигурация системы (config.yml)

2.16. Конфигурация системы (config.yml)

config.yml — основной файл конфигурации системы, в котором задана логика и порядок обработки входящих запросов, а также настройки кластерных ролей и других функций системы.

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

Рассмотрим структуру файла и логику настроек на примере ниже. В примере в качестве справочной информации приведены все возможные секции и параметры.

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

---
types: {__file: model.avsc}

functions:
  focus_decode: {__file: focus_decode.lua}
  focus_routing: {__file: focus_routing.lua}
  validate_coupon_payment: {__file: validate_coupon_payment.lua}
  focus_classifier: {__file: focus_classifier.lua}
  notification: {__file: notification.lua}
  single_task: {__file: single_task.lua}
  long_task: {__file: long_task.lua}

pipelines:
  connect_input_handle:
    - focus_routing
  coupon_payment_handle:
    - focus_decode
    - validate_coupon_payment
  focus_classifiers:
    - focus_classifier
  notification_filter:
    - notification
  single_task:
    - single_task
  long_task:
    - long_task

connector:
  input:
    - name: soap
      type: soap
      wsdl: {__file: Connect.wsdl}
      success_response_body: {__file: success_response_body.xml}
      error_response_body: {__file: error_response_body.xml}
      handlers:
        - function: Connect
          pipeline: connect_input_handle

    - name: http
      type: http
      pipeline: connect_input_handle

    - name: kafka
      type: kafka
      brokers:
        - localhost:9092
      topics:
        - orders
        - items
      group_id: kafka
      token_name: kafka_token
      pipeline: connect_input_handle

  output:
    - name: to_input_processor
      type: input_processor

    - name: to_external_http_service
      type: http
      url: http://localhost:8021/test_json_endpoint
      format: json

    - name: to_external_soap_service
      type: soap
      url: http://localhost:8020/test_soap_endpoint

    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: objects

    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@localhost
      subject: TDG_Objects
      timeout: 5
      ssl_cert: ssl.crt
      ssl_key: ssl.pem

    - name: dummy
      type: dummy

  routing:
    - key: input_processor
      output: to_input_processor

    - key: external_http_service
      output: to_external_http_service

    - key: external_soap_service
      output: to_external_soap_service

    - key: dummy
      output: dummy

input_processor:
  classifiers:
    - name: focus
      pipeline: focus_classifiers

  routing:
    - key: focus_couponpayment
      pipeline: coupon_payment_handle

    - key: focus_initiation
      pipeline: focus_catchall_handle

    - key: focus_ratechange
      pipeline: focus_catchall_handle

  storage:
    - key: focus_couponpayment
      type: CouponPayment

output_processor:
  focus_couponpayment:
    pipeline: notification_filter
    output: to_external_http_service
  unclassified:
    pipeline: notification_filter
    output: to_external_http_service

repair_queue:
  on_object_added:
    __unclassified__:
        postprocess_with_routing_key: unclassified

logger:
  rotate_log: true
  max_msg_in_log: 500000
  max_log_size: 10485760
  delete_by_n_msg: 1000

audit_log:
  enabled: true
  severity: INFO
  remove_older_than_n_hours: 12

tasks:
  task_1:
    kind: single_shot
    pipeline: single_task
    keep: 5
  task_2:
    kind: continuous
    pipeline: long_task
    pause_sec: 10
  task_3:
    kind: periodical
    pipeline: long_task
    schedule: "0 */5 * * * *"

task_runner:
  running_count_threshold: 100

jobs:
  max_jobs_in_parallel: 100

account_manager:
  only_one_time_passwords: true
  output:
    name: to_smtp
    options:
      subject: "Registration"
  password_change_timeout_seconds: 10
  block_after_n_failed_attempts: 5
  ban_inactive_more_seconds: 86400
  password_policy:
    min_length: 8
    include:
      lower: true
      upper: true
      digits: true
      symbols: false

pepper: 2d60ec7f-e9f0-4018-b354-c54907b9423d

auth_external: {__file: auth.lua}

notifier:
  mail_server:
    url: 127.0.0.1:2525
    from: TDG_repair_queue
    username: user
    password: passpass
    timeout: 5
    skip_verify_host: true
  users:
    - id: 1
      name: Petrov
      addr: petrov@mailserver.com

services:
  get_price:
    doc: "Get the item price by ID"
    function: get_price_by_id
    return_type: ItemPrice
    args:
      item_id: string

expiration:
  - type: CouponPayment
    lifetime_hours: 12
    delay_sec: 1800
    keep_version_count: 5

archivation:
  - type: Quotation
    lifetime_days: 7
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 104857600

hard-limits:
  scanned: 2000
  returned: 100

force_yield_limits: 1000

graphql_query_chache_size: 1000

vshard-timeout: 2

maintenance:
  clock_delta_threshold_sec: 5

gc:
  forced: true
  period_sec: 2
  steps: 20

tracing:
  base_url: localhost:9411/api/v2/spans
  api_method: POST
  report_interval: 0
  spans_limit: 100

sequence_generator:
  starts_with: 1
  range_width: 100

test-soap-data: {__file: test_object.json}

libraries:
  cache:
    __file: cached.lua
  utils:
    __file: utils.lua

welcome-message: |
  Hello! Let's start working with Tarantool Data Grid.

tdg-version: "== 1.7.0"

2.16.1. Секции

В файле конфигурации могут быть настроены следующие секции:

  • types — описание модели данных;
  • functions — описание функций;
  • pipelines — описание конвейеров обработки объектов;
  • connector — конфигурация роли connector;
  • input_processor — конфигурация роли input_processor;
  • output_processor — конфигурация роли output_processor;
  • repair_queue — настройки обработки объекта при попадании в ремонтную очередь;
  • logger — настройки роли logger;
  • audit_log — настройки журнала аудита;
  • tasks — конфигурация задач, выполняемых при помощи ролей scheduler и task_runner;
  • task_runner — дополнительные настройки роли task_runner;
  • jobs — настройки выполнения отложенных работ (jobs);
  • account_manager — настройки роли account_manager;
  • pepper — настройка, связанная с безопасностью паролей;
  • auth_external — настройки внешней авторизации;
  • notifier — настройки роли notifier;
  • ldap — настройки авторизации внешних пользователей и систем через LDAP;
  • services — конфигурация сервисов;
  • expiration — настройки времени жизни объектов и ограничения количества версий объектов;
  • archivation — настройки архивации объектов;
  • hard-limits — настройки ограничений для GraphQL-запросов;
  • force_yield_limits — ограничение на количество сканирований записей;
  • graphql_query_chache_size — размер кэша запросов GraphQL;
  • vshard-timeout — время ожидания запроса в модуле vshard;
  • maintenance — настройки, связанные с обслуживанием и диагностикой;
  • gc — настройки роли garbage_collector;
  • tracing — настройки роли tracing;
  • metrics — настройка просмотра метрик по нескольким адресам ресурсов (endpoints);
  • sequence_generator — настройки роли sequence_generator;
  • test-soap-data — текст запроса по умолчанию на вкладке Test;
  • libraries — настройки подключения сторонних библиотек;
  • welcome-message — текст приветственного сообщения;
  • tdg-version — проверка версии TDG при применении конфигурации.

2.16.1.1. types

Описание модели данных (типов объектов), которые будут сохраняться в системе. В качестве языка описания модели используется Avro Schema — см. подробнее раздел «Разработка доменной модели». Как правило, описание делается в отдельном файле с расширением .avsc, на который делается ссылка в этой секции. Например:

types: {__file: model.avsc}

2.16.1.2. functions

Описание функций, которые будут выполняться в конвейерах обработки объектов (секция pipelines). Для каждой функции указывается имя функции и исполняемая часть — Lua-код функции, который также обычно выносится в отдельный файл. Например:

functions:
  focus_routing: {__file: focus_routing.lua}

2.16.1.3. pipelines

Описание конвейеров обработки объектов (пайплайнов). Для каждого пайплайна указывается имя и входящие в него функции, заданные в секции functions. Например:

pipelines:
  connect_input_handle:
    - focus_routing

2.16.1.4. connector

Для кластерной роли connector настраиваются:

input

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

  • name — имя коннектора (произвольное);
  • type — тип коннектора. Поддерживаемые типы:
    • http — для запросов в формате JSON по HTTP;
    • soap — для запросов в формате XML (SOAP) по HTTP;
    • kafka — для интеграции с шиной данных Apache Kafka.
  • pipeline — конвейер обработки входящих объектов, определенный в секции pipelines.

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

type: soap

  • wsdl — схема WSDL, описывающая структуру входящего XML;
  • success_response_body — шаблон ответа в случае успешной обработки запроса;
  • error_response_body — шаблон ответа в случае ошибки;
  • handlers — обработчики входящего запроса.

Примечание

Шаблоны ответа опциональны (параметры success_response_body и error_response_body). Пользователь может задать шаблоны в нужном ему формате, соответствующем системе, в которую отправляется ответ; сам TDG ограничений на формат не накладывает. В шаблоне error_response_body возможно использовать один спецификатор форматирования %s, чтобы передать в тело ответа текст ошибки.

Например:

connector:
  input:
    - name: soap
      type: soap
      wsdl: {__file: Connect.wsdl}
      success_response_body: {__file: success_response_body.xml}
      error_response_body: {__file: error_response_body.xml}
      handlers:
        - function: Connect
          pipeline: connect_input_handle

type: kafka

  • brokers — адреса (URL) брокеров сообщений;
  • topics — топики (topics) в терминологии Kafka;
  • group_id — идентификатор группы подписчиков;
  • token_name — имя токена приложения. Необходимо вначале сгенерировать токен в системе (см. описание процедуры) и далее указать имя токена (name) в качестве значения параметра. Токен будет использоваться для авторизации при обработке входящих сообщений, которые коннектор забирает из шины данных Apache Kafka. Поскольку формат сообщений шины не дает возможности передать токен в самом сообщении, токен указывается в конфигурации коннектора;
  • options — служит для передачи опций в библиотеку librdkafka.
  • workers_count — задает количество читателей сообщений (workers), которые будут работать на коннекторе. Значение по умолчанию: 10. Параметр может быть полезен для случая, когда нужно гарантированно сохранить порядок чтения входящих сообщений. Если читателей сообщений несколько, то будет идти параллельная обработка нескольких сообщений сразу, и их порядок может быть нарушен. Чтобы гарантировать сохранение порядка, необходимо в кластере оставить один connector и один input_processor (подробнее про эти роли экземпляров TDG см. в главе Роли) и задать значение workers_count: 1.

Для типа Kafka в конфигурации можно задать более одного входящего коннектора. Например:

connector:
  input:
  - name: kafka-1
    type: kafka
    brokers:
      - localhost:9092
    topics:
      - orders-1
      - items-1
    group_id: kafka
    token_name: kafka_token
    pipeline: connect_input_handle
    workers_count: 1

  - name: kafka-2
    type: kafka
    brokers:
      - localhost:9092
    topics:
      - orders-2
      - items-2
    group_id: kafka
    token_name: kafka_token
    pipeline: connect_input_handle
    workers_count: 1

output

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

  • name — имя коннектора (произвольное).
  • type — тип коннектора. Поддерживаемые типы:
    • input_processor — для отправки объекта на роль input_processor;
    • http — для отправки объекта в формате JSON во внешнюю систему по HTTP;
    • soap — для отправки объекта в формате XML (SOAP) во внешнюю систему по HTTP;
    • kafka — для интеграции с шиной данных Apache Kafka;
    • smtp — для отправки запросов через SMTP-сервер;
    • dummy — для игнорирования объектов (пришедший объект никуда не отправляется).
  • headers– заголовки HTTP, которые при необходимости может установить пользователь при отправке данных во внешнюю систему.

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

type: http

  • url — URL внешней системы, куда отправляется объект;
  • format — формат, в котором отправляется объект. Для коннектора типа http формат — JSON.
  • options — опции параметра opts (из встроенного модуля Tarantool http).

Например:

connector:
    output:
        - name: to_external_http_service
          type: http
          url: http://localhost:8021
          format: json
          options:
            timeout: 5
            keepalive_idle: 60
            keepalive_interval: 60
            verify_host: true
            verify_peer: true
          headers:
            hello: world

type: soap

  • url — URL внешней системы, куда отправляется объект.

Например:

connector:
  output:
    - name: to_external_soap_service
      type: soap
      url: http://localhost:8020/test_soap_endpoint
      headers:
        config_header: header_for_soap

type: kafka

  • brokers — адреса (URL) брокеров сообщений;

  • topic — топик (topic) в терминологии Kafka;

  • format — формат, в котором оправляется сообщение в Kafka. Возможные значения: json и plain. Значение plain может применяться для случая, когда необходимо отправить в Kafka сообщение в формате XML. Значение по умолчанию: json.

  • options — служит для передачи опций в библиотеку librdkafka.

  • is_async — определяет режим работы TDG в качестве Kafka-продюсера:

    • true — подтверждение о доставке сообщения отправляется только после того, как сообщение было действительно доставлено в Kafka.
    • false — обычный асинхронный режим, когда подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку.

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

Например:

connector:
  output:
     - name: to_kafka
       type: kafka
       brokers:
         - localhost:9092
       topic: objects
       options:
         debug: "all"
         queue.buffering.max.ms: 1
       is_async: true

type: smtp

  • url — URL сервера SMTP;
  • from — имя отправителя, которое будет показываться в поле «From» при получении сообщения;
  • subject — тема отправляемого сообщения;
  • timeout — тайм-аут запроса к серверу SMTP, секунды;
  • ssl_cert — путь к SSL-сертификату;
  • ssl_key — путь к приватному ключу для SSL-сертификата.

Например:

connector:
  output:
    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@localhost
      subject: TDG_Objects
      timeout: 5
      ssl_cert: ssl.crt
      ssl_key: ssl.pem

routing

Mаршрутизация объекта для отправки через определенный output, который определяется в зависимости от ключа маршрутизации key. Ключ маршрутизации объект получает в результате обработки в пайплайне, указанном в input. Если в input пайплайн не указан, объект обрабатывается пайплайном по умолчанию, которые превращает объект вида

{
  "obj_type": { "field_1": 1 }
}

в объект

{
  "field_1": 1
}

и задает значение ключа маршрутизации как routing_key = obj_type.

Пример конфигурации:

connector:
  routing:
    - key: input_processor
      output: to_input_processor

    - key: external_http_service
      output: to_external_http_service

    - key: external_soap_service
      output: to_external_soap_service

2.16.1.5. input_processor

Для кластерной роли input_processor настраиваются:

classifiers

Определение пользовательского пайплайна, выполняющего классификацию объектов. В результате классификации объекту присваивается нужный ключ маршрутизации, по которому определяются дальнейшие действия по его обработке. Если пайплайн не задан, объект никак не обрабатывается и направляется на обработку пайплайном, указанным в секции input_processor: routing.

routing

Маршрутизация объекта в определенный пайплайн обработки по ключу маршрутизации (параметр key).

storage

Настройки сохранения объекта в роли storage по ключу маршрутизации (параметр key). Параметр type определяет тип бизнес-объекта (агрегата).

Пример маршрута (порядка обработки) объекта

Рассмотрим порядок обработки объекта на примере конфигурации выше.

1. После попадания в систему на роль connector, объект будет обработан в соответствии с настройками конфигурации input в секции connector.

В нашем примере мы видим, что для всех возможных вариантов input (JSON via HHTP, XML via SOAP, Kafka) конвейер обработки указан один и тот же: pipeline: connect_input_handle.

2. В секции pipelines находим этот конвейер — он состоит из выполнения одной функции.

pipelines:
  connect_input_handle:
    - focus_routing

3. В секции functions мы видим, что исполняемый код этой функции находится в файле focus_routing.lua.

functions:
  ...
  focus_routing: {__file: focus_routing.lua}

Листинг кода:

local first = ...

local ret = {obj = first, priority = 1, routing_key = 'input_processor'}

return ret

Необработанный объект должен быть помещен в поле obj. Объекту будет присвоен ключ маршрутизации «input_processor».

4. Дальнейший маршрут объекта определяется настройками routing в секции connector. Для объектов с ключом маршрутизации «input_processor» это будет output: to_input_processor:

connector:

  routing:
    - key: input_processor
      output: to_input_processor
  1. В секции connector находим данный output:
connector:

  output:
    - name: to_input_processor
      type: input_processor

Значение параметра type означает, что объект будет направлен на экземпляр с ролью input_processor.

6. При попадании на роль input_processor объект прежде всего будет обрабатываться в соответствии с настройками из секции ниже:

input_processor:
  classifiers:
    - name: focus
      pipeline: focus_classifiers

В указанном здесь пайплайне будет выполняться следующий код из focus_classifier.lua:

local param = ...

local type_table =
    {
        ["Initiation"] =  "focus_initiation",
        ["Coupon Payment"] =  "focus_couponpayment",
        ["Exercise"] =  "focus_exercise",
        ["Rate Change"] =  "focus_ratechange"
    }

local node = lom.get_by_path(param.obj, 'message.header.routedata.event_type')

if node == nil then
    return param.obj
end

local event_type = string.strip(node[1])

param.routing_key = type_table[event_type]

return param

где lom.get_by_path — функция, которая берет значение из объекта по указанному пути. При этом путь записывается с разделением при помощи точки.

Допустим, что после обработки на данном этапе наш объект получит ключ маршрутизации «focus_couponpayment».

7. Дальнейшая обработка объекта с таким ключом маршрутизации будет определяться следующими настройками в секции input_processor:

input_processor:

  routing:
    - key: focus_couponpayment
      pipeline: coupon_payment_handle

  storage:
    - key: focus_couponpayment
      type: CouponPayment

Это означает, что сначала объект будет обработан в еще одном пайплайне — coupon_payment_handle, а потом направлен на роль storage как объект типа «CouponPayment». Данный тип должен быть описан в модели данных, которая определена в секции

types: {__file: model.avsc}

После успешной валидации по модели данных, объект будет сохранен на роли storage.

8. Если для данного ключа маршрутизации указаны еще какие-либо настройки в других секциях config.yml, объекты с этим ключом будут обработаны далее (см. пример про секцию output_processor).

2.16.1.6. output_processor

Задается логика обработки объектов, которые будут реплицироваться во внешние системы. Выполняется после успешного сохранения объектов на экземплярах с ролью storage.

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

  • pipeline — какой конвейер обработки будет применен к объекту.
  • output — с какими параметрами объект будет отправлен во внешнюю систему. Все доступные параметры можно посмотреть в секции output.
  • expiration_timeout — по истечении какого времени (в секундах) объект будет удален из очереди, если он не был обработан. Значения по умолчанию нет.
  • store_strategy — значения copy или reference определяют то, как хранятся объекты — кортеж или первичный ключ соответственно. При использовании копии (copy) сохраняется кортеж, и даже при его удалении из хранилища никакие данные не теряются. Хранение по первичному ключу (reference) тратит меньше ресурсов, но при этом менее надежно — если объект был вытеснен, то при отправке он будет пропущен.
  • is_async — асинхронный или синхронный режим работы. Значение по умолчанию — is_async: true. В синхронном режиме (is_async: false) доступны еще два дополнительных параметра:
    • sync_retry_timeout — параметр задает таймаут (в секундах), после которого повторяется отправка объекта, с доставкой которого возникла проблема (по умолчанию sync_retry_timeout: 60);
    • sync_failed_attempt_count_threshold — параметр задает количество повторных попыток доставки. Значения по умолчанию нет.

В рассматриваемом примере:

output_processor:
  focus_couponpayment:
    pipeline: notification_filter
    output: to_external_http_service

Данные настройки означают, что объекты, которые на более ранних этапах обработки получили ключ маршрутизации focus_couponpayment, будут вначале обработаны функциями из пайплайна notification_filter, а затем отосланы в соответствии с настройками указанного здесь output (смотрим эти настройки в секции connector):

connector:

    output:
    - name: to_external_http_service
      type: http
      url: http://localhost:8021/test_json_endpoint
      format: json
      headers:
        config_header: header_for_http

Аналогично определяется поведение роли output_processor в отношении объектов с другими ключами маршрутизации.

При работе с output_processor можно переключаться между асинхронным и синхронным режимами работы (параметр is_async). Значение параметра is_async: false переводит роль output_processor в синхронный режим.

В асинхронном режиме есть только одна очередь вывода, и в случае сбоя объект помещается в ремонтную очередь. В синхронном режиме для продолжения работы необходимо, чтобы все сообщения были доставлены. Если в параметрах для отправки исходящих запросов output хотя бы с одним из получателей возникла ошибка, то останавливается вся очередь вывода. Попытку доставки можно повторить по истечении заданного таймаута (параметр sync_retry_timeout), и только для тех output, на которых возникла проблема. Количество повторных попыток можно настроить с помощью параметра sync_failed_attempt_count_threshold.

Пример:

output_processor:
  Type1:                                          # ключ маршрутизации
    expiration_timeout: 1000                      # время, по истечении которого необработанный объект будет удален
    store_strategy: copy                          # объекты хранятся в виде кортежей
    is_async: false                               # выбор синхронного режима
    sync_retry_timeout: 5                         # параметр доступен, если is_async: false
    sync_failed_attempt_count_threshold: 1000     # параметр доступен, если is_async: false
    handlers:                                     # обработчики запросов
      - pipeline: output_processor
        outputs:                                  # список получателей, которым будет доставлен объект
          - http_output
          - http_output2
          - http_output3

2.16.1.7. repair_queue

repair_queue:
  on_object_added:
    __unclassified__:
        postprocess_with_routing_key: unclassified

В данном примере настроен случай, когда определенные объекты, попавшие в ремонтную очередь, также должны быть реплицированы во внешнюю систему. В данном случае ранее на этапе классификации объект не удалось классифицировать, и ему было присвоено специальное значение ключа «__unclassified__», которым определяются неклассифицированные объекты.

При попадании такого объекта в ремонтную очередь, согласно настройкам postprocess_with_routing_key: unclassified, объекту присваивается другой ключ маршрутизации «unclassified», и с этим ключом он направляется на роль output_processor. Дальнейшая обработка объекта будет выполняться в соответствии с настройками в секции output_processor:

output_processor:
  unclassified:
    pipeline: notification_filter
    output: to_external_http_service

2.16.1.8. logger

В этой секции определяются настройки для кластерной роли logger. Все параметры обязательные.

  • rotate_log — флаг (true/false), осуществлять ли ротацию лога. Значения по умолчанию нет.
  • max_msg_in_log — максимальное количество сообщений, сохраняемых в логе. Значения по умолчанию нет.
  • max_log_size — максимальный размер файла лога, в байтах. Значения по умолчанию нет.
  • delete_by_n_msg — количество одновременно удаляемых сообщений при ротации лога. При превышении значений параметров max_msg_in_log или max_msg_log_size наиболее старые n сообщений в логе удаляются за раз, что повышает производительность по сравнению с режимом, когда старые сообщения удаляются по одному. Значения по умолчанию нет.

2.16.1.9. audit_log

В секции задаются параметры для работы журнала аудита. Все параметры опциональные.

  • enabled — включена (true) или выключена (false) запись событий в журнал аудита. По умолчанию: true.

  • severity — уровень важности событий, которые будут записываться в журнал аудита. Возможные значения по возрастанию важности: VERBOSE, INFO, WARNING, ALARM. По умолчанию: INFO.

    При указании определенного уровня в журнал аудита будут записываться события этого уровня и выше. Например, если задано INFO, будут записываться события, соответствующие уровням INFO, WARNING и ALARM. Подробнее см. список событий, соответствующий каждому уровню.

  • remove_older_than_n_hours — максимальное время хранения записей в журнале аудита, часы. Записи старше указанного времени удаляются. Значения по умолчанию нет.

2.16.1.10. tasks

В этой секции настраивается конфигурация задач, выполняемых при помощи ролей scheduler и task_runner. Например:

tasks:
  task_1:
    kind: single_shot
    pipeline: single_task
    keep: 5
  task_2:
    kind: continuous
    pipeline: long_task
    pause_sec: 10
  task_3:
    kind: periodical
    pipeline: long_task
    schedule: "0 */5 * * * *"

Параметры конфигурации:

  • task_N — имя задачи;
  • kind — вид задачи: «single_shot», «continuous» или «periodical» (см. подробнее);
  • pipeline — пайплайн, определяющий, что именно делается в рамках задачи;
  • keep — количество завершенных экземпляров задачи, которые сохраняются в истории. По умолчанию: 10;
  • pause_sec — пауза в выполнении задачи вида «continuous», секунды;
  • schedule — расписание выполнения для задач вида «periodical». Задается в формате cron. Используется расширенный синтаксис, в котором минимальной величиной является секунда:
* * * * * *
| | | | | |
| | | | | ----- День недели (0-6) (Воскресенье = 0)
| | | | ------- Месяц (1-12)
| | | --------- День (1-31)
| | ----------- Час (0-23)
| ------------- Минута (0-59)
--------------- Секунда (0-59)

В примере выше значение параметра schedule: "0 */5 * * * *" означает, что задача будет запускаться периодически каждые 5 минут.

2.16.1.11. task_runner

running_count_threshold — порог количества выполняемых пайплайнов для задач (tasks) и отложенных работ (jobs). По умолчанию: 100.

Этот параметр не ограничивает количество запущенных пайплайнов: при превышении порога в журнале просто создается предупреждение «Too many running pipelines. Now running %d pipelines».

2.16.1.12. jobs

max_jobs_in_parallel — максимальное количество отложенных работ (jobs), которые могут выполняться одновременно. По умолчанию: 50.

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

2.16.1.13. account_manager

Настройки кластерной роли account_manager, которая обеспечивает работу ролевой модели доступа и связанных с ней функций безопасности (см. подробнее).

  • only_one_time_passwords — флаг (true/false). По умолчанию: false. Если указано значение true, будет запрещена возможность вручную задать пароль пользователя при его создании или импорте. TDG будет автоматически генерировать одноразовый пароль и высылать его на адрес электронной почты пользователя. Для отсылки пароля также необходимо иметь работающий сервер SMTP, описание его конфигурации в секции connector (output: type: smtp) и указание на этот output в секции account_manager:

    account_manager:
      only_one_time_passwords: true
      output:
        name: to_smtp
        options:
          subject: "Registration"
    

    Опционально можно указать заголовок письма, в котором высылается одноразовый пароль (options: subject:).

    Если указано значение only_one_time_passwords: false, то автоматическая генерация пароля и отсылка его пользователю также будет выполняться в случае, когда поле Password при создании пользователя оставлено пустым.

  • password_change_timeout_seconds — минимальное время, которое должно пройти до следующей смены пароля, секунды. Значения по умолчанию нет.

    Примечание

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

  • block_after_n_failed_attempts — количество неудачных попыток входа в систему, после которых пользователь будет заблокирован (статус пользователя станет «blocked»). Значения по умолчанию нет.

  • ban_inactive_more_seconds — максимальное время, в течение которого пользователь может быть неактивен в системе, секунды. По истечении этого времени пользователь будет заблокирован. Максимально возможное значение параметра — 45 дней. Если значение превышает 45 дней или параметр не задан, будет взято значение по умолчанию, равное 45 дням.

  • password_policy — настройки политики паролей. Эти настройки также можно задать через web-интерфейс.

    • min_length — минимальная допустимая длина пароля. По умолчанию: 8.
    • include — флаги (true/false), определяющие, какие категории символов должны обязательно входить в пароль:
      • lower — латинские буквы в нижнем регистре. По умолчанию: true.
      • upper — латинские буквы в верхнем регистре. По умолчанию: true.
      • digits — цифры от 0 до 9 включительно. По умолчанию: true.
      • symbols — дополнительные символы !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~. По умолчанию: false.

2.16.1.14. pepper

Строка символов, которая в целях усиления безопасности добавляется к паролю перед его хэшированием. Если данный параметр не указан в конфигурации, добавляется строка по умолчанию, определенная в коде системы.

2.16.1.15. auth_external

В настройке задается Lua-код или путь к файлу с Lua-кодом, в котором пользователь имеет возможность самостоятельно задать логику для авторизации входящих запросов. Код должен вернуть таблицу с параметром auth, в котором лежит функция для проверки входящих запросов в формате HTTP. Функция возвращает либо nil, если доступ запрещен, либо в противном случае — объект, содержащий аутентификационную информацию.

Примечание

В версии Tarantool Data Grid, сертифицированной по требованиям доверия ФСТЭК России, использование параметра auth_external запрещено.

2.16.1.16. notifier

Настройки кластерной роли notifier.

  • mail_server — секция настроек сервера SMTP, который используется для отправки уведомлений при попадании объекта в ремонтную очередь. Данные параметры также можно задать через web-интерфейс.
    • url — URL сервера SMTP;
    • from — имя отправителя, которое будет показываться в поле «From» при получении уведомления;
    • username — имя пользователя сервера SMTP;
    • password — пароль пользователя сервера SMTP;
    • timeout — тайм-аут запроса к серверу SMTP, секунды.
    • skip_verify_host — флаг (true/false): пропустить проверку хоста по протоколу TLS.
  • users — секция, где задаются данные подписчиков (subscribers), которые будут получать уведомления. Подписчиков также можно создать через web-интерфейс.
    • id — идентификатор подписчика;
    • name — имя подписчика;
    • addr — e-mail подписчика.

2.16.1.17. ldap

В этой секции настраивается авторизация внешних пользователей и систем через LDAP.

ldap:
  - domain: 'glauth.com'
    organizational_units: ['superheros']
    hosts:
      - localhost:3893
    use_active_directory: true
    use_tls: false
    search_timeout: 2
    roles:
      - role: 'admin'
        domain_groups:
          - 'cn=superheros,ou=groups,dc=glauth,dc=com'
          - 'cn=users,ou=groups,dc=glauth,dc=com'
  • domain — доменное имя, которое используется в доменном логине пользователя (user@domain);

  • organizational_units — названия организационных подразделений или групп пользователей;

  • hosts — адрес для подключения к LDAP-серверу;

  • use_active_directory — параметр, определяющий, используется ли Active Directory (служба каталогов Microsoft). Если установлено значение true, используйте email для входа в систему и атрибут Active Directory userprincipalname=email в качестве фильтра, где <email> — это имя для входа пользователя в формате email-адреса;

  • use_tls — параметр, определяющий, используется ли TLS. Значение по умолчанию: false;

  • search_timeout — таймаут ожидания ответа от LDAP-сервера. Значение по умолчанию: 2 секунды;

  • roles — описание ролей, которые будут назначаться пользователю в зависимости от LDAP-групп, в которых он состоит:

    • role — роль, назначенная пользователю или внешнему приложению для авторизованного доступа и действий в системе (читать подробнее про роли);
    • domain_groups — LDAP-группы, которые соответствуют указанной выше роли. cn — общее имя (common name), ou — организационное подразделение или группа пользователей (organization unit name), dc — компонент домена (domain component).

2.16.1.18. services

В этой секции настраивается конфигурация сервисов. Например:

services:
  get_price:
    type: query
    doc: "Get the item price by ID"
    function: get_price_by_id
    return_type: ItemPrice
    args:
      item_id: string

Параметры:

  • Имя сервиса. В примере выше — get_price. Имя сервиса должно начинаться с латинской буквы и может содержать латинские буквы, цифры и символ подчеркивания (_);
  • type — тип запроса GraphQL для вызова сервиса: query или mutation. Если тип — query, параметр можно не указывать.
  • doc — произвольное описание сервиса;
  • function — ссылка на функцию, которая выполняет данный сервис. Функция должна быть описанна в конфигурации в секции functions;
  • return_type — тип данных, который возвращается в результате выполнения сервиса;
  • args — описание аргументов, передаваемых на вход при выполнении сервиса, в формате «имя_аргумента: тип_данных».

2.16.1.19. expiration

В секции задаются следующие параметры:

  • type — тип объекта, в отношении которого задаются ограничения;
  • lifetime_hours — время жизни объекта в часах. Объекты старше этой величины будут считаться устаревшими и подлежащими удалению. Значение по умолчанию: 24;
  • delay_sec — интервал в секундах, через который запускается очередная проверка устаревших объектов и их удаление. Значение по умолчанию: 36000;
  • keep_version_count — ограничение количества версий для объектов данного типа. По умолчанию: не ограничено.

Данные настройки также можно задать через web-интерфейс.

2.16.1.20. archivation

Определенные типы объектов могут поступать в систему в большом количестве, но при этом иметь короткое время активного использования, после чего потребность в обращении к ним возникает редко. Для этого случая реализован механизм архивации, когда такие объекты выгружаются из TDG и сохраняются отдельно на жестком диске.

Объекты сохраняются в текстовом виде в файлах формата .jsonl (формат имени — YYYY-MM-DDTHH:MM:SS.jsonl). Объекты записываются в файл построчно: один объект — одна строка вида {"TypeName": {... data ...}}, где TypeName — тип сохраняемого объекта.

Настройки архивации в конфигурации TDG:

  • type — тип объекта;
  • lifetime_days– время жизни объекта в TDG, дни. Объекты старше этой величины архивируется;
  • schedule — расписание запуска задачи на архивацию в формате cron;
  • dir — директория для хранения файлов с архивными данными;
  • file_size_threshold — максимальный размер файла с архивными данными, байты. По достижении этого размера запись архивируемых данных начинается в новый файл. По умолчанию: 104857600 (100 Мб).

2.16.1.21. hard_limits

Для контроля нагрузки на сервер задаются следующие ограничения на выполнение GraphQL-запросов:

  • scanned — запрос не должен проходить больше заданного количества кортежей в спейсах. По умолчанию: 2000.
  • returned — запрос не должен возвращать больше заданного количества кортежей. По умолчанию: 100.
При превышении одного из ограничений выполнение запроса прекращается и возвращается ошибка.

2.16.1.22. force_yield_limits

force_yield_limits — ограничение на количество сканирований записей в спейсе. При достижении порога выполняется yield. По умолчанию: 1000.

Актуально при выполнении map_reduce, чтобы избежать зависаний на экземплярах с ролью storage. Также учитывается при работе функций программного интерфейса репозитория.

2.16.1.23. graphql_query_chache_size

graphql_query_chache_size — размер кэша запросов GraphQL. Измеряется в количестве запросов, т.е. кэшируются N последних уникальных запросов в виде полного текста каждого запроса. По умолчанию: 3000.

2.16.1.24. vshard-timeout

vshard-timeout — время ожидания запроса, которое передается в функции vshard.callro()/callrw(), секунды. По умолчанию: 2.

2.16.1.25. maintenance

clock_delta_threshold_sec — порог рассинхронизации истинного времени (CLOCK_REALTIME) на серверах, секунды. По умолчанию: 5.

При превышении порога в логе создается запись об ошибке «Time deviation threshold exceeded! Max clock delta is %s». Проверка синхронизации важна для операций, использующих метки времени, таких как логирование и аудит.

2.16.1.26. gc

Роль garbage_collector принудительно запускает сборку мусора в Lua. Роль включается неявно на всех экземплярах.

Параметры:

  • forced — включение (true) или отключение (false) принудительной сборки мусора. По умолчанию: false;
  • period_sec — интервал, через который происходит запуск нового цикла сборки мусора, секунды;
  • steps — размер шага сборщика мусора.

2.16.1.27. tracing

Настройки коммуникации с трейсинг-системой (tracing system), куда передаются данные для анализа производительности выполнения кода.

  • base_url — эндпойнт программного интерфейса (API endpoint), куда отсылаются собранные для анализа спаны (spans);
  • api_method — тип HTTP-запроса для обращения к base_url. Для трейсинг-систем, поддерживающих протокол OpenZipkin, — POST;
  • report_interval — интервал, через который в трейсинг-систему отсылаются накопленные спаны, секунды;
  • spans_limit — размер буфера для накопления спанов перед отправкой в трейсинг-систему. Измеряется количеством спанов.

Например:

tracing:
  base_url: localhost:9411/api/v2/spans
  api_method: POST
  report_interval: 5
  spans_limit: 100

2.16.1.28. metrics

По умолчанию значения метрик в формате Prometheus доступны по адресу http://<IP_адрес_экземпляра>/metrics. Подробнее о сборе метрик можно почитать в главе «Метрики».

Также для мониторинга работы TDG можно настроить просмотр метрик по другим адресам ресурсов (endpoints) и в других форматах:

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/path_for_prometheus_metrics'
      format: 'prometheus'
    - path: '/health'
      format: 'health'
  • export — параметр, который определяет, что в этой секции файла конфигурации мы делаем экспорт метрик в нужную нам базу данных временных рядов (time series database);
  • path — путь, по которому будут доступны метрики. Например:
    • </path_for_json_metrics> — путь, по которому будут доступны метрики в формате JSON;
    • </path_for_prometheus_metrics> — путь, по которому будут доступны метрики в формате Prometheus;
    • </health> — путь, по которому будет доступна информация о текущем состоянии экземпляра.
  • format — формат, в котором будут доступны метрики:
    • JSON;
    • Prometheus;
    • health — проверка текущего состояния экземпляра. Если состояние экземпляра удовлетворительное, возвращает 200, если нет — возвращает 500.

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

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/another_path_for_json_metrics'
      format: 'json'

Как только вы добавите секцию metrics в файл конфигурации, метрики по умолчанию в формате Prometheus по адресу http://<IP_адрес_экземпляра>/metrics перестанут быть доступными. Если вам нужно, чтобы метрики по-прежнему были доступны по этому адресу в том же формате, добавьте path: '/metrics' и format: 'prometheus' в секцию metrics.

2.16.1.29. sequence_generator

Настройки, используемые при генерации последовательностей уникальных чисел:

  • starts_with — число, с которого начинается последовательность. По умолчанию: 1.
  • range_width — диапазон последовательности. По умолчанию: 100.

См. подробнее про функцию работы с последовательностью.

2.16.1.30. test-soap-data

Параметр позволяет задать текст, который будет по умолчанию отображаться на закладке Test в web-интерфейсе. Может использоваться для удобства тестирования: в этой секции можно задать структуру тестового объекта в формате XML или JSON для имитации входящего запроса.

2.16.1.31. libraries

Настройка подключения пользовательских библиотек, которые могут использоваться в коде функций пайплайнов (см. секции functions и pipelines). Указывается имя библиотеки, которое будет использоваться в коде, и путь к файлу библиотеки, который загружается вместе с конфигурацией системы.

Пример конфигурации:

libraries:
  cache:
    __file: cached.lua
  utils:
    __file: utils.lua

Пример вызова:

Если в указанной в конфигурации библиотеке (например, utils.lua) определена функция

local function timediff(value)
    return (datetime.now() - value)
end

то в пользовательском коде функцию можно вызвать как utils.timediff(value).

2.16.1.32. welcome-message

Текст приветственного сообщения, которое будет появляться при входе в систему. Ограничения на количество символов в сообщении нет.

2.16.1.33. tdg-version

Проверка версии TDG на совместимость при применении конфигурации. Для параметра указывается условие проверки, и с ним сравнивается текущая версия TDG. Если условие не выполняется, применение конфигурации останавливается.

Пример:

tdg-version: "== 1.7.0" # [оператор][пробел][версия]

где:

  • оператор: ==, <=, <, >, >=;
  • версия: major.minor.patch (семантическое версионирование) или scm-<число>.

Важно

Чтобы избежать возможных ошибок при чтении, всегда заключайте выражение из оператора и версии в кавычки. Обязательного помещения в кавычки не требует только выражение с «==».

Синтаксис YAML позволяет указывать многостроковые значения с помощью операторов >, <, >=, >= в первой строке. Например, чтобы задать версию больше, чем некоторое значение, нужно поместить оператор > и версию в кавычки:

# ошибка, будет прочитано как "1.7.0"
# tdg-version: > 1.7.0

# правильно, будет прочитано как "больше чем 1.7.0"
tdg-version: "> 1.7.0"