Permisos de IAM de Pub/Sub

Este artículo describe los permisos de IAM de GCP que ClickPipes necesita para autenticarse con Google Cloud Pub/Sub y consumir datos de tus temas.

Puedes inscribirte en la lista de espera de la vista previa privada aquí.

Este artículo describe los permisos de IAM de GCP que ClickPipes necesita para autenticarse con Google Cloud Pub/Sub y consumir datos de tus temas, y cómo configurar una cuenta de servicio que conceda exactamente esos permisos.

​

Requisitos previos

Para seguir esta guía, necesitará:

• 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

​

Modelo de autenticación

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.

​

Permisos necesarios

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

​

Roles predefinidos

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.

​

Configuración

​

Crear un rol personalizado (recomendado)

Para aplicar el principio de privilegio mínimo, cree un rol personalizado con exactamente los permisos que necesita ClickPipes.

Puede hacerlo con la CLI de 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

O bien, en la Consola de GCP, ve a IAM & Admin → Roles → Crear rol y agrega los permisos que se indican en Permisos necesarios.

Permisos opcionales

Añ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.

Si prefieres omitir el rol personalizado, puedes otorgar roles/pubsub.editor en su lugar.

​

Crear una cuenta de servicio

Cree una cuenta de servicio específica para el ClickPipe:

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

Asigna el rol que creaste (o 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

Cree una clave JSON para la cuenta de servicio y descárguela localmente:

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

Sube este archivo clickpipes-pubsub-key.json en la interfaz de usuario de ClickPipes al crear el pipe.

Trata la clave como un secreto

Las 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.

​

Notas

• 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.