Etkinlik odaklı Cloud Run işlevlerini kullanmaya başlama

1. Giriş

Genel Bakış

Cloud Run işlevleri, tanıdık GCF etkinlik paradigmalarını ve işlev imzasını kullanarak iş yüklerini dağıtmanın yeni bir yoludur. Cloud Run işlevleri, Cloud Run'da oluşturulan temel hizmet üzerinde doğrudan kontrol sahibi olmanızı sağlar. Bunun için kendi derleme sürecimizi ve dağıtım yapılandırmalarımızı kullanmaz.

Cloud Run işlevleriyle, Cloud Run kaynak dağıtımının basit kullanıcı deneyimini sunuyoruz. Böylece geliştiriciler, Cloud Run yapılandırmalarını kullanarak iş yükleri üzerinde tam kontrol sahibi olur.

Bu bölümde, Node'da etkinlik odaklı işlevleri nasıl dağıtacağınızı öğreneceksiniz. Bir Google Cloud Storage paketinde bir nesne tamamlandığında tetiklenen bir işlev dağıtırsınız.

Bu kod laboratuvarında aşağıdaki örneklerde nodejs örnekleri kullanılmaktadır. Ancak 2. nesil Cloud Functions kod örneklerini istediğiniz dilde kullanabilirsiniz:

Neler öğreneceksiniz?

  • Bir GCS paketine nesne yüklendiğinde tetiklenen etkinlik odaklı bir Cloud Run işlevi dağıtma
  • Cloud Storage'dan etkinlik almak ve Cloud Run işlevini çağırmak için uygun rollere sahip bir hizmet hesabı oluşturma

2. Ortam değişkenlerini ayarlama ve API'leri etkinleştirme

gcloud CLI'yi güncelleme

Bu kod laboratuvarının çalıştırılması için gcloud CLI'nin son sürümünün yüklü olması gerekir. KSA'yı güncellemek için

gcloud components update

API'leri etkinleştir

Bu kod laboratuvarını kullanmaya başlamadan önce etkinleştirmeniz gereken birkaç API vardır. Bu kod laboratuvarının çalışması için aşağıdaki API'lerin kullanılması gerekir. Aşağıdaki komutu çalıştırarak bu API'leri etkinleştirebilirsiniz:

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

Ortam değişkenlerini ayarlama

Bu codelab boyunca kullanılacak ortam değişkenlerini ayarlayabilirsiniz.

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. Depolama alanı paketi ve hizmet hesabı oluşturma

Storage paketi oluşturma

Aşağıdaki komutu çalıştırarak bir Cloud Storage paketi oluşturabilirsiniz:

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

Hizmet hesabı oluşturma

Bu örnekte, Cloud Storage'dan etkinlik almak ve Cloud Run işlevini çağırmak için gerekli EventArc izinlerine ve Cloud Run çağırıcı rolüne sahip bir hizmet hesabı oluşturacaksınız.

Öncelikle hizmet hesabını oluşturun.

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"

Ardından, tetikleyicinin etkinlik sağlayıcılardan etkinlik alabilmesi için projedeki Eventarc Etkinlik Alıcısı rolünü (roles/eventarc.eventReceiver), Eventarc tetikleyicinizle ilişkili hizmet hesabına verin.

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

Ardından, işlevi çağırabilmesi için hizmet hesabına Cloud Run çağırıcı rolü verin.

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

4. İşlevi oluşturma ve dağıtma

Öncelikle kaynak kod için bir dizin oluşturun ve cd komutunu kullanarak bu dizine gidin.

mkdir ../$SERVICE_NAME && cd $_

Ardından, aşağıdaki içeriğe sahip bir package.json dosyası oluşturun:

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

Ardından, aşağıdaki içeriğe sahip bir index.js dosyası oluşturun:

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

Artık aşağıdaki komutu çalıştırarak Cloud Run işlevini dağıtabilirsiniz:

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

