Usa Eventarc para recibir eventos de Cloud Storage


En este instructivo, se muestra cómo implementar una aplicación alojada en contenedores a través de un servicio autenticado de Cloud Run que recibe eventos a través de Eventarc.

Si especificas filtros para un activador de Eventarc, puedes configurar el enrutamiento de los eventos, incluidos la fuente y el destino del evento. En este caso, una actualización de un bucket de Cloud Storage activa el evento y se envía una solicitud a tu servicio de Cloud Run en el formato de una solicitud HTTP.

Objetivos

En este instructivo, podrás:

  1. Crear un bucket de Cloud Storage para que sea la fuente del evento.

  2. Implementar en Cloud Run un servicio de receptor de eventos que requiera invocaciones autenticadas.

  3. Crear un activador de Eventarc que enrute los eventos del bucket de Cloud Storage al servicio de Cloud Run.

  4. Generar un evento a través de la carga de un archivo al bucket de Cloud Storage y visualizarlo en los registros de Cloud Run.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de empezar

Es posible que las restricciones de seguridad que define tu organización no te permitan completar los siguientes pasos. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno de Google Cloud restringido.

  1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  2. Instala Google Cloud CLI.
  3. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init
  4. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  5. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  6. Instala Google Cloud CLI.
  7. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init
  8. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  9. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  10. Si no usas Cloud Shell, actualiza los componentes de Google Cloud CLI y accede con tu cuenta:
    gcloud components update
    gcloud auth login
  11. Habilita las APIs:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com
  12. Establece las variables de configuración que se usan en este instructivo:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  13. Si eres el creador del proyecto, se te otorga el rol de propietario básico (roles/owner). De forma predeterminada, este rol de Identity and Access Management (IAM) incluye los permisos necesarios para obtener acceso completo a la mayoría de los recursos de Google Cloud, pero puedes omitir este paso.

    Si no eres el creador del proyecto, se deben otorgar los permisos necesarios en el proyecto a la principal correspondiente. Por ejemplo, una principal puede ser una Cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de procesamiento). Para obtener más información, consulta la página Roles y permisos para el destino del evento.

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

    Permisos necesarios

    Si quieres obtener los permisos que necesitas para completar este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

    También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

  14. La cuenta de servicio predeterminada de Compute Engine se crea automáticamente después de habilitar o usar un servicio de Google Cloud que use Compute Engine.

    Si deseas realizar pruebas, puedes conectar esta cuenta de servicio a un activador de Eventarc para representar la identidad del activador. Ten en cuenta el formato de correo electrónico que se usará cuando se cree un activador:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com
    

    Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud. Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

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

    La cuenta de servicio de Compute Engine recibe automáticamente la función de editor básica (roles/editor) en tu proyecto. Sin embargo, si se inhabilitaron las asignaciones de funciones automáticas, consulta las instrucciones de Funciones y permisos aplicables para crear una cuenta de servicio nueva y otorgarle las funciones necesarias.

  15. De forma predeterminada, solo los propietarios y los editores del proyecto, y los administradores y los invocadores de Cloud Run pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso según el servicio. Sin embargo, para fines de prueba, otorga el rol de invocador de Cloud Run (run.invoker) en el proyecto de Google Cloud a la cuenta de servicio de Compute Engine. Esto otorga el rol en todos los servicios y trabajos de Cloud Run en 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 autenticado de Cloud Run sin otorgar la función de invocador de Cloud Run, el activador se crea de forma correcta y está activo. Sin embargo, el activador no funcionará como se espera y aparecerá en el registro un mensaje similar al siguiente:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  16. Otorga el rol de 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
  17. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril de 2021 o antes de esa fecha, para admitir las solicitudes de envío de Pub/Sub autenticadas, otorga la función Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) a la cuenta de servicio administrada por Google. De lo contrario, este rol se otorga 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 repositorio estándar de Artifact Registry

Crea un repositorio estándar de Artifact Registry para almacenar tu imagen de contenedor:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Reemplaza REPOSITORY por un nombre único para el repositorio.

Crea un bucket de Cloud Storage

Crea un bucket de Cloud Storage para usar como fuente del evento:

gsutil mb -l us-central1 gs://PROJECT_ID-bucket/

