Se usó la API de Cloud Translation para traducir esta página.

Comienza a usar funciones de Cloud Run basadas en eventos

1. Introducción

Descripción general

Las funciones de Cloud Run son una nueva forma de implementar cargas de trabajo con los paradigmas de eventos y la firma de funciones conocidos de GCF. En lugar de usar nuestro proceso de compilación y configuraciones de implementación definidos, las funciones de Cloud Run te brindan control directo sobre el servicio subyacente creado en Cloud Run.

Con Cloud Run Functions, proporcionamos la UX simple de la implementación de fuentes de Cloud Run, lo que les brinda a los desarrolladores un control total sobre sus cargas de trabajo con las configuraciones de Cloud Run.

En esta sección, aprenderás a implementar una función basada en eventos en Node. Implementarás una función que se activará cada vez que se finalice un objeto en un bucket de Google Cloud Storage.

En este codelab, se usan muestras de Node.js en los siguientes ejemplos. Sin embargo, puedes usar las muestras de código de Cloud Functions de 2ª gen. en el lenguaje que elijas:

Qué aprenderás

Cómo implementar una función de Cloud Run basada en eventos que se activa cada vez que se sube un objeto a un bucket de GCS
Cómo crear una cuenta de servicio con los roles adecuados para recibir un evento de Cloud Storage y, luego, invocar la función de Cloud Run

2. Configura variables de entorno y habilita las APIs

Actualiza la CLI de gcloud

Este codelab requiere que tengas instalada una versión reciente de la CLI de gcloud. Para actualizar la CLI, ejecuta

gcloud components update

Habilita las APIs

Antes de comenzar a usar este codelab, deberás habilitar varias APIs. Para este codelab, debes usar las siguientes APIs. Para habilitar esas APIs, ejecuta el siguiente comando:

gcloud services enable run.googleapis.com \
    cloudbuild.googleapis.com \
    storage.googleapis.com \
    artifactregistry.googleapis.com

Configura variables de entorno

Puedes configurar las variables de entorno que se usarán en este codelab.

PROJECT_ID=<YOUR_PROJECT_ID>
REGION=<YOUR_REGION, e.g. us-central1>

gcloud config set project $PROJECT_ID
SERVICE_NAME=crf-event-codelab
BUCKET_NAME=$PROJECT_ID-$SERVICE_NAME
TRIGGER_NAME=$SERVICE_NAME-trigger

3. Crea un bucket de almacenamiento y una cuenta de servicio

Crea un bucket de almacenamiento

Para crear un bucket de Cloud Storage, ejecuta el siguiente comando:

gsutil mb -l us-central1 gs://$BUCKET_NAME

Crea una cuenta de servicio

En este ejemplo, crearás una cuenta de servicio con los permisos de Eventarc necesarios y el rol de invocador de Cloud Run para recibir un evento de Cloud Storage y, luego, invocar la función de Cloud Run.

Primero, crea la cuenta de servicio.

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

SERVICE_ACCOUNT="cloud-run-functions"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="Cloud Run functions Eventarc service account"

A continuación, otorga el rol de receptor de eventos de Eventarc (roles/eventarc.eventReceiver) en el proyecto a la cuenta de servicio asociada con tu activador de Eventarc para que el activador pueda recibir eventos de los proveedores de eventos.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/eventarc.eventReceiver

Luego, otorga a la cuenta de servicio el rol de invocador de Cloud Run para que pueda invocar la función.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role=roles/run.invoker

4. Crea y, luego, implementa la función

Primero, crea un directorio para el código fuente y ábrelo con el comando cd.

mkdir ../$SERVICE_NAME && cd $_

Luego, crea un archivo package.json con el siguiente contenido:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

