Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

В этой статье описаны разрешения 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, которому принадлежит топик. Они охватывают весь жизненный цикл пайпа: обнаружение (получение списка топиков, проверка и сэмплирование), управление подписками, стабильную ингестию и очистку.

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

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

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

Разрешение Назначение
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 и добавьте разрешения, перечисленные в разделе Required permissions.

Если не хотите создавать пользовательскую роль, можно вместо этого назначить 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 при создании пайпа.

Примечания

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