Профили движков Kyuubi

Елизавета Вайсман

Обзор

Kyuubi выступает в роли унифицированного SQL-шлюза с поддержкой нескольких движков (engine): пользователи подключаются к одному эндпоинту (endpoint) Kyuubi, а администраторы могут направлять сессии к разным движкам (например, Spark3, Spark4, Flink, Trino или JDBC) с помощью профилей движков.

Обзор профиля движка

Профиль движка — это набор настроек, который может объявить администратор. Профиль позволяет объединить под одним именем такие настройки, как:

  • тип движка;

  • переменные окружения движка;

  • переменные сессии Kyuubi;

  • нативные (native) настройки движка.

Профили позволяют администраторам один раз определить настройки для конкретных движков в ADCM, вместо того чтобы требовать от пользователей передавать эти параметры в каждой строке подключения (например, версии Spark, пути SPARK_HOME или настройки подключения к базе данных). Пользователям достаточно указать имя профиля, а Kyuubi автоматически преобразует параметры найденного профиля в runtime-настройки для конкретного движка.

Профили движков обратно совместимы с уже установленными кластерами ADH. Если профили не объявлены или не применены, сессии Kyuubi работают точно так же, как и раньше, без изменений в механизмах запуска или обнаружения движков.

ПРИМЕЧАНИЕ

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

В примере ниже объявляется профиль с именем spark4-prod. Он указывает сервису Kyuubi:

  • выделить движок Spark SQL;

  • использовать определенные переменные окружения для Spark;

  • применить настройку уровня сессии;

  • передать движку Spark нативные настройки.

kyuubi.engine.profile.spark4-prod.type=SPARK_SQL
kyuubi.engine.profile.spark4-prod.env.SPARK_HOME=/usr/lib/spark4
kyuubi.engine.profile.spark4-prod.env.SPARK_CONF_DIR=/etc/spark4/conf
kyuubi.engine.profile.spark4-prod.session.engine.share.level=USER
kyuubi.engine.profile.spark4-prod.conf.spark.executor.memory=4g
kyuubi.engine.profile.spark4-prod.conf.spark.executor.cores=2

В примере ниже показан пользовательский запрос на выделение движка с профилем spark4-prod:

jdbc:hive2://kyuubi:10009/default?kyuubi.engine.profile=spark4-prod

Обзор черных списков профилей

Администраторы могут ограничивать доступ к определенным профилям для отдельных пользователей или групп пользователей. Если профиль внесен в черный список (blacklist) для пользователя или одной из групп пользователя, Kyuubi запрещает этому пользователю запускать сессии с таким профилем.

Больше информации можно узнать в разделе Ограничение использования профилей.

Настройка свойств профилей в ADCM

Чтобы добавить или изменить свойства профилей в ADCM, выполните следующие шаги:

  1. Откройте конфигурацию сервиса Kyuubi, как описано в статье Настройка сервисов.

  2. Перейдите на вкладку Components и нажмите на компонент Kyuubi Server.

  3. В открывшейся вкладке Configuration выберите раздел конфигурации Engine profiles.

  4. Добавьте свойства, связанные с профилями, с помощью поля Add property.

  5. Сохраните конфигурацию.

  6. Перезапустите Kyuubi или Kyuubi Server с помощью действия Restart.

В разделе конфигурации Engine profiles можно настроить следующие свойства, связанные с профилями:

ПРИМЕЧАНИЕ

Когда в кластер ADH добавляются сервисы Spark3, Spark4, Flink или Trino, ADCM автоматически создает соответствующие локальные профили движков для Kyuubi. Подробнее см. в Обзор Kyuubi UI. Профили движков Kubernetes автоматически не создаются, их необходимо настроить вручную в ADCM.

Объявление профилей движков

В этом разделе объясняется, как устроены свойства профилей, которые вы добавляете в ADCM в разделе конфигурации Engine profiles.

Свойства профилей — пары ключ/значение в формате <key>:<value>. Все ключи объявления профиля начинаются с общего префикса:

kyuubi.engine.profile.<name>.<bucket>

