Cloud Run에서 함수 배포

이 페이지에서는 Cloud Run에서 함수를 배포하고 수정하는 방법을 설명합니다. Hello World 함수 배포의 둘러보기 예시는 샘플 함수 배포를 참조하세요.

Cloud Run 함수 배포는 이면에서 Google Cloud의 빌드팩과 Cloud Build를 사용하여 함수의 소스 코드로부터 컨테이너 이미지를 자동으로 빌드합니다. 사용자가 자신의 머신에 Docker를 설치하거나 빌드팩 또는 Cloud Build를 설정할 필요가 없습니다.

Cloud Run 함수 배포는 또한 Artifact Registry를 사용하여 아티팩트를 저장하고 컨테이너 이미지를 관리합니다. 프로젝트에 아직 Artifact Registry 저장소 cloud-run-source-deploy가 생성되지 않았으면 Artifact Registry가 이 이름으로 저장소를 자동으로 만듭니다.

시작하기 전에

설정 페이지에 설명된 대로 Cloud Run용 새 프로젝트를 설정했는지 확인합니다.

Artifact Registry, Cloud Build, Cloud Run Admin API, Cloud Logging API를 사용 설정합니다.

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

원하는 경우 이벤트 트리거를 사용하도록 Eventarc API를 사용 설정합니다.

 gcloud services enable eventarc.googleapis.com

프로젝트에서 인증되지 않은 호출을 제한하는 도메인 제한 조직 정책이 적용되는 경우 비공개 서비스 테스트의 설명대로 배포된 서비스에 액세스해야 합니다.

필요한 역할

소스에서 Cloud Run 서비스를 배포하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Cloud Run 소스 개발자 (roles/run.sourceDeveloper)
서비스 계정 사용자(roles/iam.serviceAccountUser)

Cloud Run과 연결된 IAM 역할 및 권한 목록은 Cloud Run IAM 역할 및 Cloud Run IAM 권한을 참조하세요. Cloud Run 서비스가 Cloud 클라이언트 라이브러리와 같은 Google Cloud API와 상호작용하는 경우에는 서비스 ID 구성 가이드를 참조하세요. 역할 부여에 대한 자세한 내용은 배포 권한 및 액세스 관리를 참조하세요.

서비스 계정 역할

Cloud Build가 소스를 빌드할 수 있게 하려면 다음을 실행하여 Compute Engine 기본 서비스 계정에 Cloud Build 서비스 계정 역할을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/cloudbuild.builds.builder

PROJECT_NUMBER를 Google Cloud 프로젝트 번호로, PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다. 프로젝트 ID와 프로젝트 번호를 찾는 방법은 프로젝트 만들기 및 관리를 참조하세요.

Compute Engine 기본 서비스 계정에 Cloud Build 서비스 계정 역할을 부여하려면 전파하는 데 몇 분 정도 걸립니다.

참고:

iam.automaticIamGrantsForDefaultServiceAccounts 조직 정책 제약조건은 편집자 역할이 기본 서비스 계정에 자동으로 부여되지 않도록 합니다. 2024년 5월 3일 이후에 조직을 만든 경우 기본적으로 이 제약조건이 적용됩니다.

이 제약조건을 적용하여 자동 역할 부여를 사용 중지하는 것이 좋습니다. 자동 역할 부여를 중지한 경우 기본 서비스 계정에 부여할 역할을 결정한 후 직접 이러한 역할을 부여해야 합니다.

기본 서비스 계정에 이미 편집자 역할이 있으면 편집자 역할을 권한이 더 낮은 역할로 바꾸는 것이 좋습니다. 서비스 계정 역할을 안전하게 수정하려면 정책 시뮬레이터를 사용하여 변경사항의 영향을 확인한 후 적절한 역할을 부여하고 취소합니다.

Eventarc를 사용 중이면 필요에 따라 서비스 계정에 다음 역할을 부여합니다.
- Cloud Build 편집자(roles/cloudbuild.builds.editor)
- Cloud Run 관리자(roles/run.admin)
- 서비스 계정 만들기(roles/iam.serviceAccountCreator)
- Cloud Run 호출자(roles/run.invoker)
- Eventarc 관리자(roles/eventarc.admin)
- 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
- 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)
- 스토리지 관리자(roles/storage.admin)
Eventarc 트리거의 특정 역할 부여에 대한 자세한 내용은 Cloud Run 대상의 역할 및 권한을 참조하세요.

