Cloud Run 함수 시작하기

Cloud Run 함수 시작하기

이 Codelab 정보

subject최종 업데이트: 5월 7, 2025
account_circle작성자: Mete Atamel

1. 소개

개요

Cloud Run 함수는 Cloud Run 및 Eventarc를 기반으로 하는 Google Cloud의 Functions as a Service 제품으로, 성능 및 확장성에 대한 고급 제어, 함수 런타임 및 90개 이상의 이벤트 소스 트리거에 대한 추가 제어를 제공합니다.

이 Codelab에서는 HTTP 호출에 응답하고 Pub/Sub 메시지 및 Cloud 감사 로그에 의해 트리거되는 Cloud Run 함수를 만드는 방법을 안내합니다.

이 Codelab에서는 --base-image 플래그를 사용하여 기본 이미지를 지정하여 함수 배포에 자동 기본 이미지 업데이트를 사용합니다. Cloud Run의 자동 기본 이미지 업데이트를 사용하면 Google이 기본 이미지의 운영체제 및 언어 런타임 구성요소에 보안 패치를 자동으로 적용할 수 있습니다. 기본 이미지가 업데이트되도록 서비스를 다시 빌드하거나 다시 배포할 필요가 없습니다. 자세한 내용은 자동 기본 이미지 업데이트를 참고하세요.

자동 기본 이미지 업데이트를 사용하지 않으려면 이 Codelab에 표시된 예시에서 --base-image 플래그를 삭제하면 됩니다.

학습할 내용

  • Cloud Run 함수 및 자동 기본 이미지 업데이트 사용 방법에 관한 개요입니다.
  • HTTP 호출에 응답하는 함수를 작성하는 방법
  • Pub/Sub 메시지에 응답하는 함수를 작성하는 방법
  • Cloud Storage 이벤트에 응답하는 함수를 작성하는 방법
  • 두 버전 간에 트래픽을 분할하는 방법
  • 최소 인스턴스로 콜드 스타트를 제거하는 방법

2. 설정 및 요구사항

루트 폴더 만들기

모든 예의 루트 폴더를 만듭니다.

mkdir crf-codelab
cd crf-codelab

환경 변수 설정

이 Codelab 전체에서 사용할 환경 변수를 설정합니다.

gcloud config set project <YOUR-PROJECT-ID>
REGION=<YOUR_REGION>

PROJECT_ID=$(gcloud config get-value project)

API 사용 설정

필요한 모든 서비스를 사용 설정합니다.

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  eventarc.googleapis.com \
  run.googleapis.com \
  logging.googleapis.com \
  pubsub.googleapis.com

3. HTTP 함수

첫 번째 함수로 HTTP 요청에 응답하는 인증된 Node.js 함수를 만들어 보겠습니다. 10분의 제한 시간을 사용하여 함수가 HTTP 요청에 더 많은 시간을 할애할 수 있는 방법을 보여줍니다.

만들기

앱 폴더를 만들고 폴더로 이동합니다.

mkdir hello-http
cd hello-http

HTTP 요청에 응답하는 index.js 파일을 만듭니다.

const functions = require('@google-cloud/functions-framework');

functions.http('helloWorld', (req, res) => {
  res.status(200).send('HTTP with Node.js in Cloud Run functions!');
});

package.json 파일을 만들어 종속 항목을 지정합니다.

{
  "name": "nodejs-run-functions-codelab",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^2.0.0"
  }
}

배포

함수를 배포합니다.

gcloud run deploy nodejs-run-function \
      --source . \
      --function helloWorld \
      --base-image nodejs22 \
      --region $REGION \
      --timeout 600 \
      --no-allow-unauthenticated

이 명령어는 빌드팩을 사용하여 함수 소스 코드를 프로덕션에 즉시 사용 가능한 컨테이너 이미지로 변환합니다.

