서비스 ID

모든 Cloud Run 버전이나 작업이 서비스 계정에 연결됩니다. 이 서비스 계정은 Google Cloud API에 인증을 수행하기 위해 Google Cloud 클라이언트 라이브러리에서 자동으로 사용됩니다. 서비스 코드에 사용될 수 있는 Google Cloud API 예시에는 Cloud Storage, Firestore, Cloud SQL, Pub/Sub, Cloud Tasks가 포함됩니다.

서비스 계정을 지정하지 않으면 Cloud Run이 모든 Google Cloud API에서 포괄적인 권한이 있는 기본 서비스 계정에 버전 또는 작업을 연결합니다. Google에서는 대신 서비스별 ID를 사용하고 선택적인 권한을 부여하는 방식이 권장됩니다.

기본 서비스 계정 정보

기본적으로 Cloud Run 버전과 작업은 Compute Engine 기본 서비스 계정으로 실행됩니다. Compute Engine 기본 서비스 계정에는 Google Cloud 프로젝트의 모든 리소스에 대한 읽기 및 쓰기 권한을 부여하는 프로젝트 편집자 IAM 역할이 있습니다.

이는 기본 서비스 계정을 사용하는 것보다 편리할 수 있지만 가장 세분화된 권한이 포함된 자신만의 사용자 관리형 서비스 계정을 만들고 이 서비스 계정을 Cloud Run 서비스 또는 작업 ID로 할당하는 것이 좋습니다. 이 문서에서는 Cloud Run으로 서비스별 ID를 구성하는 방법을 설명합니다.

서비스별 ID 사용

기본 서비스 계정을 사용하는 대신 사용자 관리형 서비스 계정에 전용 ID를 할당하여 모든 Cloud Run 서비스 또는 작업에 전용 ID를 제공하는 것이 좋습니다. 사용자 관리 서비스 계정을 사용하면 Identity and Access Management를 사용하여 최소한의 권한 집합을 부여하는 방식으로 액세스를 제어할 수 있습니다.

Google Cloud CLI 및 Google Cloud 클라이언트 라이브러리는 자신이 Google Cloud에서 실행 중인 때를 자동으로 감지하여 현재 Cloud Run 버전의 런타임 서비스 계정을 사용합니다. 즉, 코드가 gcloud CLI 또는 공식 Google Cloud 클라이언트 라이브러리를 사용하는 경우 해당 코드는 자동으로 Cloud Run 서비스의 런타임 서비스 계정으로 감지되고 인증됩니다. 이 전략을 애플리케이션 기본 사용자 인증 정보라고 하며 이 방식을 사용하면 코드를 여러 환경에 걸쳐 이동할 수 있습니다.

서비스별 ID를 할당하는 두 가지 측면은 다음과 같습니다.

서비스별 ID를 할당하는 데 필요한 권한
할당된 ID 자체가 작동하는 데 필요한 권한

사용자 관리 서비스 계정을 할당하는 데 필요한 권한

사용자 관리형 서비스 계정을 사용하여 Cloud Run 서비스를 배포하려면 해당 서비스 계정을 가장(iam.serviceAccounts.actAs)할 수 있는 권한이 있어야 합니다. 이 권한은 roles/iam.serviceAccountUser IAM 역할을 통해 부여할 수 있습니다. 사용자 관리형 서비스 계정으로서 Cloud Run 서비스를 배포할 수 있으려면 모든 주 구성원(예: 사용자, 서비스 계정)에게 사용자 관리형 서비스 계정에 대해 이 권한이 있어야 합니다.

Google Cloud 콘솔, API(YAML) 또는 gcloud CLI를 사용하여 이 권한을 부여할 수 있습니다.

gcloud iam service-accounts add-iam-policy-binding "SERVICE_ACCOUNT_EMAIL" \
    --member "PRINCIPAL" \
    --role "roles/iam.serviceAccountUser"

다음과 같이 바꿉니다.

SERVICE_ACCOUNT_EMAIL: 서비스 계정 이메일 주소(예: PROJECT_NUMBER-compute@developer.gserviceaccount.com)
PRINCIPAL: 바인딩을 추가할 주 구성원. user:email 형식을 사용합니다(예: user:test-user@gmail.com).

권한을 부여하는 방법을 알아보려면 리소스에 대한 액세스 권한 부여, 변경, 취소를 참조하세요.