где:

  • <name> — идентификатор профиля. Он не должен конфликтовать с названиями бакетов (bucket), перечисленными в таблице ниже;

  • <bucket> — ключевое слово, которое определяет, как Kyuubi интерпретирует, маршрутизирует и применяет настройку. Поддерживаемые бакеты: type, env, session и conf. Полный формат ключа зависит от выбранного бакета и описан в таблице ниже.

Бакет Полный синтаксис ключа Описание и пример

type

kyuubi.engine.profile.<name>.type

Тип движка. Для профиля с именем <name>, например spark4-prod, указывает тип движка, который нужно выделить. При запуске Kyuubi проверяет это значение. Пример:

kyuubi.engine.profile.spark4-prod.type=SPARK_SQL

env

kyuubi.engine.profile.<name>.env.<VAR>

Переменная окружения движка. Для профиля с именем <name> экспортирует переменную окружения <VAR> непосредственно в процесс движка. Пример:

kyuubi.engine.profile.spark4-prod.env.SPARK_HOME=/usr/lib/spark4

session

kyuubi.engine.profile.<name>.session.<rest>

Настройка сессии Kyuubi. Для профиля с именем <name> задает переменной уровня сессии <rest> определенное значение. Пример:

kyuubi.engine.profile.spark4-prod.session.engine.share.level=USER

conf

kyuubi.engine.profile.<name>.conf.<rest>

Нативная настройка движка. Для профиля с именем <name> передает нативную настройку движка <rest> непосредственно в движок. Пример:

kyuubi.engine.profile.spark4-prod.conf.spark.executor.memory=4g

Ключи вида kyuubi.engine.profile.<name>.* описывают профиль только на стороне Kyuubi Server. Поэтому сами эти ключи не передаются в подпроцессы движков. Вместо этого Kyuubi разбирает объявление профиля, выбирает из него значения бакетов env, session и conf, а затем преобразует их в runtime-настройки, которые уже применяются при запуске движка.

Например, профиль JDBC может содержать настройки подключения, включая пароль:

kyuubi.engine.profile.pg.type=JDBC
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.type=postgresql
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.driver.class=org.postgresql.Driver
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.url=jdbc:postgresql://postgres.example.com:5432/analytics
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.user=analytics_reader
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.password=<password>

В этом примере kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.password становится kyuubi.engine.jdbc.connection.password для движка. Движок по-прежнему получает пароль, но не получает полное серверное объявление профиля в виде исходных свойств kyuubi.engine.profile.pg.*.

Следующие примеры демонстрируют, как объявлять различные профили движков в ADCM.

Профили Spark

Пример профиля для локальной установки Spark3, который задает количество памяти по умолчанию:

kyuubi.engine.profile.spark3.type=SPARK_SQL
kyuubi.engine.profile.spark3.env.SPARK_HOME=/usr/lib/spark3
kyuubi.engine.profile.spark3.env.SPARK_CONF_DIR=/etc/spark3/conf
kyuubi.engine.profile.spark3.conf.spark.executor.memory=2g

Пример профиля для локальной установки Spark4, который задает количество памяти по умолчанию:

kyuubi.engine.profile.spark4.type=SPARK_SQL
kyuubi.engine.profile.spark4.env.SPARK_HOME=/usr/lib/spark4
kyuubi.engine.profile.spark4.env.SPARK_CONF_DIR=/etc/spark4/conf
kyuubi.engine.profile.spark4.conf.spark.executor.memory=2g

Следующий пример настраивает профиль для запуска движков Spark4 в Kubernetes:

kyuubi.engine.profile.spark4-k8s.type=SPARK_SQL
kyuubi.engine.profile.spark4-k8s.conf.spark.master=k8s://https://<k8s-apiserver-host>:<k8s-apiserver-port>
kyuubi.engine.profile.spark4-k8s.conf.spark.kubernetes.container.image=<spark4-image>
kyuubi.engine.profile.spark4-k8s.conf.spark.kubernetes.namespace=<namespace>
kyuubi.engine.profile.spark4-k8s.conf.spark.executor.instances=2
kyuubi.engine.profile.spark4-k8s.conf.spark.executor.memory=1g

Клиенты могут явно запросить этот профиль в строке подключения:

jdbc:hive2://kyuubi:10009/default?kyuubi.engine.profile=spark4-k8s