다음 사항을 참고하세요.

  • --source 플래그는 Cloud Run에 함수를 실행 가능한 컨테이너 기반 서비스로 빌드하도록 지시하는 데 사용됩니다.
  • --function 플래그 (신규)는 새 서비스의 진입점을 호출하려는 함수 서명으로 설정하는 데 사용됩니다.
  • --base-image 플래그 (신규)는 nodejs22, python312, go123, java21, dotnet8, ruby33, php83와 같이 함수의 기본 이미지 환경을 지정합니다. 기본 이미지 및 각 이미지에 포함된 패키지에 대한 자세한 내용은 런타임 기본 이미지를 참고하세요.
  • (선택사항) --timeout 플래그를 사용하면 함수가 HTTP 요청에 응답하는 시간 제한을 더 길게 설정할 수 있습니다. 이 예에서는 10분의 응답 시간을 보여주기 위해 600초가 사용됩니다.
  • (선택사항) 함수를 공개적으로 호출할 수 없도록 하는 --no-allow-unauthenticated

테스트

다음 명령어를 사용하여 함수를 테스트합니다.

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

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

HTTP with Node.js in Cloud Run functions! 메시지가 응답으로 표시됩니다.

4. Pub/Sub 함수

두 번째 함수의 경우 특정 주제에 게시된 Pub/Sub 메시지에 의해 트리거되는 Python 함수를 만들어 보겠습니다.

Pub/Sub 인증 토큰 설정

2021년 4월 8일 이전에 Pub/Sub 서비스 계정을 사용 설정한 경우 Pub/Sub 서비스 계정에 iam.serviceAccountTokenCreator 역할을 부여합니다.

PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member  serviceAccount:service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
  --role roles/iam.serviceAccountTokenCreator

만들기

샘플에 사용할 Pub/Sub 주제를 만듭니다.

TOPIC=cloud-run-functions-pubsub-topic
gcloud pubsub topics create $TOPIC

앱 폴더를 만들고 폴더로 이동합니다.

mkdir ../hello-pubsub
cd ../hello-pubsub

CloudEvent ID가 포함된 메시지를 로깅하는 main.py 파일을 만듭니다.

import functions_framework

@functions_framework.cloud_event
def hello_pubsub(cloud_event):
   print('Pub/Sub with Python in Cloud Run functions! Id: ' + cloud_event['id'])

다음 콘텐츠로 requirements.txt 파일을 만들어 종속 항목을 지정합니다.

functions-framework==3.*

배포

함수를 배포합니다.

gcloud run deploy python-pubsub-function \
       --source . \
       --function hello_pubsub \
       --base-image python313 \
       --region $REGION \
       --no-allow-unauthenticated

서비스 계정 ID에 사용할 프로젝트 번호를 가져옵니다.

PROJECT_NUMBER=$(gcloud projects list --filter="project_id:$PROJECT_ID" --format='value(project_number)')

트리거 만들기

gcloud eventarc triggers create python-pubsub-function-trigger  \
    --location=$REGION \
    --destination-run-service=python-pubsub-function  \
    --destination-run-region=$REGION \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --transport-topic=projects/$PROJECT_ID/topics/$TOPIC \
    --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

테스트

주제에 메시지를 전송하여 함수를 테스트합니다.

gcloud pubsub topics publish $TOPIC --message="Hello World"

로그에 수신된 CloudEvent가 표시되어야 합니다.

gcloud run services logs read python-pubsub-function --region $REGION --limit=10

5. Cloud Storage 함수

다음 함수에서는 Cloud Storage 버킷의 이벤트에 응답하는 Node.js 함수를 만들어 보겠습니다.

설정

Cloud Storage 함수를 사용하려면 Cloud Storage 서비스 계정에 pubsub.publisher IAM 역할을 부여하세요.

SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member serviceAccount:$SERVICE_ACCOUNT \
  --role roles/pubsub.publisher

만들기

앱 폴더를 만들고 폴더로 이동합니다.

mkdir ../hello-storage
cd ../hello-storage

Cloud Storage 이벤트에만 응답하는 index.js 파일을 만듭니다.

const functions = require('@google-cloud/functions-framework');

