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

IAM으로 액세스 제어

이 페이지에서는 Identity and Access Management(IAM) 역할을 사용하여 프로젝트 수준에서 액세스 제어를 설정하고, gcloud functions 명령어 또는 Cloud Functions v2 API를 사용하여 만든 Google Cloud 프로젝트 및 함수에 대한 액세스 수준을 결정하는 데 필요한 추가 정보를 제공합니다.

Cloud Run을 사용하여 함수를 만들거나 배포한 경우 Cloud Run 사전 정의 역할, 개별 서비스에 대한 액세스 제어, 서비스 공개, Cloud Run 호출자 IAM의 조직 정책 구성에 관한 자세한 설명은 IAM으로 액세스 제어 및 Cloud Run 역할을 참조하세요.

사용자 액세스 제어

IAM을 사용하여 사용자를 프로젝트에 팀 구성원으로 추가하고 역할을 부여합니다.

Cloud Run Functions는 다음 역할을 지원합니다.

Cloud Run 사전 정의된 역할(추천)
Cloud Functions 사전 정의된 역할
편집자, 소유자, 뷰어의 기본 역할

서비스 계정에 대한 액세스 제어

서비스 계정은 특수한 유형의Google Cloud 계정으로, 데이터에 액세스하고 다양한 작업을 수행하도록 인증 및 승인되어야 하는 인간이 아닌 사용자의 ID 역할을 합니다. 이러한 계정 중 일부를 Google에서 직접 만들고 관리하며 이를 서비스 에이전트라고 합니다.

Cloud Run Functions에서 사용되는 서비스 계정은 다음과 같습니다.

이름	구성원 ID	역할
Compute Engine 기본 서비스 계정	`PROJECT_NUMBER-compute@developer.gserviceaccount.com`	편집자
Google Cloud Functions 서비스 에이전트	`service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com`	Google Cloud Functions 서비스 에이전트
기존 Cloud Build 서비스 계정¹	`PROJECT_NUMBER@cloudbuild.gserviceaccount.com`	Cloud Build 서비스 계정
Cloud Build 서비스 계정	`service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com`	Cloud Build 서비스 에이전트
Google Container Registry 서비스 에이전트	`service-PROJECT_NUMBER@containerregistry.iam.gserviceaccount.com`	Container Registry 서비스 에이전트
Artifact Registry 서비스 에이전트	`service-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com`	Artifact Registry 서비스 에이전트

참고:

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

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

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

런타임 서비스 계정

런타임 시 Cloud Run Functions는 기본적으로 프로젝트에 대한 편집자 역할도 있는 Compute Engine 기본 서비스 계정(PROJECT_NUMBER-compute@developer.gserviceaccount.com)을 사용합니다. 이러한 서비스 계정의 역할을 변경하여 실행 중인 함수에 대한 권한을 제한하거나 확장할 수 있습니다. 서비스 ID를 구성할 때 기본 서비스 계정을 사용하지 않도록 설정하여 사용되는 서비스 계정을 변경할 수도 있습니다.

서비스 계정에 대해 자세히 알아보려면 서비스 계정 문서를 참조하세요.

관리 서비스 계정

함수를 생성, 업데이트 또는 삭제하는 동안 프로젝트에서 관리 작업을 수행하려면 Cloud Run Functions의 모든 프로젝트에 Google Cloud Functions 서비스 에이전트 서비스 계정(service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com)이 필요합니다.

또한 모든 런타임은 프로젝트 내에서 컨테이너 이미지 빌드와 스토리지를 수행합니다. 이를 지원하려면 다음을 프로비저닝해야 합니다.

기존 Cloud Build 서비스 계정¹ (PROJECT_NUMBER@cloudbuild.gserviceaccount.com)
Cloud Build 서비스 에이전트 서비스 계정(service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com)
Google Container Registry 서비스 에이전트 서비스 계정(service-PROJECT_NUMBER@containerregistry.iam.gserviceaccount.com)

이러한 서비스 계정에는 이전 표에 나열된 역할이 있어야 합니다.

Google Cloud Functions 서비스 에이전트 서비스 계정

기본적으로 Google Cloud Functions 서비스 에이전트 서비스 계정(service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com)에는 프로젝트에 대한 cloudfunctions.serviceAgent 역할이 있습니다.