함수 만들기 및 배포

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 함수를 배포할 수 있습니다. 선택한 도구 사용에 관한 안내를 보려면 해당 탭을 클릭하세요.

콘솔

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
함수 작성을 클릭합니다.
서비스 이름 필드에 함수를 설명하는 이름을 입력합니다. 서비스 이름은 문자로만 시작해야 하고 문자, 숫자, 하이픈을 포함하여 최대 49자까지 포함할 수 있습니다. 서비스 이름은 하이픈으로 끝날 수 없고 리전 및 프로젝트별로 고유해야 합니다. 서비스 이름은 나중에 변경할 수 없으며 공개적으로 표시됩니다.
리전 목록에서 기본값을 사용하거나 함수를 배포하려는 리전을 선택합니다.
런타임 목록에서 기본값을 사용하거나 런타임 버전을 선택합니다.
원하는 경우 트리거 섹션에서 트리거 추가를 클릭하고 옵션을 선택합니다. Eventarc 트리거 창이 열리면 트리거에 대해 다음 세부정보를 수정할 수 있습니다.
1. 트리거 이름 필드에 트리거의 이름을 입력하거나 기본 이름을 사용합니다.
2. 목록에서 트리거 유형을 선택하고 다음 트리거 유형 중 하나를 지정합니다.
  - Google 소스를 선택하면 Pub/Sub, Cloud Storage, Firestore, 기타 Google 이벤트 제공자의 트리거를 지정할 수 있습니다.
  - 커스텀을 선택하면 애플리케이션 코드에서 이벤트를 생성하고 소비할 수 있습니다. Eventarc 트리거 창의 메시지에 따라 채널을 만듭니다. 채널은 제작자로부터 소비자에게 커스텀 이벤트를 전달하기 위해 파이프라인으로 사용되는 리소스입니다. 커스텀 이벤트가 채널에 게시되고 Eventarc 트리거가 이러한 이벤트를 구독합니다.
  - 서드 파티를 선택하면 Eventarc 소스를 제공하는 Google 이외의 제공자와 통합할 수 있습니다. 자세한 내용은 Eventarc의 서드 파티 이벤트를 참조하세요.
3. 목록에서 이벤트 제공자를 선택하고 함수 트리거를 위한 이벤트 유형을 제공하는 제품을 선택합니다. 이벤트 제공자 목록은 이벤트 제공자 및 대상을 참조하세요.
4. 목록에서 이벤트 유형을 선택합니다. 트리거 구성은 지원되는 이벤트 유형에 따라 다릅니다. 자세한 내용은 이벤트 유형을 참조하세요.
5. 리전 필드에서 Eventarc 트리거의 위치를 선택합니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 함수도 동일한 리전에 배포해야 합니다. Eventarc 트리거 위치에 대한 자세한 내용은 Eventarc 위치 이해를 참조하세요.
6. 서비스 계정 필드에서 서비스 계정을 선택합니다. Eventarc 트리거는 함수를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 함수 호출 권한이 있어야 합니다. 기본적으로 Cloud Run은 Compute Engine 기본 서비스 계정을 사용합니다.
7. 선택적으로 수신 요청을 전송할 서비스 URL 경로를 지정합니다. 이는 트리거의 이벤트가 전송되어야 하는 대상 서비스의 상대 경로입니다. 예를 들면 /, /route, route, route/subroute입니다.
8. 필수 필드를 작성했으면 트리거 저장을 클릭합니다.
인증 아래에서 다음을 구성합니다.
- 웹훅과 같은 공개 HTTP 함수를 만드는 경우 인증되지 않은 호출 허용을 선택합니다. 이를 선택하면 IAM 호출자 역할이 특수 식별자 allUser에 할당됩니다. 서비스를 만든 후 나중에 IAM을 사용하여 이 설정을 수정할 수 있습니다. 이를 선택할 수 있는 권한(Cloud Run 관리자 역할)이 없으면 서비스가 배포되고 인증이 요구됩니다.
- 이벤트 트리거 함수를 만드는 경우 인증 필요를 선택합니다.
원하는 경우 함수에 대해 다음 추가 구성을 업데이트합니다.
1. 필요에 따라 CPU 할당 및 가격 책정을 설정합니다.
2. 서비스 자동 확장 아래에서 필요에 따라 최소 인스턴스를 지정합니다.
3. 필요에 따라 인그레스 제어 설정을 지정합니다.
4. 컨테이너, 볼륨, 네트워킹, 보안 섹션을 확장하여 해당 탭에서 기타 선택적인 설정을 지정합니다.
만들기를 클릭하고 Cloud Run이 자리표시자 버전을 사용해서 서비스를 만들 때까지 기다립니다.
콘솔이 함수의 소스 코드를 볼 수 있는 소스로 리디렉션됩니다. 저장 및 재배포를 클릭합니다.
소스 탭에서 선택적으로 페이로드 표시를 클릭하면 수신 이벤트의 페이로드 예시를 볼 수 있습니다.
배포 후 테스트 버튼을 클릭하여 생성된 함수를 테스트합니다.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
gcloud 구성요소를 최신 버전으로 업데이트합니다.
```
gcloud components update
```
샘플 코드가 포함된 디렉터리에서 다음 명령어를 실행합니다.
```
gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION
```
다음과 같이 바꿉니다.
- FUNCTION을 배포하려는 함수의 이름으로 바꿉니다. 이 매개변수를 완전히 생략할 수 있지만 생략하면 이름을 입력하라는 메시지가 표시됩니다.
- FUNCTION_ENTRYPOINT를 소스 코드에 있는 함수의 진입점으로 바꿉니다. 이는 함수가 실행될 때 Cloud Run이 실행하는 코드입니다. 이 플래그의 값은 소스 코드에 있는 함수 이름 또는 정규화된 클래스 이름이어야 합니다.
- BASE_IMAGE를 함수의 기본 이미지 환경으로 바꿉니다. 기본 이미지 및 각 이미지에 포함된 패키지에 대한 자세한 내용은 런타임 기본 이미지를 참조하세요.
- REGION을 함수를 배포하려는 Google Cloud 리전으로 바꿉니다. 예를 들면 us-central1입니다.
선택사항:
- 웹훅과 같이 공개 HTTP 함수를 만드는 경우 --allow-unauthenticated 플래그를 지정합니다. 이 플래그는 Cloud Run IAM 호출자 역할을 특수 식별자 allUser에 할당합니다. 서비스를 만든 후 나중에 IAM을 사용하여 이 설정을 수정할 수 있습니다. 이벤트 트리거 함수 또는 인증된 서비스를 만드는 경우 이 플래그를 생략할 수 있습니다.

원하는 경우 함수를 배포한 후 Eventarc 트리거를 함수에 추가할 수 있습니다. 트리거를 추가하려면 다음 명령어를 실행합니다.

  gcloud eventarc triggers create EVENTARC_TRIGGER_NAME \
      --location=EVENTARC_TRIGGER_LOCATION \
      --destination-run-service=FUNCTION \
      --destination-run-region=REGION \
      --event-filters="type=EVENTARC_FILTER_TYPE" \
      --event-filters="EVENTARC_EVENT_FILTER" \
      --service-account=EVENTARC_TRIGGER_SERVICE_ACCOUNT

다음과 같이 바꿉니다.

EVENTARC_TRIGGER_NAME을 Eventarc 트리거 이름으로 바꿉니다.
EVENTARC_TRIGGER_LOCATION을 Eventarc 트리거 위치로 바꿉니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 함수도 동일한 리전에 배포해야 합니다. Eventarc 트리거 위치에 대한 자세한 내용은 Eventarc 위치 이해를 참조하세요.
FUNCTION을 배포된 함수의 이름으로 바꿉니다.
REGION을 함수의 Cloud Run 리전으로 바꿉니다.
EVENTARC_FILTER_TYPE을 트리거가 모니터링하는 이벤트 필터로 바꿉니다. 모든 --event-filters 필터와 일치하는 이벤트가 함수 호출을 트리거합니다. 각 트리거는 --event-filters="type=EVENTARC_FILTER_TYPE" 형식으로 지원되는 이벤트 유형이어야 합니다. 이 이벤트 유형은 생성 후 변경할 수 없습니다. EVENT_FILTER_TYPE을 변경하려면 새 트리거를 만들고 이전 트리거를 삭제합니다. 선택적으로 ATTRIBUTE=VALUE 형식으로 지원되는 필터를 사용해서 --event-filters 플래그를 반복하여 더 많은 필터를 추가할 수 있습니다.
EVENTARC_TRIGGER_SERVICE_ACCOUNT를 서비스 계정으로 바꿉니다. Eventarc 트리거는 함수를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 함수 호출 권한이 있어야 합니다. 기본적으로 Cloud Run은 기본 컴퓨팅 서비스 계정을 사용합니다.

Cloud Run 위치

Cloud Run은 리전을 기반으로 합니다. 즉, Cloud Run 서비스를 실행하는 인프라가 특정 리전에 위치해 있으며 해당 리전 내의 모든 영역에서 중복으로 사용할 수 있도록 Google이 관리합니다.

Cloud Run 서비스를 실행하는 리전을 선택하는 데 있어 중요한 기준은 지연 시간, 가용성 또는 내구성 요구사항입니다. 일반적으로 사용자와 가장 가까운 리전을 선택할 수 있지만 Cloud Run 서비스에서 사용하는 다른 Google Cloud 제품 위치도 고려해야 합니다. 여러 위치에서 Google Cloud 제품을 함께 사용하면 서비스 지연 시간과 비용에 영향을 미칠 수 있습니다.

Cloud Run은 다음 리전에서 사용할 수 있습니다.

등급 1 가격 적용

asia-east1(타이완)
asia-northeast1(도쿄)
asia-northeast2(오사카)
europe-north1(핀란드) 낮은 CO₂
europe-southwest1(마드리드) 낮은 CO₂
europe-west1(벨기에) 낮은 CO₂
europe-west4(네덜란드) 낮은 CO₂
europe-west8(밀라노)
europe-west9(파리) 낮은 CO₂
me-west1(텔아비브)
us-central1(아이오와) 낮은 CO₂
us-east1(사우스캐롤라이나)
us-east4(북 버지니아)
us-east5(콜럼버스)
us-south1(댈러스) 낮은 CO₂
us-west1(오리건) 낮은 CO₂

등급 2 가격 적용

africa-south1(요하네스버그)
asia-east2(홍콩)
asia-northeast3(대한민국 서울)
asia-southeast1(싱가포르)
asia-southeast2 (자카르타)
asia-south1(인도 뭄바이)
asia-south2(인도 델리)
australia-southeast1(시드니)
australia-southeast2(멜버른)
europe-central2(폴란드 바르샤바)
europe-west10(베를린) 낮은 CO₂
europe-west12(토리노)
europe-west2(영국 런던) 낮은 CO₂
europe-west3(독일 프랑크푸르트) 낮은 CO₂
europe-west6(스위스 취리히) 낮은 CO₂
me-central1(도하)
me-central2(담맘)
northamerica-northeast1(몬트리올) 낮은 CO₂
northamerica-northeast2(토론토) 낮은 CO₂
southamerica-east1(브라질 상파울루) 낮은 CO₂
southamerica-west1(칠레 산티아고) 낮은 CO₂
us-west2(로스앤젤레스)
us-west3(솔트레이크시티)
us-west4(라스베이거스)

Cloud Run 서비스를 이미 만들었다면 Google Cloud 콘솔의 Cloud Run 대시보드에서 리전을 확인할 수 있습니다.

이벤트 재시도 사용 설정

Eventarc는 Pub/Sub를 전송 계층으로 사용하며 사용자 함수에 작동하지 않을 수 있는 기본 재시도 정책을 갖고 있습니다.

Eventarc 트리거를 만든 후에는 Eventarc에서 재시도 정책을 업데이트하고 Pub/Sub에서 데드 레터 주제를 구성하는 것이 좋습니다.

기존 함수 수정

함수의 구성 또는 코드를 수정할 수 있습니다.

구성 수정

CPU 할당, 메모리, VPC 연결 등의 구성 매개변수를 수정하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
서비스 목록에서 업데이트할 서비스를 찾고 클릭하여 해당 서비스의 세부정보를 엽니다.
새 버전 수정 및 배포를 클릭하여 버전 배포 양식을 표시합니다.
구성 설정을 수정합니다.
배포를 클릭하고 배포가 완료될 때까지 기다립니다.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
하나 이상의 서비스 구성 설정을 업데이트하려면 업데이트하려는 구성의 명령줄 플래그와 함께 gcloud beta run services update SERVICE 명령어를 사용합니다. SERVICE를 서비스 이름으로 바꿉니다.

새 소스 코드 재배포

