Запуск пайплайна в Vanilla-операции

Это самый простой способ запустить Flow: отдельный долгоживущий деплой контроллеров и воркеров не нужен — они поднимаются внутри одной YTsaurus vanilla-операции. Чтобы включить такой запуск, достаточно дописать в pipeline.yson блок vanilla.

Что потребуется

До запуска создайте корневой узел пайплайна по настроенному path. Он нужен для сохранения манифеста. См. подготовку объектов пайплайна.

Конфигурационный файл:

  • pipeline.yson — runner config со спекой пайплайна. Чтобы пайплайн запустился в vanilla-операции, в нём должен быть блок vanilla с enable = %true (см. Как включить). Отдельный config.yson не нужен — node config внутри джоб строится автоматически.

И бинари — их роли зависят от языка:

  • pipeline — ваш бинарь пайплайна. Он же является flow_server (через TSimpleRunnerProgram) и работает контроллером, воркером и раннером.
  • pipeline — лёгкий Python-бинарь: лаунчер + компаньон.
  • flow_server — серверный бинарь Flow (yt/yt/flow/bin/flow_server), работающий контроллером и воркером; путь к нему передаётся раннеру через --flow-bin или переменную окружения YT_FLOW_BIN. Компаньон доставляется в джобу автоматически. Не задавайте entrypoint в параметрах ресурса компаньона: заданный executable, отличный от ./py_companion, раннер сохраняет как есть и считает, что компаньон уже есть в окружении джобы.
  • run.sh — скрипт запуска Java jar и компаньона; первым аргументом принимает полное имя главного класса.
  • flow_server — серверный бинарь Flow (yt/yt/flow/bin/flow_server), работающий контроллером и воркером; путь к нему передаётся раннеру через --flow-bin или переменную окружения YT_FLOW_BIN. Компаньон доставляется в джобу автоматически. Не задавайте classpath в параметрах ресурса компаньона: заданный classpath раннер сохраняет как есть и считает, что jar-файлы уже есть в окружении джобы.
  • run.sh — сгенерированный JVM-лаунчер Kotlin-программы; первым аргументом он принимает полное имя главного класса. Для модуля Word Count разверните его вместе с wordcount_kotlin_bin.jar и каталогом зависимостей wordcount_kotlin_bin/, сохранив их взаимное расположение. Модуль собирается для JDK 21 и также создаёт jdk.tar: макрос WITH_JDK() упаковывает архив, но не распаковывает и не развёртывает автоматически каталог jdk/. На хосте запуска предоставьте Java 21 через JAVA_HOME или начальную опцию run.sh -j <путь/к/java>; -j имеет приоритет. Запускайте скрипт из каталога с этими артефактами, потому что его пути отсчитываются от текущего каталога. Отдельный docker-пример с образом flow-java использует Java 17, поэтому этот образ не гарантирует запуск модуля для JDK 21. Kotlin-код использует тот же Java SDK, см. Быстрый старт (Kotlin).
  • flow_server — серверный бинарь Flow (yt/yt/flow/bin/flow_server), работающий контроллером и воркером; путь к нему передаётся раннеру через --flow-bin или переменную окружения YT_FLOW_BIN. Компаньон доставляется в джобу автоматически. Не задавайте classpath в параметрах ресурса компаньона, если раннер должен доставить jar-файлы. Заданный classpath сохраняется; если он задан у всех ресурсов Java-компаньона, раннер не доставляет jar-файлы, а в смешанной спеке по-прежнему доставляет их для ресурсов без classpath.
  • pipeline — Go-бинарь: лаунчер + компаньон.
  • flow_server — серверный бинарь Flow (yt/yt/flow/bin/flow_server), работающий контроллером и воркером; путь к нему передаётся раннеру через --flow-bin или переменную окружения YT_FLOW_BIN. Компаньон доставляется в джобу автоматически. Не задавайте entrypoint в параметрах ресурса компаньона: заданный executable, отличный от ./go_companion, раннер сохраняет как есть и считает, что компаньон уже есть в окружении джобы.