사용자 관리형 서비스 계정으로 새 서비스 배포

사용자 관리형 서비스 계정이 아직 없으면 먼저 서비스 계정을 만듭니다.

새 서비스를 만들거나 새 버전을 배포할 때 Google Cloud 콘솔, gcloud CLI, API(YAML)를 사용하여 Cloud Run 서비스의 서비스 계정을 설정할 수 있습니다.

콘솔

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

Cloud Run으로 이동
배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 후 새 버전 수정 및 배포를 클릭합니다.
새 서비스를 구성하는 경우 원하는 대로 초기 서비스 설정 페이지를 작성한 후 컨테이너, 볼륨, 네트워킹, 보안을 클릭하여 서비스 구성 페이지를 펼칩니다.
보안 탭을 클릭합니다.
- 서비스 계정 드롭다운을 클릭하고 원하는 서비스 계정을 선택합니다.
만들기 또는 배포를 클릭합니다.

gcloud

다음 명령어로 기존 서비스를 업데이트하여 새 런타임 서비스 계정을 만들 수 있습니다.

gcloud run services update SERVICE --service-account SERVICE_ACCOUNT

다음과 같이 바꿉니다.

SERVICE를 서비스 이름으로 바꿉니다.
SERVICE_ACCOUNT를 새 ID와 연결된 서비스 계정으로 바꿉니다. 이 값은 서비스 계정의 이메일 주소입니다(예를 들어 example@myproject.iam.gserviceaccount.com).

배포 중에 다음 명령어를 사용하여 서비스 계정을 설정할 수도 있습니다.

gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT

다음과 같이 바꿉니다.

IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
SERVICE_ACCOUNT를 새 ID와 연결된 서비스 계정으로 바꿉니다. 이 값은 서비스 계정의 이메일 주소입니다(예를 들어 example@myservice.iam.gserviceaccount.com).

YAML

YAML 형식으로 정리된 결과를 생성하는 gcloud run services describe --format export 명령어를 사용하면 기존 서비스 구성을 다운로드해서 볼 수 있습니다. 그런 다음 아래 설명된 필드를 수정하고 gcloud run services replace 명령어를 사용하여 수정된 YAML을 업로드할 수 있습니다. 설명된 대로 필드만 수정해야 합니다.

구성을 보고 다운로드하려면 다음을 실행합니다.

gcloud run services describe SERVICE --format export > service.yaml

