Puedes inscribirte en la lista de espera de la vista previa privada aquí.
- Un servicio activo de ClickHouse Cloud
- Un proyecto de GCP que contenga el tema de Pub/Sub desde el que desea ingestar
- Permisos de IAM en ese proyecto para crear cuentas de servicio y asignar roles
ClickPipes para Pub/Sub se autentica con GCP mediante una clave JSON de cuenta de servicio. Cuando creas un pipe, subes el archivo de clave; ClickPipes lo cifra en reposo y lo usa en tiempo de ejecución para:
- listar y leer temas de tu proyecto,
- crear y eliminar la suscripción administrada que ClickPipes usa para consumir mensajes,
- consumir mensajes de esa suscripción, y
- (opcionalmente) leer esquemas nativos de Pub/Sub desde el registro de esquemas.
No hay opción de Workload Identity ni de pegar credenciales directamente: la clave JSON de cuenta de servicio es el único método de autenticación compatible actualmente.
ClickPipes requiere los siguientes permisos de IAM en el proyecto de GCP propietario del tema. Cubren todo el ciclo de vida del pipe: descubrimiento (listado de temas, validación y muestreo), gestión de suscripciones, ingestión continua y limpieza.
Acceso al tema (descubrimiento y validación)
| Permiso | Propósito |
|---|
pubsub.topics.list | Listar los temas disponibles en el proyecto durante el descubrimiento |
pubsub.topics.get | Validar la existencia del tema y recuperar la configuración del esquema |
pubsub.topics.attachSubscription | Obligatorio en el tema al crear una suscripción sobre él |
Ciclo de vida de la suscripción (descubrimiento e ingestión)
| Permiso | Propósito |
|---|
pubsub.subscriptions.create | Crear la suscripción administrada (clickpipes-{pipeID}) y las suscripciones efímeras de descubrimiento |
pubsub.subscriptions.get | Comprobaciones de estado (cada 60 s), sondeo del follower, validación de la suscripción |
pubsub.subscriptions.delete | Limpiar las suscripciones efímeras de descubrimiento y eliminar la suscripción administrada al eliminar el pipe |
pubsub.subscriptions.consume | Operaciones de Receive(), Ack(), Nack() y búsqueda por timestamp |
Acceso a esquemas (opcional — solo para temas nativos de Avro/Protobuf)
| Permiso | Propósito |
|---|
pubsub.schemas.get | Recuperar definiciones de esquemas nativos del registro de esquemas de Pub/Sub |
| Rol | ¿Suficiente? | Notas |
|---|
roles/pubsub.editor | Sí | Cubre todos los permisos necesarios. Es la opción más amplia. |
roles/pubsub.subscriber | No | Faltan topics.list, topics.attachSubscription, subscriptions.create, subscriptions.delete y schemas.get. |
roles/pubsub.viewer | No | Solo lectura: no permite gestionar suscripciones ni consumir datos. |
| Rol personalizado (recomendado) | Sí | Use los siete permisos principales anteriores (más schemas.get, opcional) para un acceso con privilegios mínimos. |
Crear un rol personalizado (recomendado)
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
Permisos opcionalesAñade pubsub.schemas.get a la lista de --permissions si ingestas datos desde temas que usan esquemas nativos de Pub/Sub Avro o Protobuf. De lo contrario, omítelo para mantener el rol con los permisos mínimos.
roles/pubsub.editor en su lugar.
Crear una cuenta de servicio
gcloud iam service-accounts create clickpipes-pubsub \
--project=YOUR_PROJECT_ID \
--display-name="ClickPipes Pub/Sub Ingestion"
Otorga el rol a la cuenta de servicio
roles/pubsub.editor) a la cuenta de servicio a nivel de proyecto:
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"
Crear y descargar una clave de cuenta de servicio
gcloud iam service-accounts keys create clickpipes-pubsub-key.json \
--iam-account=clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com
clickpipes-pubsub-key.json en la interfaz de usuario de ClickPipes al crear el pipe.
Trata la clave como un secretoLas claves de las cuentas de servicio otorgan acceso a tu proyecto de GCP. Guarda el archivo de forma segura, no lo añadas al control de versiones y rótalo periódicamente. ClickPipes cifra la clave en reposo tras subirla.
pubsub.topics.attachSubscription es obligatorio en el recurso de tema, no en la suscripción. Esto suele pasarse por alto cuando solo se otorgan permisos a nivel de suscripción.- Si tu tema no usa un esquema nativo de Pub/Sub (Avro o Protobuf), no se necesita el permiso
pubsub.schemas.get.
- Las suscripciones administradas se llaman
clickpipes-{pipeID} y tienen un ack deadline de 60 s, retención de mensajes de 7 días y el orden de los mensajes habilitado.
- Las suscripciones efímeras de descubrimiento se llaman
clickpipes-discovery-{uuid} y tienen un ack deadline de 10 s, retención de 10 minutos y un TTL de caducidad automática de 24 horas.
- ClickPipes trata los errores
PermissionDenied y Unauthenticated como no reintentables: si falta algún permiso, el pipe falla de inmediato en lugar de reintentarlo indefinidamente.