JVM-раннер дополняет параметры JDK и classpath только в этом включённом Vanilla-режиме. В docker-джобе путь к JDK выбирается в порядке: jdk_bin_path ресурса, YT_FLOW_JDK_BIN_PATH, путь к JVM лаунчера. Выбранный путь должен существовать в образе джобы и указывать на совместимую версию Java. В porto-джобе с JDK-слоем от лаунчера переменная YT_FLOW_JDK_BIN_PATH переопределяет путь из слоя, а отличающийся путь из ресурса игнорируется. Воркер с явно заданными слоями не получает JDK-слой лаунчера, поэтому ему нужен совместимый путь к JDK в ресурсе или переменной окружения. При прямом пользовательском деплое JDK, jar-файлы и параметры компаньона нужно предоставить самостоятельно.

Как включить

Добавьте в конфиг пайплайна блок vanilla:

"vanilla" = {
    "enable" = %true;
    "pool" = "<ваш-пул>";
    "worker" = {"count" = 5};
};

Обязательные параметры — pool и worker.count. Остальные поля имеют разумные значения по умолчанию: контроллер — одна джоба, каждая джоба (и контроллера, и воркера) получает cpu_limit = 6 и memory_limit = 18 GiB. Порты джобы при запуске без сетевого проекта по умолчанию запрашиваются у YTsaurus — фиксированные порты соседних джоб на хосте с общей сетью конфликтовали бы; в сетевом проекте у каждой джобы свой IP, и фиксированные порты rpc_port = 10080, monitoring_port = 10081, companion.port = 10082 и companion.monitoring_port = 10083 используются, если раннер не запрашивает порты для джобы. Подробнее — в Дополнительных параметрах.

При необходимости ресурсы переопределяются явно:

"vanilla" = {
    "enable" = %true;
    "pool" = "<ваш-пул>";
    "controller" = {"count" = 1; "cpu_limit" = 2; "memory_limit" = "8g"};
    "worker" = {"count" = 5; "cpu_limit" = 8; "memory_limit" = "32g"};
};

Полный список полей — в TVanillaConfig и TVanillaTaskConfig.

При запуске flow_server сам валидирует спеку, создаёт vanilla-операцию с двумя задачами (controller и worker), устанавливает спеку пайплайна и стартует его.

Доступ читателей к операции

Если вы задаёте явный ACL операции, до запуска убедитесь, что его субъекты существуют на кластере исполнения. Выбор политики и проверка прав читателя описаны в разделе Чтение логов и артефактов операции.

Дополнительные параметры

Реже используемые поля блока vanilla:

Параметр

Описание

runtime_proxy_role

RPC-роль прокси для runtime_cluster (роль кластера пайплайна на нём может не существовать). Учитывается, только когда runtime_cluster отличается от кластера пайплайна; на кластере пайплайна используется его proxy_role

cache_path

Файловый кеш YTsaurus, в который загружаются файлы джоб (общий для всех flow-операций кластера). Непустой, по умолчанию //tmp/yt_wrapper/file_storage/new_cache

И поля задач (controller/worker):

Параметр

Описание

layers

Cypress-пути porto-слоёв, монтируемых в корневую файловую систему задачи. Непустой список хотя бы у одной задачи включает porto-джобы для всей операции

system_layer_path

Базовый OS-слой задачи; переопределяет системный слой по умолчанию

set_container_cpu_limit

Запрашивает ограничение CPU контейнера значением cpu_limit, если среда исполнения поддерживает его. По умолчанию %false: раннер не задаёт это поле в спеке операции.

port_count

Сколько портов задача запрашивает у YTsaurus вместо фиксированных. Без сетевого проекта нативный C++- и JVM-запуск по умолчанию запрашивают 2 порта у контроллера и 4 у воркера; раннеры Python и Go устанавливают для воркера с незаданным значением 3. 0 оставляет фиксированные порты, если компаньонский раннер не увеличивает worker.port_count