Google Cloud 콘솔 또는 gcloud CLI를 사용하여 함수의 기본 이미지, 런타임, 소스 코드를 수정할 수 있습니다.

선택한 도구 사용에 관한 안내를 보려면 해당 탭을 클릭하세요.

콘솔

Google Cloud 콘솔에서 Cloud Run 페이지로 이동합니다.

Cloud Run으로 이동
서비스 목록에서 업데이트하려는 함수를 찾아서 클릭하여 해당 함수의 세부정보를 엽니다.
소스 탭으로 이동하고 소스 수정을 클릭합니다.
기본 이미지 옆에 있는 런타임 및 보안 업데이트 수정을 클릭하고 필요에 따라 목록에서 다른 런타임 또는 환경을 선택하고 저장을 클릭합니다.
필요에 따라 함수 진입점을 수정합니다.
파일 섹션에서 새 파일을 만들려면 파일 추가를 선택하고, 파일 이름을 바꾸려면 파일 이름 바꾸기를 선택하고, 파일을 삭제하려면 파일 삭제를 선택합니다.
코드 섹션에서 필요에 따라 소스 코드를 수정합니다.
저장 및 재배포를 클릭하고 배포가 완료될 때까지 기다립니다.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
함수의 소스 코드가 포함된 디렉터리에서 다음 명령어를 실행합니다.
```
gcloud beta run deploy FUNCTION \
       --source . \
       --function FUNCTION_ENTRYPOINT \
       --base-image BASE_IMAGE \
       --region REGION
```
다음과 같이 바꿉니다.
- FUNCTION을 수정하려는 함수의 이름으로 바꿉니다.
- FUNCTION_ENTRYPOINT를 소스 코드에 있는 함수의 진입점으로 바꿉니다.
- BASE_IMAGE를 함수의 기본 이미지 환경으로 바꿉니다. 대부분의 경우 런타임 ID를 지정할 수 있습니다(예: nodejs22).
  
  또는 스택에서 특정 시스템 패키지를 사용하거나 기본 이미지가 다운로드된 위치의 리전을 지정하려면 다음 중 하나를 지정하면 됩니다.
  - 전체 기본 이미지 경로(예: us-central1-docker.pkg.dev/serverless-runtimes/google-22-full/runtimes/nodejs22). 이 옵션을 선택하면 기본 이미지, 스택의 특정 시스템 패키지, 기본 이미지가 다운로드된 리전을 지정할 수 있습니다.
  - 전체 기본 이미지 경로의 별칭(예: google-22/nodejs22 또는 google-22-full/nodejs22). 이 축약된 별칭 옵션을 사용하면 기본 이미지 및 스택의 특정 시스템 패키지를 지정할 수 있습니다.
  기본 이미지 및 각 이미지에 포함된 패키지에 대한 자세한 내용은 런타임 기본 이미지를 참조하세요.
- REGION을 함수를 배포하려는 Google Cloud 리전으로 바꿉니다. 예를 들면 us-central1입니다.
선택적 플래그

함수를 수정하는 동안 다음과 같은 선택적인 플래그를 구성할 수 있습니다.
- 빌드 환경 변수 플래그를 사용하면 빌드 시간에 특정된 인증서 또는 매개변수 구성과 같이 빌드 단계 중에 환경 변수를 지정할 수 있습니다.
- 작업자 풀 플래그를 사용하면 VPC 서비스 제어 보안 빌드 컨텍스트에서 사용할 작업자 풀을 지정할 수 있습니다.
- 커스텀 빌드 서비스 계정 플래그를 사용하면 보안 강화를 위해 기본 빌드 서비스 계정의 대안을 지정할 수 있습니다.
- 자동 기본 이미지 업데이트 플래그를 사용하면 자동 업데이트를 사용 중지할 수 있습니다. 기본적으로 함수에는 자동 보안 업데이트가 사용 설정되어 있습니다.

다음 단계

새 함수를 배포한 후에는 다음을 수행할 수 있습니다.

Cloud Run에서 함수 배포

시작하기 전에

필요한 역할

서비스 계정 역할

함수 만들기 및 배포

콘솔

gcloud

Cloud Run 위치

등급 1 가격 적용

등급 2 가격 적용

이벤트 재시도 사용 설정

기존 함수 수정

구성 수정

콘솔

gcloud

새 소스 코드 재배포

콘솔

gcloud

선택적 플래그

다음 단계