Агент Apache Pulsar

Агент Pulsar — провайдер авторизации брокеров: Pulsar спрашивает его, кто может производить, потреблять, запускать functions, sources и sinks и администрировать топики, пространства имён, тенанты и кластеры, и он отвечает по подписанным политикам сервиса данных pulsar. Дистрибутив поставляет его как JAR для Java 17 agents/pulsar/grantforge-agent-pulsar-<version>.jar со встроенными и перемещёнными зависимостями.

Интеграционные тесты Testcontainers в репозитории запускают JAR в брокерах Pulsar 3.0.17, 3.3.9, 4.0.14 и 4.2.5. Это не сертифицирует все остальные версии. Сервисный плагин описан в Apache Pulsar.

Как это работает

• Каждая проверка решается на каждом уровне имени топика. Как и в правах Pulsar, право на тенант или пространство имён распространяется на их содержимое, поэтому агент решает производство в persistent://sales/orders/payments на тенанте sales, пространстве имён orders и топике payments: запрет на любом из них отклоняет, разрешение на любом из них предоставляет.
• Потребление решается и по подписке. На каждом из этих уровней агент спрашивает также о топике с подпиской, поэтому политика может позволить роли потреблять только через некоторые подписки, например billing-*.
• Администраторы кластера — суперпользователи Pulsar. admin на кластере брокера делает роль одним из них, а Pulsar позволяет своим суперпользователям всё, поэтому нижележащие политики их не ограничивают. Операции брокера и кластера Pulsar требуют admin на кластере, который они называют.
• Политики могут действовать только для некоторых сетей. Каждая проверка несёт адрес клиента, и агент вычисляет условие Адреса клиентов с помощью диапазонов адресов Netty, которыми пользуется сетевой стек брокера.
• Выдача прав через Pulsar отклоняется. Собственные права Pulsar и роли администраторов его тенантов не используются, поэтому pulsar-admin namespaces grant-permission и подобные получают ответ HTTP 405 с указанием выдавать права в GrantForge.
• Отказы записываются в журнал с причиной. Текст отказа, который получает клиент, формулирует Pulsar; журнал брокера называет политику GrantForge, которая запретила, или сообщает, что ни одна не разрешает.
• Решения сохраняются, а обращения объединяются. Решения текущего снимка сохраняются, по умолчанию 100 000 на 10 секунд, а новый снимок начинает заново. Одинаковые разрешённые обращения в пределах окна, по умолчанию 10 секунд, передаются одним событием доступа с указанием их числа; отказы передаются по одному и сразу. Каждое событие называет топик, пространство имён, тенант или кластер и адрес клиента.
• Один агент обслуживает весь брокер. Брокер загружает провайдер авторизации для бинарного протокола, веб-сервиса и functions worker; они используют один агент, который останавливается вместе с брокером.

Развёртывание

1. Добавьте сервис данных pulsar и настройте его политики. Откройте Права доступа к данным → Агенты, выберите сервис и выпустите токен агента. Он показывается только один раз; сохраните его в файл, доступный для чтения только учётной записи Pulsar.

2. Скопируйте JAR в lib каждого брокера, например /pulsar/lib.

3. Добавьте параметры в broker.conf каждого брокера или в standalone.conf, заменив адрес, пути и имя экземпляра из примера:

   authorizationEnabled=true
   authorizationProvider=org.devlive.grantforge.pulsar.agent.GrantForgePulsarAuthorizer
   superUserRoles=broker
   grantforge.server.url=https://grantforge.example.com
   grantforge.token.file=/pulsar/conf/grantforge.token
   grantforge.instance=broker-1
   grantforge.cache.dir=/pulsar/data/grantforge-cache

   Аутентификация тоже должна быть включена, чтобы у клиентов были роли. superUserRoles и proxyRoles должны называть только собственную роль брокеров и роли прокси: агент их не проверяет, а Pulsar проверяет и исходного клиента прокси. Администраторам вместо этого дайте admin на кластере. Каталог кэша должен быть доступен для записи учётной записи Pulsar. В контейнере записывайте параметры grantforge.* в файл: оболочка некоторых образов Pulsar отбрасывает переменные окружения с точками в имени, например PULSAR_PREFIX_grantforge.token.file.

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

5. Сначала перенесите существующие права: собственные права Pulsar на пространства имён, топики и подписки, а также роли администраторов тенантов перестают действовать. Заранее создайте соответствующие политики.

Пользователи, группы и роли

Политики называют пользователем роль, которую аутентификация Pulsar даёт клиенту, например subject токена или common name сертификата. Собственных групп у Pulsar нет: группы — те, в которые роль помещает GrantForge, а роли — те, что GrantForge ей назначает.

Решения и ограничения

• Без пригодного снимка отклоняется всё, кроме запросов брокеров и прокси. Неиспользуемый сервис оставляет Pulsar без проверок, как при выключенном authorizationEnabled.
• Токен, привязанный к сервису, тип которого не pulsar, отклоняет всё.
• Перед многими проверками Pulsar спрашивает, является ли роль суперпользователем или администратором тенанта; передаются только ответы, пропускающие запрос, а собственная проверка запроса передаётся в любом случае. Запрос, который Pulsar решает только этим вопросом, как Pulsar 3.0 для тенантов и кластеров, при отказе записывается лишь на уровне debug.
• admin на кластере делает роль суперпользователем только брокеров этого кластера.
• Списки прав Pulsar, например pulsar-admin namespaces permissions, завершаются ошибкой: политики хранит GrantForge.
• Адреса клиентов — только адреса и диапазоны; имя хоста не соответствует ни одному клиенту.
• Решения сохраняются на grantforge.decision.cache.ttl.ms, поэтому политика начинает или перестаёт действовать с задержкой до этого времени.

Связанные руководства

• Apache Pulsar
• Сервисы данных, политики и агенты