На хосте с общей сетью фиксированные порты соседних джоб столкнулись бы — там порты нужно запросить у YTsaurus полем port_count задачи. Поэтому при нативном C++- или JVM-запуске без сетевого проекта поле по умолчанию равно 2 у контроллера и 4 у воркера; явное значение 0 возвращает фиксированные порты, если компаньонский раннер не увеличивает worker.port_count. Выданные порты приходят в переменных окружения YT_PORT_<i> и имеют приоритет над конфигом: YT_PORT_0 — rpc_port (и bus_server.port), YT_PORT_1 — monitoring_port, YT_PORT_2 — companion.port, YT_PORT_3 — companion.monitoring_port (необязательный). Контроллеру и воркеру без компаньона достаточно двух портов, воркеру с компаньоном нужны как минимум три; при меньшем значении часть конечных точек останется фиксированной или компаньон не запустится, а без четвёртого порта отключатся только его метрики и профилирование.

Python-раннер устанавливает worker.port_count = 3, если поле не задано, равно YSON-сущности # или содержит ненулевое целое значение меньше 3. Явный 0 он сохраняет, поэтому воркер использует фиксированные порты. Go-раннер заменяет отсутствующее или целое значение меньше 3 на 3, в том числе явный 0. Порты этих воркеров выделяются и при наличии сетевого проекта, кроме случая с явным нулём для Python; для контроллера действуют правила выше. Java- и Kotlin-раннер используют JVM-лаунчер и автоматически worker.port_count не увеличивают.

Обращения к YTsaurus через job proxy

Используйте job proxy для обращений Flow к кластеру, на котором запущена vanilla-операция. Настройка подходит для массового чтения статических таблиц, чтения очередей, загрузки и сохранения состояния, записи в динамические таблицы и коммитов транзакций.

Запросы обходят общий RPC proxy: вместо сетевого перехода к нему используется локальный Unix socket. Это снижает нагрузку на общие RPC proxy и может уменьшить задержки и повысить пропускную способность, если ограничение было на их стороне. У vanilla-джоб должен оставаться запас CPU и памяти: обработка RPC-запросов и буферы переносятся в job proxy каждой джобы. Если скорость ограничена серверами хранения или пользовательскими вычислениями, смена маршрута сама по себе это ограничение не снимает.

Добавьте в vanilla.worker настройку enable_rpc_proxy_in_job_proxy:

enable_rpc_proxy_in_job_proxy = %true;

Путь данных:

Flow → RPC-клиент → Unix socket → job proxy → native-клиент → серверы кластера

Job proxy — отдельный процесс на execution node YTsaurus, который запускает пользовательский процесс джобы, контролирует его ресурсы и передаёт статистику узлу. В vanilla-операции пользовательским процессом служит воркер Flow. Job proxy существует и без этой настройки; флаг включает RPC API в этом процессе и передаёт путь к локальному сокету в YT_JOB_PROXY_SOCKET_PATH.

Лаунчер Flow передаёт кластер выполнения в YT_FLOW_JOB_PROXY_CLUSTER. Все клиенты общего кеша Flow для этого кластера используют локальный сокет: чтение таблиц, состояние, запись и commit транзакций. Клиент аутентификатора также использует job proxy. Клиенты с одинаковыми настройками внутри одного кеша переиспользуют соединение, сохраняя свои параметры авторизации. Явно указанная роль прокси, например my-cluster/my-proxy-role, для кластера выполнения также заменяется локальным сокетом. Обращения к другим кластерам сохраняют обычный RPC proxy.

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

Разделение RPC по транспортным band'ам

При большом числе партиций служебные RPC могут конкурировать с потоками данных (например, ReadTable) за обработку и передачу данных через job proxy. Настройка enable_control_multiplexing_band направляет поддерживающие её методы, в том числе CommitTransaction, PingTransaction, AbortTransaction и DetachTransaction, в band control. ReadTable остаётся в default. Band'ы используют отдельные транспортные соединения и очереди, но CPU, память и пропускная способность хоста остаются общими.