Después de crear la fuente del evento, puedes implementar el servicio del receptor de eventos en Cloud Run.

Implementa un receptor de eventos en Cloud Run

Implementa un servicio de Cloud Run que reciba y registre eventos.

  1. Clona el repositorio de GitHub:

    Node.js

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

    Python

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

    Go

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

    C#

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

    De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.

  2. Ve al directorio que contiene el código de muestra de Cloud Run:

    Node.js

    cd nodejs-docs-samples/eventarc/audit-storage/

    Python

    cd python-docs-samples/eventarc/audit-storage/

    Go

    cd golang-samples/eventarc/audit_storage/

    Java

    cd java-docs-samples/eventarc/audit-storage/

    C#

    cd dotnet-docs-samples/eventarc/audit-storage/
  3. Compila el contenedor para el servicio de Cloud Run:

    export PROJECT_ID=$(gcloud config get-value project)
    export SERVICE_NAME=helloworld-events
    gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  4. Implementa la imagen del contenedor en Cloud Run:

    gcloud run deploy ${SERVICE_NAME} \
        --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  5. En el mensaje ¿Permitir invocaciones no autenticadas en helloworld-events (y/N)?, responde n para “No”.

Cuando veas la URL del servicio de Cloud Run, la implementación estará completa.

Crea un activador de Eventarc

El activador de Eventarc envía eventos desde el bucket de Cloud Storage al servicio helloworld-events de Cloud Run. El servicio requiere autenticación, y un emisor que tenga una cuenta de servicio con los roles y permisos de IAM necesarios para usar el recurso debe activar el evento.

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

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

    Esto crea un activador llamado helloworld-events.

    Ten en cuenta que, cuando creas un activador de Eventarc por primera vez en un proyecto de Google Cloud, es posible que haya un retraso en el aprovisionamiento del agente de servicio de Eventarc. Por lo general, este problema se puede resolver si intentas crear el activador de nuevo. Para obtener más información, consulta Errores de permiso denegado.

  2. Confirma que el activador se haya creado de forma correcta. Ten en cuenta que, si bien tu activador se crea de inmediato, puede tardar hasta dos minutos para que un activador sea por completo funcional.

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

    El resultado debería ser similar al siguiente ejemplo:

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

Genera y visualiza un evento

Sube un archivo de texto al bucket de Cloud Storage para generar un evento que se enrute al servicio de Cloud Run. El servicio de Cloud Run registra el evento en los registros del servicio.

  1. Para generar un evento, haz lo siguiente:

    Sube un archivo de texto a Cloud Storage:

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

    La carga genera un evento y el servicio de Cloud Run registra el mensaje del evento.

  2. Sigue estos pasos para ver la entrada de registro:

    1. Filtra las entradas de registro y muestra 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 lo siguiente:

      "textPayload": "Detected change in Cloud Storage bucket: objects/random.txt"
      

Los registros pueden tardar un poco en aparecer. Si no los ves de inmediato, vuelve a revisar en un minuto.

Implementaste un servicio de receptor de eventos en Cloud Run de forma correcta, creaste un activador de Eventarc, generaste un evento desde Cloud Storage y lo viste en los registros de Cloud Run.

Realiza una limpieza

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y deseas conservarlo sin los cambios que se agregaron en este instructivo, borra los recursos creados para el instructivo.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, haz lo siguiente:

  1. En la consola de Google Cloud, ve a la página Administrar recursos.

    Ir a Administrar recursos

  2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Elimina recursos de instructivos

  1. Usa este comando para borrar el servicio de Cloud Run que implementaste en este instructivo:

    gcloud run services delete SERVICE_NAME

    En el ejemplo anterior, SERVICE_NAME es el nombre del servicio que elegiste.

    También puedes borrar los servicios de Cloud Run desde la consola de Google Cloud.

  2. Quita todas las opciones de configuración predeterminadas de gcloud CLI que agregaste durante la configuración del instructivo.

    Por ejemplo:

    gcloud config unset run/region

    o

    gcloud config unset project

  3. Borra otros recursos de Google Cloud que creaste en este instructivo:

    • Borrar el activador de Eventarc:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      Reemplaza TRIGGER_NAME por el nombre de tu activador.

¿Qué sigue?