functions.cloudEvent('helloStorage', (cloudevent) => {
  console.log('Cloud Storage event with Node.js in Cloud Run functions!');
  console.log(cloudevent);
});

package.json 파일을 만들어 종속 항목을 지정합니다.

{
  "name": "nodejs-crf-cloud-storage",
  "version": "0.0.1",
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^2.0.0"
  }
}

배포

먼저 Cloud Storage 버킷을 만들거나 기존에 있는 버킷을 사용합니다.

export BUCKET_NAME="gcf-storage-$PROJECT_ID"
​​export BUCKET="gs://gcf-storage-$PROJECT_ID"
gsutil mb -l $REGION $BUCKET

함수를 배포합니다.

gcloud run deploy nodejs-crf-cloud-storage \
 --source . \
 --base-image nodejs22 \
 --function helloStorage \
 --region $REGION \
 --no-allow-unauthenticated

함수가 배포되면 Cloud Console의 Cloud Run 섹션에서 확인할 수 있습니다.

이제 Eventarc 트리거를 만듭니다.

BUCKET_REGION=$REGION

gcloud eventarc triggers create nodejs-crf-cloud-storage-trigger \
  --location=$BUCKET_REGION \
  --destination-run-service=nodejs-crf-cloud-storage \
  --destination-run-region=$REGION \
  --event-filters="type=google.cloud.storage.object.v1.finalized" \
  --event-filters="bucket=$BUCKET_NAME" \
  --service-account=$PROJECT_NUMBER-compute@developer.gserviceaccount.com

테스트

버킷에 파일을 업로드하여 함수를 테스트하세요.

echo "Hello World" > random.txt
gsutil cp random.txt $BUCKET/random.txt

로그에 수신된 CloudEvent가 표시되어야 합니다.

gcloud run services logs read nodejs-crf-cloud-storage --region $REGION --limit=10

6. 트래픽 분할

Cloud Run 함수는 함수의 여러 버전을 지원하여 여러 버전 간에 트래픽을 분할하고 함수를 이전 버전으로 롤백할 수 있습니다.

이 단계에서는 함수의 두 버전을 배포한 다음 두 버전 간에 트래픽을 50-50으로 분할합니다.

만들기

앱 폴더를 만들고 폴더로 이동합니다.

mkdir ../traffic-splitting
cd ../traffic-splitting

색상 환경 변수를 읽고 해당 배경색으로 Hello World로 응답하는 Python 함수가 포함된 main.py 파일을 만듭니다.

import os

color = os.environ.get('COLOR')

def hello_world(request):
    return f'<body style="background-color:{color}"><h1>Hello World!</h1></body>'

다음 콘텐츠로 requirements.txt 파일을 만들어 종속 항목을 지정합니다.

functions-framework==3.*

배포

주황색 배경이 있는 함수의 첫 번째 버전을 배포합니다.

COLOR=orange
gcloud run deploy hello-world-colors \
 --source . \
 --base-image python313 \
 --function hello_world \
 --region $REGION \
 --allow-unauthenticated \
 --update-env-vars COLOR=$COLOR

이 시점에서 브라우저에서 HTTP 트리거 (위 배포 명령어의 URI 출력)를 보고 함수를 테스트하면 주황색 배경의 Hello World가 표시됩니다.

36ca0c5f39cc89cf.png

노란색 배경이 있는 두 번째 버전을 배포합니다.

COLOR=yellow
gcloud run deploy hello-world-colors \
 --source . \
 --base-image python313 \
 --function hello_world \
 --region $REGION \
 --allow-unauthenticated \
 --update-env-vars COLOR=$COLOR

이는 최신 버전이므로 함수를 테스트하면 노란색 배경의 Hello World가 표시됩니다.

391286a08ad3cdde.png

트래픽 50-50 분할

주황색 버전과 노란색 버전 간에 트래픽을 분할하려면 Cloud Run 서비스의 버전 ID를 찾아야 합니다. 다음은 버전 ID를 확인하는 명령어입니다.