Это настройки клиентской стороны Flow. Флаг enable_control_multiplexing_band задаётся для конкретной RPC connection и выбирает band для поддерживаемых методов; он действует как при обращении к job proxy, так и к обычному RPC proxy. Параметры tcp_dispatcher.multiplexing_bands задают параллелизм транспортных соединений для всего процесса Flow. Они не настраивают диспетчер в отдельном процессе job proxy.

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

Следующий фрагмент конфига включает job proxy для воркеров, выбор control для поддерживаемых RPC и задаёт параллелизм 4 в default и 1 в control для каждого транспортного канала. Эти значения — пример для настройки под нагрузку, а не новые значения по умолчанию.

{
    vanilla = {
        worker = {enable_rpc_proxy_in_job_proxy = %true;};
        node_config = {
            clients_cache = {
                default_connection = {
                    enable_control_multiplexing_band = %true;
                };
            };
        };
    };
    dynamic_spec = {
        singletons = {
            tcp_dispatcher = {
                multiplexing_bands = {
                    default = {
                        min_multiplexing_parallelism = 4;
                        max_multiplexing_parallelism = 4;
                    };
                    control = {
                        min_multiplexing_parallelism = 1;
                        max_multiplexing_parallelism = 1;
                    };
                };
            };
        };
    };
}

Описание параметров min_multiplexing_parallelism и max_multiplexing_parallelism приведено в справочнике транспортного band'а.

Если для кластера задан clients_cache.per_cluster_connection, настройку enable_control_multiplexing_band нужно задать в соответствующем соединении: оно не наследует default_connection.

Запуск пайплайна

В командах для Java com.example.pipeline.PipelineMain — имя класса-заглушка. В командах для Kotlin указано имя точки входа из примера Word Count. В разделах запуска и валидации замените соответствующее имя на полное имя класса своего пайплайна. JVM-команды запускайте из каталога с run.sh, программным jar-файлом и каталогом зависимостей.

./pipeline --config pipeline.yson
./pipeline --config pipeline.yson --flow-bin flow_server
./run.sh com.example.pipeline.PipelineMain --config pipeline.yson --flow-bin flow_server
./run.sh tech.ytsaurus.flow.examples.wordcount.WordCountApplication --config pipeline.yson --flow-bin flow_server
./pipeline --config pipeline.yson --flow-bin flow_server

После старта раннер по умолчанию (YT_FLOW_WAIT=1) ждёт, пока пайплайн не перейдёт в состояние completed, и всё это время печатает новые записи публичного лога контроллера — те, что появились с момента начала ожидания; более ранние не выводятся. Раннер можно прервать — на запущенную операцию это не повлияет. С YT_FLOW_WAIT=0 раннер завершается сразу после запуска.

Только валидация спеки

Чтобы локально проверить спеку, не отправляя её контроллеру, передайте флаг --validate-only раннеру C++ или JVM. Раннер проверит статическую и динамическую спеки и завершится без побочных эффектов. Если спека невалидна, он завершится с ошибкой; иначе — успешно. JVM-раннер передаёт флаг в flow_server, поэтому это работает и для Java, и для Kotlin. Раннеры Python и Go не передают флаг в flow_server; при их запуске пайплайн вместо проверки может запуститься или обновиться.

Для пайплайна на C++:

./pipeline --config pipeline.yson --validate-only

Для Java и Kotlin укажите реальное полное имя класса точки входа и путь к flow_server. В Java-команде ниже сохранено имя-заглушка из раздела запуска, а в Kotlin-команде — имя класса из примера Word Count:

./run.sh com.example.pipeline.PipelineMain --config pipeline.yson --flow-bin flow_server --validate-only
./run.sh tech.ytsaurus.flow.examples.wordcount.WordCountApplication --config pipeline.yson --flow-bin flow_server --validate-only

См. также