Autorisations IAM Pub/Sub

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.

Vous pouvez vous inscrire sur la liste d’attente de la Private Preview ici.

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.

Permissions facultatives

Ajoutez pubsub.schemas.get à la liste --permissions si vous ingérez depuis des topics qui utilisent des schémas Avro ou Protobuf Pub/Sub natifs. Sinon, laissez-le de côté pour conserver un rôle minimal.

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.

Traitez cette clé comme un secret

Les clés de compte de service donnent accès à votre projet GCP. Conservez ce fichier en lieu sûr, ne l’ajoutez pas au contrôle de version et renouvelez la clé régulièrement. ClickPipes chiffre la clé au repos après son import.

​

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.