serviceAccountName: 속성을 업데이트합니다.
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      serviceAccountName: SERVICE_ACCOUNT
```
다음과 같이 바꿉니다.
- SERVICE를 Cloud Run 서비스 이름으로 바꿉니다.
- SERVICE_ACCOUNT를 새 ID와 연결된 서비스 계정으로 바꿉니다. 이 값은 서비스 계정의 이메일 주소입니다(예를 들어 example@myproject.iam.gserviceaccount.com).
다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.
```
gcloud run services replace service.yaml
```

Terraform

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.

서비스 계정을 만들려면 기존 main.tf 파일에 다음 리소스를 추가합니다.

resource "google_service_account" "cloudrun_service_identity" {
  account_id = "my-service-account"
}

Cloud Run 서비스를 만들거나 업데이트하고 서비스 계정을 포함합니다.

resource "google_cloud_run_v2_service" "default" {
  name     = "cloud-run-srv"
  location = "us-central1"

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.cloudrun_service_identity.email
  }
}

다른 프로젝트에서 서비스 계정 사용

또한 Cloud Run 서비스가 아닌 다른 Google Cloud 프로젝트에 있는 사용자 관리형 서비스 계정을 사용할 수도 있습니다. 서비스 계정과 Cloud Run 서비스가 서로 다른 프로젝트에 있는 경우:

이 서비스 계정이 포함된 프로젝트의 경우 조직 정책 iam.disableCrossProjectServiceAccountUsage를 폴더 수준에서 false/unenforced로 설정하거나 프로젝트 수준 설정에서 상속해야 합니다. 기본적으로 true로 설정됩니다.
서비스 계정에는 배포 프로젝트의 서비스 에이전트의 roles/iam.serviceAccountTokenCreator에 대한 역할 멤버십이 필요합니다.
```
service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com
```
여기서 PROJECT_NUMBER는 프로젝트의 프로젝트 번호입니다.
서비스 계정에는 배포 작업을 수행하는 ID(사용자 또는 자동화)의 roles/iam.serviceAccountUser에 대한 역할 멤버십이 필요합니다.

역할 멤버십을 서비스 계정 리소스에 직접 적용하거나 리소스 계층 구조의 상위 수준에서 상속받을 수 있습니다.

사용자 관리 서비스 계정에서 Cloud Run을 작동하는 데 필요한 권한

Cloud Run 서비스가 Google Cloud의 다른 부분에 액세스하지 않는 경우 해당 서비스 계정에 역할 또는 권한을 부여할 필요가 없습니다.

Google Cloud Console에서 새 서비스 계정을 만들 때 추가 액세스 권한에 선택적 단계 '이 서비스 계정에 프로젝트에 대한 액세스 권한 부여'가 필요합니다. 예를 들어 Cloud Run 서비스 하나에서 다른 비공개 Cloud Run 서비스를 호출하거나 Cloud SQL 데이터베이스에 액세스할 수 있으며 특정 IAM 역할에 둘 다 필요합니다. 자세한 내용은 액세스 관리 문서를 참조하세요.

메타데이터 서버를 사용하여 ID 및 액세스 토큰 가져오기

Cloud Run 서비스 코드가 Google Cloud 클라이언트 라이브러리를 사용하는 경우 라이브러리는 서비스의 런타임 서비스 계정을 사용하여 코드 요청을 인증하기 위해 액세스 토큰을 자동으로 가져옵니다.

대신 자체 커스텀 코드를 사용하는 경우 메타데이터 서버를 사용하여 액세스 토큰과 ID 토큰을 수동으로 가져올 수 있습니다. Google Cloud에서 실행되는 워크로드에만 메타데이터 서버를 사용할 수 있으므로 로컬 머신에서 이 서버를 직접 쿼리할 수 없습니다.

메타데이터 서버로 가져올 수 있는 두 가지 토큰 유형은 다음과 같습니다.

대부분의 Google API를 호출하는 데 사용되는 OAuth 2.0 액세스 토큰
다른 Cloud Run 서비스 또는 Cloud Functions를 호출하거나 ID 토큰 검증을 위해 서비스를 호출하는 데 사용되는 ID 토큰

토큰을 가져오려면 다음 옵션 중 하나를 선택합니다.

액세스 토큰

예를 들어 Pub/Sub 주제를 만들려면 projects.topics.create 메서드를 사용합니다.

Compute 메타데이터 서버를 사용하여 액세스 토큰을 가져옵니다.
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    --header "Metadata-Flavor: Google"
```
이 엔드포인트는 access_token 속성과 함께 JSON 응답을 반환합니다.
HTTP/프로토콜 요청에서 요청은 Authorization 헤더의 액세스 토큰으로 인증되어야 합니다.
```
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
```
각 항목의 의미는 다음과 같습니다.
- PROJECT_ID는 프로젝트 ID입니다.
- TOPIC_ID는 주제 ID입니다.
- ACCESS_TOKEN은 이전 단계에서 가져온 액세스 토큰입니다.
응답:
```
{
    "name": "projects/PROJECT_ID/topics/TOPIC_ID"
}
```

ID 토큰

Compute 메타데이터 서버를 사용하여 특정 수신자가 있는 ID 토큰을 가져옵니다.

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE" \
    --header "Metadata-Flavor: Google"

여기서 AUDIENCE는 요청된 JWT 수신자입니다.

Cloud Run 서비스의 경우 대상은 호출 중인 서비스의 URL 또는 서비스에 구성된 커스텀 도메인과 같은 커스텀 대상이어야 합니다.

https://service.domain.com

다른 리소스의 경우 IAP로 보호되는 리소스의 OAuth 클라이언트 ID일 수 있습니다.

1234567890.apps.googleusercontent.com

전용 서비스 계정 생성을 위한 추천 받기

추천자 서비스는 필요한 최소한의 권한 집합이 포함된 전용 서비스 계정을 만들 수 있도록 권장사항을 자동으로 제공합니다.

다음 단계

서비스에 대한 액세스를 관리하거나 안전하게 개발자, 서비스, 최종 사용자를 인증하는 방법을 알아보세요.

보안 위험을 최소화하기 위해 서비스 ID를 사용하는 애플리케이션을 전반적으로 둘러보려면 Cloud Run 서비스 보안 튜토리얼을 참조하세요.