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

Comienza a usar funciones de Cloud Run controladas por eventos

1. Introducción

Descripción general

Cloud Run Functions ofrece una nueva forma de implementar cargas de trabajo mediante los ya conocidos paradigmas de eventos de GCF y la firma de funciones. En lugar de usar nuestro proceso de compilación definido y la configuración de implementación, las funciones de Cloud Run te brindan control directo sobre el Service subyacente creado en Cloud Run.

Con las funciones de Cloud Run, proporcionamos la UX sencilla de la implementación de código fuente de Cloud Run, lo que brinda a los desarrolladores control completo sobre sus cargas de trabajo con los parámetros de configuración de Cloud Run.

En esta sección, aprenderás a implementar una función controlada por eventos en Node. Implementarás una función que se active cuando finalice un objeto en un bucket de Google Cloud Storage.

En este codelab, se utilizan muestras de nodejs que se indican en los siguientes ejemplos. Sin embargo, puedes usar las muestras de código de Cloud Functions (2nd gen) en el lenguaje que prefieras:

Qué aprenderás

Cómo implementar una función de Cloud Run controlada por 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 gcloud CLI

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

gcloud components update

Habilita las APIs

Antes de comenzar a usar este codelab, debes habilitar varias APIs. Este codelab requiere el uso de 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 establecer 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

Puedes crear un bucket de Cloud Storage con la ejecución del 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 necesarios de EventArc y el rol de invocador de Cloud Run para recibir un evento de Cloud Storage e 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"

Luego, 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 este 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, otórgale 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 desplázate a ese directorio 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.
El marcador –function (nuevo) se usa para establecer que el punto de entrada del nuevo servicio sea la firma de la función que quieres que se invoque.
(opcional) el comando –no-allow-unauthenticated para evitar que tu función se pueda invocar de forma pública

Puedes ver tu crf-nodejs-event de servicio nuevo si ejecutas 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 finaliza 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 de tu bucket.

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

6. Prueba la función

Cuando se complete la implementación, verás la URL de servicio. Para invocar la función, debes enviar una solicitud autenticada con tu token de identidad o el token de identidad de un principio 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

Ahora que implementamos nuestra función y creamos un activador, ya podemos invocar la función.

Crea un archivo y súbelo a tu bucket de Cloud Storage. Puedes hacer esto a través de la interfaz web de la consola de Cloud o con la herramienta de la CLI de 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 gcloud CLI:

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

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 funciones de Cloud Run.

Temas abordados

Cómo implementar una función de Cloud Run controlada por 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 involuntarios (por ejemplo, si este servicio de Cloud Run se invoca de forma involuntaria más veces que tu asignación mensual de invocación de Cloud Run en el nivel gratuito), puedes borrar el servicio de Cloud Run o borrar 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 el proyecto completo, 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.