Activar funciones de Cloud Storage con Eventarc

En este tutorial se muestra cómo desplegar una función basada en eventos en Cloud Run y cómo usar Eventarc para activar la función en respuesta a eventos de Cloud Storage mediante la CLI de Google Cloud.

Si especificas filtros para un activador de Eventarc, puedes configurar el enrutamiento de eventos, incluida la fuente y el destino de los eventos. En el ejemplo de este tutorial, una actualización de un segmento de Cloud Storage activa el evento y se envía una solicitud a tu función en forma de solicitud HTTP.

Definir roles obligatorios

Tú o tu administrador debéis conceder los siguientes roles de gestión de identidades y accesos a la cuenta de implementación, la identidad del activador y, opcionalmente, al agente de servicio de Pub/Sub y al agente de servicio de Cloud Storage.

Roles necesarios para la cuenta de implementación

  1. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

    Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, una entidad principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación). Para obtener más información, consulta la página Roles y permisos de tu destino de evento.

    Para obtener los permisos que necesitas para completar este tutorial, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

    Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

    También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

    Ten en cuenta que, de forma predeterminada, los permisos de Cloud Build incluyen permisos para subir y descargar artefactos de Artifact Registry.

Roles necesarios para la identidad del activador

  1. Anota la cuenta de servicio predeterminada de Compute Engine, ya que la asociarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio que utiliza Compute Engine y tiene el siguiente formato de correo electrónico: Google Cloud 

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sustituye PROJECT_NUMBER por el número de tu proyecto. Google Cloud Puedes encontrar el número de tu proyecto en la página Bienvenido de la consola Google Cloud o ejecutando el siguiente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    En los entornos de producción, te recomendamos que crees una cuenta de servicio y le asignes uno o varios roles de IAM que contengan los permisos mínimos necesarios y que sigas el principio de privilegio mínimo.

  2. De forma predeterminada, solo los propietarios y editores de proyectos, así como los administradores e invocadores de Cloud Run, pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso por servicio. Sin embargo, para hacer pruebas, otorga el rol Invocador de Cloud Run (run.invoker) en el proyecto Google Cloud a la cuenta de servicio de Compute Engine. Concede el rol en todos los servicios y trabajos de Cloud Run de un proyecto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Ten en cuenta que, si creas un activador para un servicio de Cloud Run autenticado sin conceder el rol Invocador de Cloud Run, el activador se creará correctamente y estará activo. Sin embargo, el activador no funcionará como se espera y aparecerá un mensaje similar al siguiente en los registros:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  3. Concede el rol Receptor de eventos de Eventarc (roles/eventarc.eventReceiver) en el proyecto a la cuenta de servicio predeterminada de Compute Engine para que el activador de Eventarc pueda recibir eventos de proveedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

Rol opcional del agente de servicio de Cloud Storage

  • Antes de crear un activador para eventos directos de Cloud Storage, concede el rol Publicador de Pub/Sub (roles/pubsub.publisher) al agente de servicio de Cloud Storage:

    SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

Rol opcional del agente de servicio de Pub/Sub

  • Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril del 2021 o antes para admitir solicitudes push de Pub/Sub autenticadas, asigna el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se asigna de forma predeterminada: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Crea un segmento de Cloud Storage

Crea un segmento de Cloud Storage que se usará como fuente de eventos:

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

Escribir una función basada en eventos

Para escribir una función basada en eventos, sigue estos pasos:

Node.js

  1. Crea un directorio llamado helloGCS y cambia a ese directorio:

       mkdir helloGCS
   cd helloGCS

  2. Crea un archivo package.json en el directorio helloGCS para especificar las dependencias de Node.js:

    {
  "name": "nodejs-docs-samples-functions-v2-storage",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

  3. Crea un archivo index.js en el directorio helloGCS con el siguiente ejemplo de Node.js:

    const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent('helloGCS', cloudEvent => {
  console.log(`Event ID: ${cloudEvent.id}`);
  console.log(`Event Type: ${cloudEvent.type}`);

  const file = cloudEvent.data;
  console.log(`Bucket: ${file.bucket}`);
  console.log(`File: ${file.name}`);
  console.log(`Metageneration: ${file.metageneration}`);
  console.log(`Created: ${file.timeCreated}`);
  console.log(`Updated: ${file.updated}`);
});

Python

  1. Crea un directorio llamado helloGCS y cambia a ese directorio:

       mkdir helloGCS
   cd helloGCS

  2. Crea un archivo requirements.txt en el directorio helloGCS para especificar las dependencias de Python:

    functions-framework==3.9.2
cloudevents==1.11.0

    De esta forma, se añaden los paquetes que necesita el ejemplo.

  3. Crea un archivo main.py en el directorio helloGCS con el siguiente ejemplo de Python:

    from cloudevents.http import CloudEvent

import functions_framework


# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event: CloudEvent) -> tuple:
    """This function is triggered by a change in a storage bucket.

    Args:
        cloud_event: The CloudEvent that triggered this function.
    Returns:
        The event ID, event type, bucket, name, metageneration, and timeCreated.
    """
    data = cloud_event.data

    event_id = cloud_event["id"]
    event_type = cloud_event["type"]

    bucket = data["bucket"]
    name = data["name"]
    metageneration = data["metageneration"]
    timeCreated = data["timeCreated"]
    updated = data["updated"]

    print(f"Event ID: {event_id}")
    print(f"Event type: {event_type}")
    print(f"Bucket: {bucket}")
    print(f"File: {name}")
    print(f"Metageneration: {metageneration}")
    print(f"Created: {timeCreated}")
    print(f"Updated: {updated}")

    return event_id, event_type, bucket, name, metageneration, timeCreated, updated

Desplegar una función basada en eventos

Despliega la función llamada helloworld-events ejecutando el siguiente comando en el directorio que contiene el código de ejemplo:

Node.js 

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

Sustituye BASE_IMAGE por el entorno de imagen base de tu función (por ejemplo, nodejs22). Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

Python 

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

Sustituye BASE_IMAGE por el entorno de imagen base de tu función (por ejemplo, python313). Para obtener más información sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Runtimes e imágenes base de los idiomas admitidos.

Cuando se complete la implementación, la CLI de Google Cloud mostrará una URL en la que se ejecuta tu servicio.

Crear un activador de Eventarc

El activador de Eventarc envía eventos del segmento de Cloud Storage a tu servicio de Cloud Run helloworld-events.

  1. Crea un activador que filtre eventos de Cloud Storage:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=helloworld-events  \
    --destination-run-region=${REGION} \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sustituye:

    • TRIGGER_NAME con el nombre del activador.
    • PROJECT_ID por el ID de tu proyecto. Google Cloud
    • PROJECT_NUMBER con el número de tu proyecto Google Cloud .

    Ten en cuenta que, cuando crees un activador de Eventarc por primera vez en un proyecto de Google Cloud , puede haber un retraso en el aprovisionamiento del agente de servicio de Eventarc. Este problema suele resolverse intentando crear el activador de nuevo. Para obtener más información, consulta Errores de permiso denegado.

  2. Confirma que el activador se ha creado correctamente. Ten en cuenta que, aunque el activador se crea inmediatamente, puede tardar hasta dos minutos en estar totalmente operativo.

    gcloud eventarc triggers list --location=${REGION}

    La salida debería ser similar a la siguiente:

    NAME: helloworld-events
TYPE: google.cloud.storage.object.v1.finalized
DESTINATION: Cloud Run service: helloworld-events
ACTIVE: Yes
LOCATION: us-central1

Generar y ver un evento

Sube un archivo de texto al segmento de Cloud Storage para generar un evento que se enrute a la función. La función de Cloud Run registra el evento en los registros del servicio.

  1. Sube un archivo de texto a Cloud Storage para generar un evento:

     echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt

    La subida genera un evento y la función de Cloud Run registra el mensaje del evento.

  2. Para ver la entrada del registro, sigue estos pasos:

    1. Filtra las entradas de registro y devuelve el resultado en formato JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json

    2. Busca una entrada de registro similar a la siguiente:

      [
  {
   ....
    "resource": {
      "labels": {
        ....
        "location": "us-central1",
        .....
        "service_name": "helloworld-events"
      },
    },
    "textPayload": "File: random.txt",
     .....
  }
]

      Puede que los registros tarden unos instantes en aparecer. Si no los ves inmediatamente, vuelve a comprobarlo al cabo de un minuto.

Cuando veas la entrada de registro, se confirmará que has desplegado correctamente una función basada en eventos que se ha activado cuando se ha subido un archivo de texto a Cloud Storage.