Профиль Trino

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

kyuubi.engine.profile.trino-prod.type=TRINO
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.url=http://trino-coordinator.example.com:8080
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.catalog=system
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.user=analytics_reader
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.password=<password>

Пример профиля для подключения к координатору Trino, развернутому в Kubernetes и доступному через внешний IP-адрес:

kyuubi.engine.profile.trino-k8s.type=TRINO
kyuubi.engine.profile.trino-k8s.conf.kyuubi.engine.trino.connection.url=jdbc:trino://<external-ip>:8080
kyuubi.engine.profile.trino-k8s.conf.kyuubi.engine.trino.connection.catalog=adh-iceberg

Пример профиля для запуска приложений движка Flink:

kyuubi.engine.profile.flink-test.type=FLINK_SQL
kyuubi.engine.profile.flink-test.conf.flink.execution.target=remote
kyuubi.engine.profile.flink-test.conf.flink.app.name=test_app
kyuubi.engine.profile.flink-test.conf.kyuubi.engine.flink.doAs.enabled=false

Назначение профилей по умолчанию

Вы можете назначать профили по умолчанию в ADCM:

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

  • глобально для каждого типа движка.

Профили по умолчанию для пользователей и групп

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

___<user_name>___.kyuubi.engine.profile=<profile_name>
___<group_name>___.kyuubi.engine.profile=<profile_name>

Пример:

___alice___.kyuubi.engine.profile=trino-prod
___analysts___.kyuubi.engine.profile=spark4-prod

Профили по умолчанию для типов движков

Вы можете задать профиль по умолчанию для типа движка (engine type). Kyuubi использует его, если в сессии не указан профиль и не найден подходящий профиль по умолчанию для пользователя или группы:

kyuubi.engine.<TYPE>.profile.default=<profile_name>

где <TYPE> — допустимый тип движка, например SPARK_SQL, TRINO, FLINK_SQL или JDBC.

Пример:

kyuubi.engine.SPARK_SQL.profile.default=spark3-prod

Ограничение использования профилей

Вы можете настроить черные списки (blacklist) в ADCM, чтобы запретить выбранные профили для отдельных пользователей или групп пользователей.

___<user_name>___.kyuubi.engine.profiles.blacklist=<profile1>,<profile2>
___<group_name>___.kyuubi.engine.profiles.blacklist=<profile1>,<profile2>

Черные списки работают по следующим правилам:

  • Ограничения для пользователя сессии и всех групп пользователя объединяются. Профиль запрещен, если он присутствует в любом подходящем черном списке.

  • Если пользователь явно запрашивает профиль из черного списка в строке подключения с помощью kyuubi.engine.profile=<profile_name>, Kyuubi отклоняет сессию.

  • Если профиль из черного списка выбран неявно — например, как профиль по умолчанию для пользователя, группы или типа движка — Kyuubi пропускает его. Затем Kyuubi продолжает поиск в следующем источнике с более низким приоритетом. Подробнее см. в разделе Порядок выбора профилей.

Пример:

___analysts___.kyuubi.engine.profiles.blacklist=spark4-prod,trino-k8s
___bob___.kyuubi.engine.profiles.blacklist=flink-test

Как выбираются профили

Порядок выбора профилей

Когда открывается новая сессия Kyuubi, Kyuubi Server выбирает для нее не более одного профиля. Kyuubi проверяет следующие источники в строгом порядке приоритета и останавливается на первом источнике, который возвращает имя профиля:

  1. Явный параметр сессии
    Клиент явно запрашивает профиль по имени, например, с помощью kyuubi.engine.profile=<name> в строке подключения JDBC. Если запрошенный профиль внесен в черный список для пользователя, сессия сразу завершается с ошибкой.

  2. Профиль по умолчанию для пользователя или группы
    Если профиль не запрошен явно, Kyuubi ищет профиль по умолчанию, подходящий для пользователя или его группы, с помощью свойства <principal>.kyuubi.engine.profile. Сначала проверяется пользователь сессии, затем группы пользователя. Если найденный профиль по умолчанию внесен в черный список для этого пользователя, Kyuubi пропускает его и переходит к следующему профилю по умолчанию с более низким приоритетом.

  3. Профиль по умолчанию для типа движка
    Если подходящие профили по умолчанию для пользователя или группы не найдены, Kyuubi ищет профиль по умолчанию для типа движка с помощью свойства kyuubi.engine.<TYPE>.profile.default, где <TYPE> — выбранный тип движка для сессии. Если этот профиль внесен в черный список для текущего пользователя, он игнорируется и профиль не применяется.

  4. Без профиля
    Если не удалось выбрать имя профиля из перечисленных выше источников, профиль не применяется. Сессия ведет себя так же, как в развертывании Kyuubi без профилей движков.

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

