이벤트 기반 Cloud Run 함수 시작하기

이벤트 기반 Cloud Run 함수 시작하기

이 Codelab 정보

subject최종 업데이트: 8월 23, 2024
account_circle작성자: Google 직원

1. 소개

Cloud Run 함수는 익숙한 GCF 이벤트 패러다임과 함수 서명을 사용하여 워크로드를 배포하는 새로운 방법입니다. Cloud Run 함수를 사용하면 Google의 사전 정의된 빌드 프로세스 및 배포 구성을 사용하는 대신 Cloud Run에서 생성된 기본 서비스를 직접 제어할 수 있습니다.

Cloud Run 함수를 사용하면 Cloud Run 소스 배포의 간단한 UX를 제공하여 개발자가 Cloud Run 구성을 사용하여 워크로드를 완전히 제어할 수 있습니다.

이 섹션에서는 Node에서 이벤트 기반 함수를 배포하는 방법을 알아봅니다. Google Cloud Storage 버킷에서 객체가 완료될 때마다 트리거되는 함수를 배포합니다.

이 Codelab에서는 아래 예시에서 nodejs 샘플을 사용합니다. 하지만 원하는 언어로 Cloud Functions 2세대 코드 샘플을 사용할 수 있습니다.

학습할 내용

  • 객체가 GCS 버킷에 업로드될 때마다 트리거되는 이벤트 기반 Cloud Run 함수를 배포하는 방법
  • Cloud Storage에서 이벤트를 수신하고 Cloud Run 함수를 호출할 수 있는 적절한 역할이 있는 서비스 계정을 만드는 방법

2. 환경 변수 설정 및 API 사용 설정

gcloud CLI 업데이트

이 Codelab을 사용하려면 최신 버전의 gcloud CLI가 설치되어 있어야 합니다. 다음을 실행하여 CLI를 업데이트할 수 있습니다.

gcloud components update

API 사용 설정

이 Codelab을 사용하기 전에 몇 가지 API를 사용 설정해야 합니다. 이 Codelab에서는 다음 API를 사용해야 합니다. 다음 명령어를 실행하여 이러한 API를 사용 설정할 수 있습니다.

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

환경 변수 설정

이 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. 저장소 버킷 및 서비스 계정 만들기

스토리지 버킷 만들기

다음 명령어를 실행하여 Cloud Storage 버킷을 만들 수 있습니다.

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

서비스 계정 만들기

이 예에서는 Cloud Storage에서 이벤트를 수신하고 Cloud Run 함수를 호출하는 데 필요한 Eventarc 권한과 Cloud Run 호출자 역할이 있는 서비스 계정을 만듭니다.

먼저 서비스 계정을 만듭니다.

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"

그런 다음 트리거가 이벤트 제공업체에서 이벤트를 수신할 수 있도록 프로젝트에 Eventarc 트리거와 연결된 서비스 계정에 Eventarc 이벤트 수신자 역할 (roles/eventarc.eventReceiver)을 부여합니다.

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

그런 다음 서비스 계정이 함수를 호출할 수 있도록 Cloud Run 호출자 역할을 부여합니다.

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

4. 함수 만들기 및 배포

먼저 소스 코드의 디렉터리를 만들고 해당 디렉터리로 이동합니다.

mkdir ../$SERVICE_NAME && cd $_

그런 다음 다음 콘텐츠로 package.json 파일을 만듭니다.

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

그런 다음 다음 콘텐츠로 index.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}`);
});

이제 다음 명령어를 실행하여 Cloud Run 함수를 배포할 수 있습니다.

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

다음 사항을 참고하세요.

  • –source 플래그는 Cloud Run에 함수를 실행 가능한 컨테이너 기반 서비스로 빌드하도록 지시하는 데 사용됩니다.
  • –function 플래그 (신규)는 새 서비스의 진입점을 호출하려는 함수 서명으로 설정하는 데 사용됩니다.
  • (선택사항) –no-allow-unauthenticated: 함수를 공개적으로 호출할 수 없도록 합니다.

다음 명령어를 실행하여 새 서비스 crf-nodejs-event를 볼 수 있습니다.

gcloud beta run services describe $SERVICE_NAME

5. 이벤트 만들기

Google Cloud Storage에서 객체가 완료될 때마다 함수에 메시지를 전송하는 Eventarc 트리거를 만들 수 있습니다.

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

다음 사항을 참고하세요.

  • gcs-function-trigger는 트리거의 이름입니다.
  • crf-nodejs-event는 함수가 배포된 Cloud Run 서비스의 이름입니다.
  • –event-filters 플래그: 버킷 이름에 gs:// 접두사를 사용하지 마세요.

Eventarc를 사용하여 Cloud Storage에서 트리거 서비스를 설정하는 방법에 관한 자세한 튜토리얼은 Cloud Run 문서(https://cloud.google.com/run/docs/tutorials/eventarc)를 참고하세요.

6. 함수 테스트

배포가 완료되면 서비스 URL이 표시됩니다. 함수를 호출하려면 아래와 같이 ID 토큰 또는 Cloud Run 호출자 역할이 있는 주 구성원의 ID 토큰으로 인증된 요청을 전송해야 합니다.

# 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

함수가 배포되고 트리거가 생성되었으므로 이제 함수를 호출할 준비가 되었습니다.

파일을 만들고 Cloud Storage 버킷에 업로드합니다. Cloud 콘솔 웹 인터페이스를 통해 또는 gsutil CLI 도구를 사용하여 이 작업을 수행할 수 있습니다.

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

파일이 업로드되면 이벤트가 생성되고 함수에서 객체에 관한 몇 가지 기본 정보(예: 파일 이름)를 출력합니다. 이 출력은 Cloud 콘솔의 함수 로그 항목에서 확인할 수 있습니다. 또는 gcloud CLI를 사용하여 이 출력을 쿼리할 수 있습니다.

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

다음과 같은 출력이 표시됩니다.

"textPayload": "File: test.txt"

7. 축하합니다.

Codelab을 완료했습니다. 축하합니다.

Cloud Run 함수 문서를 검토하는 것이 좋습니다.

학습한 내용

  • 객체가 GCS 버킷에 업로드될 때마다 트리거되는 이벤트 기반 Cloud Run 함수를 배포하는 방법
  • Cloud Storage에서 이벤트를 수신하고 Cloud Run 함수를 호출할 수 있는 적절한 역할이 있는 서비스 계정을 만드는 방법

8. 삭제

의도치 않은 요금이 청구되지 않도록 하려면(예: 이 Cloud Run 서비스가 무료 등급의 월별 Cloud Run 호출 할당량보다 더 자주 실수로 호출되는 경우) Cloud Run 서비스를 삭제하거나 2단계에서 만든 프로젝트를 삭제하면 됩니다.

Cloud Run 서비스를 삭제하려면 https://console.cloud.google.com/run/에서 Cloud Run Cloud 콘솔로 이동하여 이 Codelab에서 만든 crf-event-codelab 서비스를 삭제합니다.

전체 프로젝트를 삭제하려면 https://console.cloud.google.com/cloud-resource-manager로 이동하여 2단계에서 만든 프로젝트를 선택하고 삭제를 선택합니다. 프로젝트를 삭제하면 Cloud SDK에서 프로젝트를 변경해야 합니다. gcloud projects list를 실행하여 사용 가능한 모든 프로젝트 목록을 볼 수 있습니다.