Önemli:

  • –source işaretçisi, Cloud Run'a işlevi çalıştırılabilir bir kapsayıcı tabanlı hizmet olarak derlemesini bildirmek için kullanılır.
  • –function işaretçisi (yeni), yeni hizmetin giriş noktasını çağrılmasını istediğiniz işlev imzası olarak ayarlamak için kullanılır.
  • (isteğe bağlı) İşlevinizin herkese açık olarak çağrılmasını önlemek için –no-allow-unauthenticated

Aşağıdaki komutu çalıştırarak yeni hizmetinizi crf-nodejs-event görüntüleyebilirsiniz:

gcloud beta run services describe $SERVICE_NAME

5. Etkinlik oluşturma

Google Cloud Storage'da her nesne tamamlandığında işlevimize mesaj göndermek için bir Eventarc tetikleyicisi oluşturabiliriz:

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

Önemli:

  • gcs-function-trigger, tetikleyicinin adıdır.
  • crf-nodejs-event, işlevimizin dağıtıldığı Cloud Run hizmetinin adıdır.
  • –event-filters işareti için paket adınızda gs:// ön ekini kullanmayın.

Eventarc'ı kullanarak Cloud Storage'dan Tetikleyici hizmetinin nasıl ayarlanacağına dair ayrıntılı bir eğitim, şu adresteki Cloud Run dokümanlarında bulunabilir: https://cloud.google.com/run/docs/tutorials/eventarc

6. İşlevi test etme

Dağıtım tamamlandığında hizmet URL'sini görürsünüz. İşlevi çağırmak için kimlik jetonunuzu veya Cloud Run Invoker rolüne sahip bir tüzel kişinin kimlik jetonunu içeren kimliği doğrulanmış bir istek göndermeniz gerekir. Aşağıda gösterildiği gibi:

# 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

İşlevimiz dağıtıldı ve bir tetikleyici oluşturuldu. Artık işlevi çağırmaya hazırız.

Bir dosya oluşturun ve Cloud Storage paketinize yükleyin. Bunu Cloud Console web arayüzü üzerinden veya gsutil CLI aracını kullanarak yapabilirsiniz.

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

Dosya başarıyla yüklendiğinde bir etkinlik oluşturulur ve işleviniz, nesneyle ilgili bazı temel bilgileri (ör. dosya adı) yazdırır. Bu çıkışı, Cloud Console'daki işlevin günlük girişlerinde bulabilirsiniz. Alternatif olarak, gcloud KSA'yı kullanarak bu çıkışı sorgulayabilirsiniz:

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

Aşağıdaki çıkışı göreceksiniz:

"textPayload": "File: test.txt"

7. Tebrikler!

Codelab'i tamamladığınız için tebrikler.

Cloud Run işlevleri ile ilgili dokümanları incelemenizi öneririz.

Ele aldığımız konular

  • Bir GCS paketine nesne yüklendiğinde tetiklenen etkinlik odaklı bir Cloud Run işlevi dağıtma
  • Cloud Storage'dan etkinlik almak ve Cloud Run işlevini çağırmak için uygun rollere sahip bir hizmet hesabı oluşturma

8. Temizleme

Yanlışlıkla yapılan ödemeleri önlemek için (örneğin, bu Cloud Run hizmeti yanlışlıkla ücretsiz kademede aylık Cloud Run çağrısı tahsisatınızdan daha fazla sayıda çağrılırsa) Cloud Run hizmetini veya 2. adımda oluşturduğunuz projeyi silebilirsiniz.

Cloud Run hizmetlerini silmek için https://console.cloud.google.com/run/ adresindeki Cloud Run Cloud Console'a gidin ve bu kod laboratuvarında oluşturduğunuz crf-event-codelab hizmetini silin.

Projenin tamamını silmeyi seçerseniz https://console.cloud.google.com/cloud-resource-manager adresine gidip 2. adımda oluşturduğunuz projeyi seçin ve Sil'i tıklayın. Projeyi silerseniz Cloud SDK'nızdaki projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak mevcut tüm projelerin listesini görüntüleyebilirsiniz.