Autorisations IAM Pub/Sub | ClickHouse Docs

Cet article décrit les autorisations IAM GCP requises par ClickPipes pour s'authentifier auprès de Google Cloud Pub/Sub et consommer les données de vos topics, ainsi que la manière de configurer un compte de service conférant exactement ces autorisations.

Prérequis

Pour suivre ce guide, vous aurez besoin de :

D’un service ClickHouse Cloud actif
D’un projet GCP contenant le topic Pub/Sub depuis lequel vous souhaitez ingérer des données
Des autorisations IAM dans ce projet pour créer des comptes de service et attribuer des rôles

Modèle d’authentification

ClickPipes for Pub/Sub s’authentifie auprès de GCP à l’aide d’une clé JSON de compte de service. Lorsque vous créez un pipe, vous téléversez le fichier de clé ; ClickPipes le chiffre au repos et l’utilise à l’exécution pour :

répertorier et lire les topics de votre projet,
créer et supprimer l’abonnement géré que ClickPipes utilise pour consommer les messages,
consommer les messages de cet abonnement,
et, éventuellement, lire les schémas Pub/Sub natifs depuis le registre de schémas.

Il n’existe actuellement ni option Workload Identity ni option de collage intégré des identifiants : la clé JSON de compte de service est aujourd’hui la seule méthode d’authentification prise en charge.

Permissions requises

ClickPipes requiert les permissions IAM suivantes sur le projet GCP propriétaire du topic. Elles couvrent l'ensemble du cycle de vie du pipe : découverte (recensement des topics, validation, échantillonnage), gestion des abonnements, ingestion continue et nettoyage.

Accès aux topics (découverte et validation)

Permission	Objectif
`pubsub.topics.list`	Lister les topics disponibles dans le projet lors de la découverte
`pubsub.topics.get`	Valider l'existence du topic et récupérer les paramètres du schéma
`pubsub.topics.attachSubscription`	Requise sur le topic lors de la création d'un abonnement pour celui-ci

Cycle de vie de l’abonnement (découverte et ingestion)

Permission	Objectif
`pubsub.subscriptions.create`	Créer l’abonnement géré (`clickpipes-{pipeID}`) et les abonnements de découverte éphémères
`pubsub.subscriptions.get`	Vérifications d’état (toutes les 60 s), polling du follower, validation de l’abonnement
`pubsub.subscriptions.delete`	Nettoyer les abonnements de découverte éphémères et supprimer l’abonnement géré lors de la suppression du pipe
`pubsub.subscriptions.consume`	Opérations `Receive()`, `Ack()`, `Nack()` et seek par timestamp

Accès au schéma (optionnel — uniquement pour les topics Avro/Protobuf natifs)

Autorisation	Objectif
`pubsub.schemas.get`	Récupérer les définitions de schéma natives à partir du registre de schémas Pub/Sub

Rôles prédéfinis

Rôle	Suffisant ?	Remarques
`roles/pubsub.editor`	Oui	Couvre toutes les permissions requises. Option la plus permissive.
`roles/pubsub.subscriber`	Non	Il manque `topics.list`, `topics.attachSubscription`, `subscriptions.create`, `subscriptions.delete` et `schemas.get`.
`roles/pubsub.viewer`	Non	Lecture seule — aucune gestion des abonnements ni consommation des messages.
Rôle personnalisé (recommandé)	Oui	Utilisez les sept permissions de base ci-dessus (plus `schemas.get` en option) pour respecter le principe du moindre privilège.

Configuration

Créer un rôle personnalisé (recommandé)

Pour appliquer le principe du moindre privilège, créez un rôle personnalisé avec exactement les permissions dont ClickPipes a besoin.

Vous pouvez le faire avec la 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

Ou, dans la Console GCP, accédez à IAM & Admin → Roles → Create role et ajoutez les permissions listées dans Permissions requises.

Si vous préférez ne pas créer de rôle personnalisé, vous pouvez à la place attribuer roles/pubsub.editor.

Créer un compte de service

Créez un compte de service dédié pour le ClickPipe :

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

Attribuez le rôle au compte de service

Associez le rôle que vous avez créé (ou roles/pubsub.editor) au compte de service au niveau du projet :

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"

Créer et télécharger une clé d’un compte de service

Créez une clé JSON pour le compte de service et téléchargez-la sur votre machine :

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

Vous importerez ce fichier clickpipes-pubsub-key.json dans ClickPipes UI lors de la création du pipe.

Remarques

pubsub.topics.attachSubscription est requis sur la ressource topic, et non sur l’abonnement. Ce point est souvent oublié lorsque seules des permissions au niveau de l’abonnement sont accordées.
Si votre topic n'utilise pas de schéma Pub/Sub natif (Avro ou Protobuf), la permission pubsub.schemas.get n'est pas nécessaire.
Les abonnements gérés sont nommés clickpipes-{pipeID} avec un ack deadline de 60 s, une rétention des messages de 7 jours et l'ordonnancement des messages activé.
Les abonnements de découverte éphémères sont nommés clickpipes-discovery-{uuid} avec un ack deadline de 10 s, une rétention de 10 minutes et un TTL d'expiration automatique de 24 heures.
ClickPipes traite les erreurs PermissionDenied et Unauthenticated comme non réessayables — si une permission est manquante, le pipeline échoue immédiatement au lieu de réessayer indéfiniment.