Запуск пайплайна в 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:
|
Параметр |
Описание |
|
|
RPC-роль прокси для |
|
|
Файловый кеш YTsaurus, в который загружаются файлы джоб (общий для всех flow-операций кластера). Непустой, по умолчанию |
И поля задач (controller/worker):
|
Параметр |
Описание |
|
|
Cypress-пути porto-слоёв, монтируемых в корневую файловую систему задачи. Непустой список хотя бы у одной задачи включает porto-джобы для всей операции |
|
|
Базовый OS-слой задачи; переопределяет системный слой по умолчанию |
|
|
Запрашивает ограничение CPU контейнера значением |
|
|
Сколько портов задача запрашивает у YTsaurus вместо фиксированных. Без сетевого проекта нативный C++- и JVM-запуск по умолчанию запрашивают 2 порта у контроллера и 4 у воркера; раннеры Python и Go устанавливают для воркера с незаданным значением 3. |
На хосте с общей сетью фиксированные порты соседних джоб столкнулись бы — там порты нужно запросить у 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