gcloud run revisions list --service hello-world-colors \
  --region $REGION --format 'value(REVISION)'

출력은 다음과 유사해야 합니다.

hello-world-colors-00001-man
hello-world-colors-00002-wok

이제 다음과 같이 두 버전 간에 트래픽을 분할합니다 (버전 이름에 따라 X-XXX 업데이트).

gcloud run services update-traffic hello-world-colors \
  --region $REGION \
  --to-revisions hello-world-colors-0000X-XXX=50,hello-world-colors-0000X-XXX=50

테스트

공개 URL을 방문하여 함수를 테스트합니다. 절반의 경우 주황색 버전이 표시되고 나머지 절반의 경우 노란색 버전이 표시됩니다.

36ca0c5f39cc89cf.png 391286a08ad3cdde.png

자세한 내용은 롤백, 점진적 출시, 트래픽 마이그레이션을 참고하세요.

7. 최소 인스턴스

Cloud Run 함수에서 요청 처리를 위해 실행 및 준비 상태로 유지할 최소 함수 인스턴스 수를 지정할 수 있습니다. 이는 콜드 스타트 수를 제한하는 데 유용합니다.

이 단계에서는 느린 초기화가 포함된 함수를 배포합니다. 콜드 스타트 문제가 발생합니다. 그런 다음 최소 인스턴스 값을 1로 설정하여 함수를 배포하여 콜드 스타트를 제거합니다.

만들기

앱 폴더를 만들고 해당 폴더로 이동합니다.

mkdir ../min-instances
cd ../min-instances

main.go 파일을 만듭니다. 이 Go 서비스에는 긴 초기화를 시뮬레이션하기 위해 10초 동안 절전 모드로 전환되는 init 함수가 있습니다. HTTP 호출에 응답하는 HelloWorld 함수도 있습니다.

package p

import (
        "fmt"
        "net/http"
        "time"
)

func init() {
        time.Sleep(10 * time.Second)
}

func HelloWorld(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, "Slow HTTP Go in Cloud Run functions!")
}

배포

기본 최소 인스턴스 값이 0인 함수의 첫 번째 버전을 배포합니다.

gcloud run deploy go-slow-function \
 --source . \
 --base-image go123 \
 --function HelloWorld \
 --region $REGION \
 --no-allow-unauthenticated

다음 명령어를 사용하여 함수를 테스트합니다.

# get the Service URL
SERVICE_URL="$(gcloud run services describe go-slow-function --region $REGION --format 'value(status.url)')"

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

첫 번째 호출 시 10초 지연 (콜드 스타트)이 발생한 후 메시지가 표시됩니다. 후속 호출은 즉시 반환되어야 합니다.

최소 인스턴스 설정

첫 번째 요청에서 콜드 스타트를 제거하려면 다음과 같이 --min-instances 플래그를 1로 설정하여 함수를 다시 배포합니다.

gcloud run deploy go-slow-function \
 --source . \
 --base-image go123 \
 --function HelloWorld \
 --region $REGION \
 --no-allow-unauthenticated \
 --min-instances 1

테스트

함수를 다시 테스트합니다.

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

첫 번째 요청에서 더 이상 10초 지연이 표시되지 않습니다. 최소 인스턴스 덕분에 오랜 시간 사용하지 않은 후 첫 번째 호출 시 발생하는 콜드 스타트 문제가 사라졌습니다.

자세한 내용은 최소 인스턴스 사용을 참고하세요.

8. 축하합니다.

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

학습한 내용

  • Cloud Run 함수 및 자동 기본 이미지 업데이트 사용 방법에 관한 개요입니다.
  • HTTP 호출에 응답하는 함수를 작성하는 방법
  • Pub/Sub 메시지에 응답하는 함수를 작성하는 방법
  • Cloud Storage 이벤트에 응답하는 함수를 작성하는 방법
  • 두 버전 간에 트래픽을 분할하는 방법
  • 최소 인스턴스로 콜드 스타트를 제거하는 방법
bug_report 오류 신고