Разрешения IAM для Pub/Sub

Примечание

Вы можете записаться в лист ожидания закрытой предварительной версии здесь.

В этой статье описаны разрешения GCP IAM, необходимые ClickPipes для аутентификации в Google Cloud Pub/Sub и чтения данных из ваших топиков, а также порядок настройки сервисного аккаунта с предоставлением именно этих разрешений.

Предварительные требования

Чтобы выполнить это руководство, вам потребуется:

• Активный сервис ClickHouse Cloud
• Проект GCP, содержащий топик Pub/Sub, из которого вы хотите принимать данные
• Разрешения IAM в этом проекте для создания сервисных аккаунтов и назначения ролей

Модель аутентификации

ClickPipes for Pub/Sub аутентифицируется в GCP с помощью JSON-ключа сервисного аккаунта. При создании пайпа вы загружаете файл ключа; ClickPipes шифрует его при хранении и использует во время выполнения для следующих задач:

• перечисление и чтение топиков в вашем проекте;
• создание и удаление управляемой подписки, которую ClickPipes использует для получения сообщений;
• получение сообщений из этой подписки;
• (необязательно) чтение нативных схем Pub/Sub из реестра схем.

Поддержка workload identity и возможность вставить учётные данные напрямую отсутствуют — на данный момент JSON-ключ сервисного аккаунта остаётся единственным поддерживаемым методом аутентификации.

Требуемые разрешения

ClickPipes требуются следующие разрешения IAM в проекте GCP, которому принадлежит топик. Они охватывают полный жизненный цикл пайпа: обнаружение (получение списка топиков, проверка, отбор образцов), управление подписками, ингестию в штатном режиме и очистку.

Доступ к топикам (обнаружение и проверка)

Permission	Purpose
pubsub.topics.list	Просмотр списка доступных топиков в проекте в ходе обнаружения
pubsub.topics.get	Проверка существования топика и получение настроек схемы
pubsub.topics.attachSubscription	Требуется для топика при создании для него подписки

Жизненный цикл подписки (обнаружение и ингестия)

Permission	Purpose
pubsub.subscriptions.create	Создание управляемой подписки (clickpipes-{pipeID}) и эфемерных подписок для обнаружения
pubsub.subscriptions.get	Проверки состояния (каждые 60 с), опрос follower, проверка подписки
pubsub.subscriptions.delete	Удаление эфемерных подписок для обнаружения и управляемой подписки при удалении пайпа
pubsub.subscriptions.consume	Операции Receive(), Ack(), Nack() и seek-to-timestamp

Доступ к схемам (необязательно — только для нативных топиков Avro/Protobuf)

Разрешение	Назначение
pubsub.schemas.get	Получение определений нативных схем из реестра схем Pub/Sub

Предопределённые роли

Роль	Достаточно?	Примечания
roles/pubsub.editor	Да	Включает все необходимые разрешения. Наиболее широкий вариант.
roles/pubsub.subscriber	Нет	Отсутствуют topics.list, topics.attachSubscription, subscriptions.create, subscriptions.delete и schemas.get.
roles/pubsub.viewer	Нет	Только для чтения — без управления подписками и получения сообщений.
Пользовательская роль (рекомендуется)	Да	Используйте семь основных разрешений, перечисленных выше (плюс необязательное schemas.get), чтобы предоставить минимально необходимые привилегии.

Настройка

Создайте пользовательскую роль (рекомендуется)

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

Это можно сделать с помощью CLI gcloud:

gcloud iam roles create clickpipes.pubsub.ingestion \
  --project=YOUR_PROJECT_ID \
  --title="ClickPipes Pub/Sub Ingestion" \
  --description="Permissions required by ClickHouse ClickPipes to ingest from Pub/Sub" \
  --permissions=pubsub.topics.list,pubsub.topics.get,pubsub.topics.attachSubscription,pubsub.subscriptions.create,pubsub.subscriptions.get,pubsub.subscriptions.delete,pubsub.subscriptions.consume \
  --stage=GA

Или в консоли GCP перейдите в IAM & Admin → Roles → Create role и добавьте разрешения, перечисленные в разделе Обязательные разрешения.

Необязательные разрешения

Добавьте pubsub.schemas.get в список --permissions, если у вас настроен приём из топиков, использующих собственные схемы Pub/Sub Avro или Protobuf. В противном случае не добавляйте его, чтобы роль оставалась минимальной.

Если вы не хотите создавать пользовательскую роль, вместо неё можно выдать roles/pubsub.editor.

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

Создайте отдельный сервисный аккаунт для ClickPipe:

gcloud iam service-accounts create clickpipes-pubsub \
  --project=YOUR_PROJECT_ID \
  --display-name="ClickPipes Pub/Sub Ingestion"

Назначьте роль сервисному аккаунту

Назначьте роль, которую вы создали (или roles/pubsub.editor), сервисному аккаунту на уровне проекта:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="projects/YOUR_PROJECT_ID/roles/clickpipes.pubsub.ingestion"

Создайте и скачайте ключ сервисного аккаунта

Создайте JSON-ключ для сервисного аккаунта и скачайте его локально:

gcloud iam service-accounts keys create clickpipes-pubsub-key.json \
  --iam-account=clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com

Загрузите файл clickpipes-pubsub-key.json в интерфейсе ClickPipes при создании пайпа.

Обращайтесь с ключом как с секретом

Ключи сервисного аккаунта предоставляют доступ к вашему проекту GCP. Храните этот файл в безопасном месте, не добавляйте его в систему контроля версий и регулярно обновляйте его. После загрузки ClickPipes шифрует ключ при хранении.

Примечания

• pubsub.topics.attachSubscription требуется для ресурса топика, а не подписки. Этот момент часто упускают, когда выдают права только на уровне подписки.
• Если ваш топик не использует нативную схему Pub/Sub (Avro или Protobuf), разрешение pubsub.schemas.get не требуется.
• Управляемые подписки именуются как clickpipes-{pipeID} и имеют тайм-аут подтверждения 60 с, срок хранения сообщений 7 дней и включенное упорядочивание сообщений.
• Эфемерные подписки для обнаружения именуются как clickpipes-discovery-{uuid} и имеют тайм-аут подтверждения 10 с, срок хранения 10 минут и TTL автоматического истечения 24 часа.
• ClickPipes рассматривает ошибки PermissionDenied и Unauthenticated как не подлежащие повторной попытке — если какого-либо разрешения не хватает, пайп сразу завершается вместо того, чтобы бесконечно повторять попытки.