Итоговая конфигурация сессии

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

Когда Kyuubi формирует итоговую конфигурацию сессии, он применяет свойства от самого низкого к самому высокому приоритету:

  1. Базовая конфигурация сессии (значения по умолчанию для Kyuubi Server и значения конфигурации по умолчанию для пользователя или группы).

  2. Параметры, которые заданы в выбранном профиле.

  3. Параметры, которые явно запросил клиент.

Изоляция движков и субдомены

Движки, запущенные с разными профилями, изолированы друг от друга: они никогда не используют один и тот же экземпляр движка и не переиспользуют runtime-ресурсы, созданные для другого профиля. Это правило действует даже в случаях, когда сессии используют один и тот же тип общего доступа к движку (share level), например USER, GROUP или SERVER.

Например, две сессии, открытые одним пользователем с разными профилями, запускают отдельные процессы движков.

Без профилей субдомен обычно основан только на идентификаторе типа общего доступа, например имени пользователя или имени группы. Если профили применены, Kyuubi строит субдомен, соединяя имя профиля и исходный субдомен символом подчеркивания: <profile>_<subdomain>. В таблице ниже приведен пример.

Тип общего доступа Субдомен без профиля Субдомен с профилем spark4

USER

alice

spark4_alice

GROUP

analytics

spark4_analytics

Если профиль не применяется, субдомен остается без изменений.

ВАЖНО

Если профиль применен, то клиентские приложения, команды CLI и запросы REST API, которые используют субдомен движка, должны использовать формат <profile>_<subdomain>.

Например, для движков, запущенных с профилем spark4, административная операция, которая ранее была нацелена на субдомен alice, должна быть нацелена на субдомен spark4_alice.

Валидация и обработка ошибок

Fail-fast-валидация при запуске

Профили движков являются статическими конфигурациями, которые Kyuubi Server считывает только один раз во время запуска. Kyuubi валидирует их по принципу fail-fast: если какой-либо профиль некорректен, Kyuubi Server немедленно останавливается при запуске.

Объявление профиля считается невалидным в следующих случаях:

  • Не удается распознать тип движка, объявленный в бакете type. Поддерживаемые типы движков:

    • SPARK_SQL

    • FLINK_SQL

    • TRINO

    • JDBC

  • В объявлении профиля используется неизвестный бакет: любой, кроме type, env, session или conf.

  • Бакет объявлен в неправильном формате, например бакет type содержит подключ (subkey), или после бакета env не указано имя переменной окружения.

Стратегия для неизвестных профилей

Если алгоритм выбора профиля возвращает незадекларированное имя профиля, то Kyuubi обрабатывает такую ситуацию в соответствии со свойством kyuubi.engine.profiles.unknown.strategy:

  • FAIL (по умолчанию) — Kyuubi немедленно прерывает попытку подключения и возвращает клиенту сообщение об ошибке со списком всех доступных имен профилей.

  • LOG — на стороне Kyuubi Server записывается warning-сообщение, и инициализация сессии продолжается без применения профиля.

Просмотр профилей движков

В web-интерфейсе Kyuubi можно работать с профилями движков, а именно:

  • просматривать движки, сгруппированные по профилю движка;

  • видеть неактивные профили, у которых нет запущенных экземпляров движков;

  • обновлять список профилей;

  • завершать (kill) работающие движки, связанные с профилем.

Узнать больше можно в статье Обзор Kyuubi UI.

Та же информация о профилях доступна через эндпоинт (endpoint) REST API:

$ curl -X GET http://<kyuubi_host>:<kyuubi_port>/api/v1/admin/engine/profile
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней