새 함수를 만드는 경우 Cloud Run의 콘솔 빠른 시작을 참고하세요.

빌드 프로세스 개요

이 가이드에서는 gcloud functions 명령어를 사용하여 배포된 함수의 빌드 프로세스 개요를 보여줍니다. gcloud run 명령어를 사용하여 배포된 함수의 빌드 프로세스를 알아보려면 다음을 참고하세요.

gcloud functions deploy 명령어를 사용하여 함수의 소스 코드를 배포하면 이 소스가 Cloud Storage 버킷에 저장됩니다. 그러면 Cloud Build가 컨테이너 이미지에 코드를 자동으로 빌드하고 해당 이미지를 이미지 레지스트리에 푸시합니다.

이미지를 빌드하는 프로세스는 완전 자동으로 진행되며 사용자의 직접 입력이 필요하지 않습니다. 빌드 프로세스에 사용된 모든 리소스는 자체 사용자 프로젝트로 실행됩니다.

프로젝트 내에서 빌드 프로세스를 실행하면 다음과 같은 특징이 있습니다.

모든 빌드 로그에 직접 액세스할 수 있습니다.
Cloud Build에 고유 기본 동시 실행 할당량이 있더라도 사전 설정된 빌드 시간 할당량이 없습니다.
Artifact Registry에 모두 저장되어 있는 현재 컨테이너 이미지 및 이전에 배포된 컨테이너 이미지를 볼 수 있습니다.
Cloud Storage는 프로젝트에서 함수의 소스 코드 디렉터리를 저장하는 데 사용됩니다. 다음에 유의하세요.
- Google Cloud CLI를 사용하여 함수를 만들면 소스 코드를 보관하는 업로드 버킷이 생성됩니다. 이 업로드 버킷 이름은 gcf-v2-uploads-PROJECT_NUMBER-REGION.cloudfunctions.appspot.com입니다.
- 코드가 업로드되면 함수 코드는 별도의 소스 버킷에 저장됩니다.
  - 기본 암호화를 사용하는 경우 이 버킷의 이름은 gcf-v2-sources-PROJECT_NUMBER-REGION입니다.
  - CMEK로 데이터를 보호하는 경우 버킷의 이름은 gcf-v2-sources-PROJECT_NUMBER-REGION-CMEK_KEY_HASH입니다.
- 소스 버킷과 업로드 버킷 모두 보관 기간이 없습니다.

빌드 프로세스 특성

빌드 프로세스에는 다음과 같은 특성이 있습니다.

프로젝트에 대해 Cloud Build API를 사용 설정해야 합니다.

API를 수동으로 사용 설정하려면 위 링크를 클릭하고 드롭다운 메뉴에서 프로젝트를 선택한 후 표시되는 메시지에 따라 UI를 사용 설정합니다.
전체 빌드 프로세스가 프로젝트의 컨텍스트 내에서 실행되기 때문에 포함된 리소스의 가격 책정에 따라 프로젝트에 영향을 줍니다.
- Cloud Build 가격 책정은 가격 책정 페이지를 참조하세요. 인스턴스가 사전 워밍되고 빠르게 제공되기 때문에 이 프로세스에는 Cloud Build의 기본 인스턴스 크기가 사용됩니다. Cloud Build는 무료 계층을 제공합니다. 자세한 내용은 가격 책정 문서를 참조하세요.
- Cloud Storage 가격 책정은 가격 책정 페이지를 참조하세요. Cloud Storage는 무료 등급을 제공합니다. 자세한 내용은 가격 책정 문서를 참조하세요.
- Artifact Registry 가격 책정은 가격 책정 페이지를 참조하세요.
빌드 프로세스가 결제 대상이 되므로 프로젝트에 Cloud Billing 계정이 연결되어 있어야 합니다.

빌드 이미지 로그 보기

사용자 프로젝트에서 빌드 이미지 프로세스가 갖는 주요 이점은 빌드 로그에 액세스할 수 있다는 것입니다. gcloud CLI 또는 Google Cloud 콘솔을 사용하여 Cloud Logging을 통해 제공되는 로그에 연결할 수 있습니다.

gcloud

gcloud functions deploy 명령어를 사용하여 함수를 배포합니다.

로그 URL은 터미널 창에 응답의 일부로 표시됩니다. 예를 들면 다음과 같습니다.

Deploying function (may take a while - up to 2 minutes)...⠹
**For Cloud Build Stackdriver Logs**, visit:
https://console.cloud.google.com/logs/viewer?project=&advancedFilter=resource.type%
3Dbuild%0Aresource.labels.build_id%3D38d5b662-2315-45dd-8aa2-
380d50d4f5e8%0AlogName%3Dprojects%2F%
2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.

Google Cloud 콘솔

Cloud Run 페이지에서 함수 로그를 보려면 다음 안내를 따르세요.

Cloud Run으로 이동
표시된 목록에서 선택한 함수를 클릭합니다.
로그 탭을 클릭하여 이 함수의 모든 버전에 대한 요청 로그와 컨테이너 로그를 가져옵니다. 로그 심각도 수준으로 필터링할 수 있습니다.

이미지 레지스트리

Artifact Registry는 함수 소스 코드에서 빌드된 이미지를 저장하는 데 사용됩니다. 이미지는 함수가 생성된 같은 프로젝트에 있는 REGION-docker.pkg.dev/PROJECT_ID/gcf-artifacts 저장소에 저장됩니다.

자체 관리 Artifact Registry 저장소를 지정하려면 다음 명령어를 실행합니다.

gcloud functions deploy FUNCTION_NAME \
   --docker-repository=REPOSITORY \
   [FLAGS...]

다음을 바꿉니다.

FUNCTION_NAME: 함수 이름입니다.
REPOSITORY: projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY 형식의 정규화된 Artifact Registry 저장소 이름입니다.

다른 프로젝트나 리전에 있는 Artifact Registry 저장소를 지정할 경우 추가 구성을 고려해야 할 수도 있습니다.

IAM 구성:

IAM 구성: 빌드 서비스 계정에 REPOSITORY를 읽고 쓸 수 있는 승인된 액세스 권한이 있는지 확인합니다.
네트워크 구성: 현재 프로젝트 구성에서 대상 REPOSITORY에 도달할 수 있는지 확인합니다.
VPC 서비스 제어 구성: 빌드 서비스 계정이 VPC-SC 경계 내의 대상 REPOSITORY에 도달할 수 있는지 확인합니다.
데이터 상주 제약 조건: 함수가 있는 리전과 다른 리전에서 REPOSITORY를 지정하면 리전 간에 데이터가 전송됩니다.

비공개 풀로 빌드 보호

npm 패키지와 같은 종속 항목을 함수에서 사용할 수 있도록 Cloud Build는 기본적으로 빌드 프로세스 중에 무제한 인터넷 액세스를 제공합니다. VPC 서비스 제어(VPC SC) 경계를 설정한 경우 경계 내부에 저장된 종속 항목으로만 빌드의 액세스를 제한하려면 Cloud Build 비공개 작업자 풀 기능을 사용하면 됩니다.

일반적으로 비공개 풀을 설정할 때는 다음 단계를 따릅니다.

비공개 작업자 풀을 만듭니다. 비공개 풀 만들기 및 관리를 참고하세요.
VPC 서비스 제어 경계를 구성합니다. VPC 서비스 제어 사용을 참조하세요.
비공개 작업자 풀이 함수와 다른 프로젝트에 있는 경우 Cloud Functions 서비스 에이전트 서비스 계정(service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com)에 cloudbuild.workerPoolUser 역할을 부여하여 Cloud Build 서비스가 작업자 풀에 액세스할 수 있도록 합니다.
```
gcloud projects add-iam-policy-binding PRIVATE_POOL_PROJECT_ID \
    --member serviceAccount:service-FUNCTION_PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com
    --role roles/cloudbuild.workerPoolUser
```
FUNCTION_PROJECT_NUMBER를 함수가 실행되는 프로젝트의 번호로, PRIVATE_POOL_PROJECT_ID를 작업자 풀이 있는 프로젝트의 ID로 바꿉니다. 자세한 내용은 비공개 풀에서 빌드 실행을 참조하세요.
비공개 풀을 사용하여 빌드할 함수를 배포합니다.
```
gcloud functions deploy FUNCTION_NAME \
   --runtime RUNTIME \
   --build-worker-pool PRIVATE_POOL_NAME
   [FLAGS...]
```
FUNCTION_NAME을 함수의 이름으로, RUNTIME을 사용 중인 런타임으로, PRIVATE_POOL_NAME을 풀의 이름으로 바꿉니다.

지정된 비공개 풀의 사용을 중지하고 대신 기본 Cloud Build 풀을 사용하려면 다시 배포할 때 --clear-build-worker-pool 플래그를 사용합니다.

gcloud functions deploy FUNCTION_NAME \
   --runtime RUNTIME \
   --clear-build-worker-pool
   [FLAGS...]

FUNCTION_NAME을 함수의 이름으로 바꾸고 RUNTIME을 사용 중인 런타임으로 바꿉니다.

커스텀 서비스 계정으로 빌드 보호

함수의 소스 코드는 컨테이너화하기 위해 Cloud Build로 전송됩니다. 컨테이너화된 함수는 Artifact Registry에 저장되고 서비스 형태로 Cloud Run에 배포됩니다. Cloud Run Functions는 Cloud Run 함수를 빌드하고 배포할 때 Cloud Build를 활용합니다. 기본적으로 Cloud Run Functions는 빌드를 수행할 때 기본 Cloud Build 서비스 계정을 주 구성원으로 사용합니다. 2024년 7월부터 Cloud Build가 새 프로젝트에서 서비스 계정을 사용하는 방법에 대한 기본 동작이 변경되었습니다. 이러한 변경사항으로 인해 처음으로 함수를 배포하는 새 프로젝트에서 함수 빌드를 위한 권한이 부족한 기본 Cloud Build 서비스 계정을 사용할 수 있습니다.

2024년 7월 전에 만든 Google Cloud 프로젝트의 경우 Cloud Build는 기존 Cloud Build 서비스 계정을 사용합니다. 이 서비스 계정은 사용자가 광범위한 사용 사례를 실행할 수 있도록 설계되어 프로젝트의 요구사항에 비해 지나치게 권한이 클 수 있습니다. 기존 프로젝트를 이 서비스 계정에서 이전하려면 다음 단계를 수행하여 함수 빌드 환경 보안을 더욱 강화하면 됩니다.

기존 Cloud Build 서비스 계정이 빌드에 사용되지 않도록 합니다.
기본 Compute 서비스 계정이 빌드에 사용되지 않도록 합니다.
빌드에 사용할 수 있는 적절한 범위의 권한으로 새 서비스 계정을 구성합니다.

기존 Cloud Build 서비스 계정이 빌드에 사용되지 않도록 방지

함수 빌드 세부정보를 검사하여 프로젝트에서 기존 Cloud Build 서비스 계정을 사용하고 있는지 확인할 수 있습니다. 기본 빌드 서비스 계정의 형식은 다음과 같습니다.

PROJECT_NUMBER@cloudbuild.gserviceaccount.com.

조직 정책 제약조건 cloudbuild.useBuildServiceAccount를 Not Enforced로 설정하여 이 서비스 계정을 강제로 사용하지 못하게 할 수 있습니다. 또는 모든 역할 부여를 제거하면 Google Cloud리소스에 액세스할 수 있는 기능이 제한됩니다.

기본 컴퓨팅 서비스 계정이 빌드에 사용되지 않도록 방지

기본 컴퓨팅 서비스 계정의 형식은 PROJECT_NUMBER-compute@developer.gserviceaccount.com입니다. 조직 정책 cloudbuild.useComputeServiceAccount를 Not Enforced로 설정하여 빌드에 사용되는 기본값으로 사용되지 않도록 할 수 있습니다. 또는 이 서비스 계정을 사용 중지하면 이 계정이 Google Cloud 리소스에 액세스하는 데 사용되지 않습니다.

함수 빌드용 서비스 계정 제공

함수를 배포할 때 함수 구성의 일부로 빌드 서비스 계정을 지정할 수 있습니다. 기존 Cloud Build 서비스 계정과 기본 Compute 서비스 계정이 빌드에 사용되지 않도록 차단된 경우 이 섹션에 설명된 대로 함수를 배포하려면 빌드 서비스 계정을 지정해야 합니다.

Cloud Build 서비스 계정 변경에 설명된 변경사항의 영향을 받는 경우 다음 중 하나를 수행할 수 있습니다.

기본 서비스 계정 변경에 대한 Cloud Build 안내를 검토하고 변경사항을 선택 해제합니다.
기본 Compute Engine 서비스 계정에 Cloud Build 계정 역할(roles/cloudbuild.builds.builder)을 추가합니다.
함수 배포를 위한 커스텀 Cloud Build 서비스 계정을 만듭니다.

Cloud Build가 함수를 빌드할 때 사용할 다른 서비스 계정을 제공해야 하는 상황은 다음과 같습니다.

VPC-SC 경계에 추가할 서비스 계정을 더 세부적으로 제어하려는 경우
각 권한을 개별적으로 취소하지 않고 Cloud Build를 기본 서비스 계정의 권한과 다른 권한으로 실행하려는 경우
다른 목적에 최적화된 Cloud Build 서비스 계정을 공유하지 않고 함수에 대한 세분화된 Cloud Build 권한을 설정하려는 경우
조직에서 기본 서비스 계정의 사용을 사용 중지한 경우

다음 섹션에서는 함수 배포를 위한 커스텀 Cloud Build 서비스 계정을 만드는 방법을 보여줍니다.

서비스 계정 만들기

서비스 계정 만들기의 설명대로 새 서비스 계정을 만듭니다.

권한 부여

사용하는 서비스 계정에 다음 역할이 필요합니다.

roles/logging.logWriter— Cloud Logging에서 빌드 로그를 저장하는 데 필요합니다.
roles/artifactregistry.writer— Artifact Registry에 빌드 이미지를 저장하는 데 필요합니다. 기본 동작의 경우 서비스 계정에 'gcf-artifacts' 및 'cloud-run-source-deploy'라는 저장소에 대한 액세스 권한이 필요합니다. 저장소의 IAM 정책에서 저장소에 대한 액세스 권한을 설정할 수 있습니다. dockerRepository 필드를 통해 자체 아티팩트 저장소를 제공할 수도 있습니다.
roles/storage.objectViewer - Cloud Storage 버킷에서 함수 소스를 검색하고 Container Registry에 빌드 이미지를 저장하는 데 필요합니다. 기본 동작의 경우 서비스 계정에 'run-sources-*', 'gcf-v2-sources-*', 'gcf-v2-uploads-*'라는 버킷에 대한 액세스 권한이 필요합니다. 이는 다음과 같은 IAM 조건을 역할 부여에 추가하여 수행할 수 있습니다. (resource.type == "storage.googleapis.com/Object" && (resource.name.startsWith("projects/_/buckets/gcf-v2-sources-") || resource.name.startsWith("projects/_/buckets/gcf-v2-uploads-") || resource.name.startsWith("projects/_/buckets/run-sources-")))

Google Cloud CLI를 사용하거나 Google Cloud 콘솔을 사용하여 다음 역할을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
    --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/artifactregistry.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/storage.objectViewer

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID
SA_EMAIL: 서비스 계정의 이메일 주소