A continuación, crea un archivo index.js con el siguiente contenido:

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}`);
});

Ahora puedes implementar la función de Cloud Run ejecutando el siguiente comando:

gcloud beta run deploy $SERVICE_NAME \
 --source . \
      --function helloGCS \
      --region $REGION \
      --no-allow-unauthenticated

Ten en cuenta lo siguiente:

La marca –source se usa para indicarle a Cloud Run que compile la función en un servicio ejecutable basado en contenedores.
La marca –function (nueva) se usa para establecer el punto de entrada del servicio nuevo como la firma de la función que deseas invocar.
(opcional) El parámetro –no-allow-unauthenticated para evitar que tu función se pueda invocar de forma pública

Para ver tu nuevo servicio crf-nodejs-event, ejecuta el siguiente comando:

gcloud beta run services describe $SERVICE_NAME

5. Crea el evento

Podemos crear un activador de Eventarc para enviar mensajes a nuestra función cada vez que se finalice un objeto en Google Cloud Storage:

BUCKET_REGION=$REGION

gcloud eventarc triggers create $TRIGGER_NAME \
     --location=$REGION \
     --destination-run-service=crf-nodejs-event \
  --destination-run-region=$BUCKET_REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$BUCKET_NAME" \
     --service-account=$SERVICE_ACCOUNT_ADDRESS

Ten en cuenta lo siguiente:

gcs-function-trigger es el nombre del activador.
crf-nodejs-event es el nombre del servicio de Cloud Run en el que se implementa nuestra función.
Para la marca –event-filters, no uses el prefijo gs:// en el nombre del bucket.

En la documentación de Cloud Run, puedes encontrar un instructivo detallado para configurar el servicio de activador desde Cloud Storage con Eventarc: https://cloud.google.com/run/docs/tutorials/eventarc

6. Prueba la función

Cuando se complete la implementación, verás la URL del servicio. Para invocar la función, debes enviar una solicitud autenticada con tu token de identidad o el token de identidad de un principal que tenga el rol de invocador de Cloud Run, como se muestra a continuación:

# get the Service URL
SERVICE_URL="$(gcloud run services describe crf-nodejs-event --region us-central1 --format 'value(status.url)')"

# invoke the service
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

Con nuestra función implementada y un activador creado, ya está todo listo para invocar la función.

Crea un archivo y súbelo a tu bucket de Cloud Storage. Puedes hacerlo a través de la interfaz web de la consola de Cloud o con la herramienta de CLI gsutil, p.ej.:

echo "hello world" > test.txt
gsutil cp test gs://$BUCKET_NAME

Cuando el archivo se suba correctamente, se generará un evento y tu función imprimirá información básica sobre el objeto, p.ej., el nombre del archivo. Puedes encontrar este resultado en las entradas de registro de la función en la consola de Cloud. Como alternativa, puedes consultar este resultado con la CLI de gcloud:

gcloud logging read "resource.labels.service_name=crf-nodejs-event AND textPayload: File" --format=json

y deberías ver el siguiente resultado:

"textPayload": "File: test.txt"

7. ¡Felicitaciones!

¡Felicitaciones por completar el codelab!

Te recomendamos que revises la documentación de las funciones de Cloud Run.

Temas abordados

Cómo implementar una función de Cloud Run basada en eventos que se activa cada vez que se sube un objeto a un bucket de GCS
Cómo crear una cuenta de servicio con los roles adecuados para recibir un evento de Cloud Storage y, luego, invocar la función de Cloud Run

8. Limpia

Para evitar cargos imprevistos (por ejemplo, si este servicio de Cloud Run se invoca por error más veces que tu asignación mensual de invocaciones de Cloud Run en el nivel gratuito), puedes borrar el servicio de Cloud Run o el proyecto que creaste en el paso 2.

Para borrar los servicios de Cloud Run, ve a la consola de Cloud Run en https://console.cloud.google.com/run/ y borra el servicio crf-event-codelab que creaste en este codelab.

Si decides borrar todo el proyecto, puedes ir a https://console.cloud.google.com/cloud-resource-manager, seleccionar el proyecto que creaste en el paso 2 y elegir Borrar. Si borras el proyecto, deberás cambiar los proyectos en tu SDK de Cloud. Para ver la lista de todos los proyectos disponibles, ejecuta gcloud projects list.