다음은 cloudfunctions.serviceAgent에서 사용하는 몇 가지 주요 권한입니다.

권한	설명
`roles/artifactregistry.admin`	Artifact Registry에서 저장소를 관리하고 빌드 이미지를 저장합니다.
`roles/cloudbuild.builds.editor`	사용자 프로젝트에서 빌드를 수행하기 위해 Cloud Build를 사용하는 데 필요합니다.
`roles/cloudbuild.customworkers.builder`	Cloud Build 커스텀 작업자에서 빌드를 만듭니다.
`compute.globalOperations.get`, `compute.networks.access`, `vpcaccess.connectors.{get, use}`	소비자 프로젝트 VPC에 액세스할 수 있는 함수를 프로비저닝합니다.
`roles/eventarc.developer`	함수의 Eventarc 트리거를 관리합니다.
`firebasedatabase.instances.{get, update}`	Firebase 실시간 데이터베이스에 의해 트리거된 함수를 생성합니다.
`iam.serviceAccounts.{actAs, getAccessToken, signBlob}`	런타임 서비스 계정 사용자 인증 정보를 가져옵니다.
`iam.serviceAccounts.getOpenIdToken`	에이전트가 사용자 지정 권한에 대한 OpenID 토큰을 가져오는 데 필요합니다. OpenID 토큰은 IAM이 사용 설정된 함수를 호출하는 데 사용됩니다.
`pubsub.subscriptions`	사용자 프로젝트의 구독을 관리합니다.
`pubsub.topics`	사용자 프로젝트의 주제를 관리합니다.
`roles/run.developer`	함수의 Cloud Run 서비스를 관리합니다.
`storage.buckets.create`, `storage.objects.{delete, get, create, list}`	사용자 프로젝트에 소스 코드를 저장하는 데 필요합니다.

사전 정의된 IAM 역할에서 또는 이 명령어를 실행하여 전체 권한 집합을 볼 수 있습니다.

gcloud iam roles describe roles/cloudfunctions.serviceAgent

현재 사용하는 서비스 역할을 제거하고 Cloud Functions 서비스 에이전트 역할을 추가하여 이 서비스 계정을 기본 역할로 재설정하세요.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com \
  --role roles/cloudfunctions.serviceAgent

권한 오류 문제해결

프로젝트에서 함수를 배포, 업데이트, 삭제 또는 실행 시에 권한 오류가 발생하면 다음 단계를 수행합니다.

프로젝트에 대한 편집자 또는 소유자 역할이 있는지 Cloud Functions 개발자 역할을 사용하고 있는지 확인합니다.

프로젝트 수준에서 Cloud Functions 개발자 역할을 사용하고 있다면 반드시 사용자에게 IAM 서비스 계정 사용자 역할을 부여해야 합니다.

현재 함수별 수준에서는 실행 권한만 허용됩니다.
Cloud Functions 서비스 에이전트 서비스 계정(service-PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com)에 프로젝트에 대한 Cloud Functions 서비스 에이전트(cloudfunctions.serviceAgent) 역할이 있는지 확인합니다.

이 계정을 표시하려면 Console IAM 페이지의 권한 탭에서 Google 제공 역할 부여 포함 체크박스를 선택합니다. gcloud projects add-iam-policy-binding PROJECT_ID를 사용할 수도 있습니다.
Pub/Sub 또는 Cloud Storage와 같은 트리거 소스에 권한이 있는지 확인합니다.

함수 실행 시 '권한 부족' 오류가 발생하거나 다른 인증 문제가 발생하는 경우, 런타임 서비스 계정에 함수에서 필요한 리소스에 액세스할 수 있는 올바른 권한이 있는지 확인합니다. 그런 다음 2단계와 3단계를 반복합니다.

배포 중에 '서비스를 사용할 수 없음' 오류가 발생하면 런타임 서비스 계정 PROJECT_ID@appspot.gserviceaccount.com이 프로젝트에 있는지 확인합니다. 서비스 계정이 삭제된 경우 이를 다시 만들려면 서비스 계정 삭제 취소를 참조하세요.

Cloud Run Functions 문제 해결도 참조하세요.

¹ Cloud Run Functions는 2024년 7월 전에 생성된 프로젝트에만 기존 Cloud Build 서비스 계정을 사용합니다.