VPC 서비스 제어 고려사항

프로젝트와 Cloud Run Functions API를 모두 보호하는 VPC 서비스 제어 경계가 있고 Compute Engine 기본 서비스 계정을 Cloud Run Functions의 Cloud Build 서비스 계정 역할로 사용하고 있다면 다음과 같은 인그레스 규칙을 만들어야 합니다.

Cloud Storage 및 Cloud Logging API의 모든 메서드에 대한 Compute Engine 기본 서비스 계정 인그레스를 허용합니다.
서비스 계정 service-[PROJECT_NUMBER]@gcf-admin-robot.iam.gserviceaccount.com의 Cloud Storage 및 Cloud Logging API의 모든 메서드에 대한 인그레스를 허용합니다.

커스텀 서비스 계정으로 함수 배포

함수를 배포할 때 Cloud Build에서 사용할 사용자가 만든 서비스 계정을 전달하려면 다음 gcloud 명령어를 실행합니다.

--build-service-account 플래그는 빌드 단계에 사용될 사용자 인증 정보를 보유한 IAM 서비스 계정을 지정합니다. 커스텀 서비스 계정이 제공되지 않으면 함수는 프로젝트의 기본 서비스 계정을 Cloud Build에 사용합니다.
필요한 경우 --build-worker-pool 플래그로 비공개 풀을 지정하여 사용할 수도 있습니다.


gcloud functions deploy FUNCTION_NAME \
   --gen2 \
   --region=REGION \
   --project=PROJECT_ID \
   --runtime=RUNTIME \
   --entry-point=CODE_ENTRYPOINT \
   --build-service-account=projects/PROJECT_ID/serviceAccounts/SA_EMAIL \
   --memory=256Mi \
   --trigger-http \
   --source=.

다음을 바꿉니다.

FUNCTION_NAME: 함수를 배포하는 데 사용한 이름
REGION: 함수를 배포할 Google Cloud 리전의 이름(예: us-west1)
PROJECT_ID: Google Cloud 프로젝트 ID
RUNTIME: 함수를 실행할 지원되는 런타임 버전의 런타임 ID(예: nodejs18)
CODE_ENTRYPOINT: 소스 코드에 있는 함수의 진입점. 이것은 함수가 실행될 때 수행되는 코드입니다.
SA_EMAIL: 서비스 계정의 이메일 주소

Cloud Build 서비스 계정에 VPC 서비스 제어 경계에 대한 액세스 권한 부여

Cloud Run Functions는 Cloud Build를 사용하여 소스 코드를 실행 가능한 컨테이너에 빌드합니다. VPC 서비스 제어와 함께 Cloud Run Functions를 사용하려면 서비스 경계에 액세스할 수 있도록 Cloud Build 서비스 계정(기본 또는 맞춤)을 구성해야 합니다.

서비스 계정 이름 찾기

기본 Cloud Build 서비스 계정을 사용하는 경우 이름은 다음과 같이 찾을 수 있습니다.

Google Cloud 콘솔의 IAM 페이지를 사용하여 Cloud Build 서비스 계정을 찾습니다.

Open IAM
프로젝트 드롭다운에 올바른 프로젝트가 표시되었는지 확인합니다.
cloudbuild.gserviceaccount.com을 검색합니다. PROJECT_NUMBER@cloudbuild.gserviceaccount.com 형식의 이메일 주소는 서비스 계정 이름입니다.

커스텀 Cloud Build 서비스 계정이 있는 경우 해당 이름을 대신 사용합니다.

서비스 계정에 서비스 경계에 대한 액세스 권한 부여

서비스 계정 이름이 있으면 사용자 또는 서비스 계정별 액세스 제한의 가이드에 따라 서비스 계정의 액세스 수준을 만듭니다. 그런 후 기존 경계에 액세스 수준 추가에 따라 서비스 경계에 액세스 수준을 추가합니다.