서비스 ID 소개

이 페이지에서는 Cloud Run ID 2개와 Cloud 클라이언트 라이브러리에서 서비스 ID를 사용하여 Google Cloud API를 호출하는 방법을 설명합니다. Cloud 클라이언트 라이브러리가 있는 Google Cloud 제품의 예로는 Cloud Storage, Firestore, Cloud SQL, Pub/Sub, Cloud Tasks가 있습니다. 이 페이지는 조직 정책과 사용자 액세스를 관리하는 관리자, 운영자 또는 개발자나 이러한 주제를 알아보려는 사용자를 대상으로 합니다.

Cloud Run ID

Cloud Run을 사용하려면 Google Cloud에 Cloud Run 사용자와 Cloud Run 인스턴스가 있고 각각에 ID가 있어야 합니다.

  • Cloud Run 사용자 ID를 Cloud Run 배포자 계정이라고 합니다. 버전이나 작업을 관리할 때는 이 ID를 사용하여 Cloud Run Admin API에 요청을 보냅니다.
  • Cloud Run 인스턴스 ID를 Cloud Run 서비스 ID라고 합니다. 작성한 Cloud Run 코드가 Cloud 클라이언트 라이브러리와 상호작용하거나 서비스 간 통신을 위해 다른 Cloud Run 서비스를 호출할 때, 이 ID를 사용하여 Cloud Run에서 Google Cloud API 또는 기타 Cloud Run 서비스로 요청을 실행합니다.

Google Cloud API에 액세스하여 요청하거나 서비스 간에 통신하려면 Identity and Access Management(IAM)에서 각 ID에 적절한 권한을 부여해야 합니다.

배포자 계정으로 Cloud Run Admin API 호출

Cloud Run 배포자 계정을 사용하여 Cloud Run에서 Cloud Run Admin API를 호출할 수 있습니다. 배포자 계정은 사용자 계정이나 서비스 계정일 수 있으며 Google Cloud 환경에 로그인한 계정을 나타냅니다.

배포자 계정에서 Cloud Run을 사용하는 경우 IAM은 배포자 계정에 Cloud Run 작업을 수행하는 데 필요한 권한이 있는지 확인합니다. 다음 다이어그램에서는 사용자 계정이 Cloud Run Admin API를 호출하여 Google Cloud 콘솔에서 새 버전을 배포하는 방법을 보여줍니다.

Google Cloud 콘솔에서 Cloud Run Admin API를 호출합니다.
그림 1. 사용자는 Google Cloud 콘솔을 사용하여 액세스 토큰이 포함된 요청을 Cloud Run Admin API에 전송해 새 버전을 배포합니다. IAM은 이 액세스 토큰을 사용하여 작업을 수행하기 전에 사용자 계정이 Cloud Run Admin API에 액세스할 수 있도록 인증되었는지 확인합니다.

서비스 ID로 Google Cloud API 호출

Cloud Run 인스턴스가 IAM 인증을 받은 다른 Cloud Run 서비스와 상호작용하거나 애플리케이션 코드 또는 내장 기능(예: Cloud Run 통합 또는 Cloud Storage 볼륨 마운트)을 통해 Cloud 클라이언트 라이브러리를 호출하는 경우, Google Cloud 환경에서는 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 Cloud Run 서비스 ID가 API 작업을 수행하도록 인증을 받았는지를 자동으로 감지합니다. Cloud Run 서비스 ID는 버전을 배포하거나 작업을 실행할 때 Cloud Run 인스턴스 ID로 할당된 서비스 계정입니다.

배포자 계정으로 사용되는 서비스 계정은 Cloud Run 구성에서 같은 서비스 계정을 구성하는 경우에만 서비스 ID로 사용됩니다.

이 가이드의 나머지 부분에서는 Cloud Run 서비스나 작업에서 서비스 ID를 사용하여 Google 서비스와 API를 호출하고 액세스하는 방법을 설명합니다. 서비스 ID 구성 방법에 대한 자세한 내용은 서비스 및 작업의 서비스 ID 구성 페이지를 참조하세요.

서비스 ID의 서비스 계정 유형

Cloud Run 인스턴스에서 필요한 작업을 수행하기 위해 Google Cloud APIs를 호출하면 Cloud Run은 자동으로 서비스 계정을 서비스 ID로 사용합니다. 서비스 ID로 사용할 수 있는 두 가지 유형의 서비스 계정은 다음과 같습니다.

  • 사용자 관리형 서비스 계정(권장): 이 서비스 계정을 수동으로 만들고 서비스 계정에서 특정 Google Cloud 리소스에 액세스하는 데 필요한 최소한의 권한 집합을 결정합니다. 사용자 관리형 서비스 계정은 SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com 형식을 따릅니다.
  • Compute Engine 기본 서비스 계정: Cloud Run은 자동으로 Compute Engine 기본 서비스 계정을 기본 서비스 ID로 제공합니다. Compute Engine 기본 서비스 계정은 PROJECT_NUMBER-compute@developer.gserviceaccount.com 형식을 따릅니다.

서비스 ID 구성 시 기본 서비스 계정 사용 안함

기본적으로 Compute Engine 기본 서비스 계정은 자동으로 생성됩니다. Cloud Run 서비스이나 작업을 만들 때 서비스 계정을 지정하지 않으면 Cloud Run에서 이 서비스 계정을 사용합니다.

조직 정책 구성에 따라 프로젝트에 대한 편집자 역할이 기본 서비스 계정에 자동으로 부여될 수 있습니다. iam.automaticIamGrantsForDefaultServiceAccounts 조직 정책 제약조건을 적용하여 자동 역할 부여를 중지하는 것이 좋습니다. 2024년 5월 3일 이후에 조직을 만든 경우 기본적으로 이 제약조건이 적용됩니다.

자동 역할 부여를 중지한 경우 기본 서비스 계정에 부여할 역할을 결정한 후 직접 이러한 역할을 부여해야 합니다.

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

서비스 ID 작동 방식

코드에서 Cloud 클라이언트 라이브러리를 호출하거나 요청을 Cloud 클라이언트 라이브러리로 보내면 다음이 발생합니다.

  1. 클라이언트 라이브러리는 요청이 Google Cloud API 또는 Cloud 클라이언트 라이브러리로 보내졌는지 감지하고 인스턴스 메타데이터 서버에서 서비스 ID에 대한 OAuth 2.0 액세스 토큰을 요청합니다.
  2. 인스턴스 메타데이터 서버는 서비스 ID로 구성된 서비스 계정에 대한 IAM 액세스 토큰을 제공합니다.
  3. Google Cloud API에 대한 요청은 OAuth 2.0 액세스 토큰과 함께 전송됩니다.
  4. IAM은 필요한 권한에 대해 액세스 토큰에서 참조되는 서비스 ID를 확인하고 호출을 API 엔드포인트로 전달하기 전에 정책 바인딩을 확인합니다.
  5. Google Cloud API에서 작업을 수행합니다.
Cloud Run에서 Google Cloud API를 호출합니다.
그림 1. Cloud Run은 메타데이터 서버에서 액세스 토큰을 생성하고 IAM은 이 액세스 토큰을 사용하여 할당된 Cloud Run 서비스 ID가 Google Cloud API에 액세스할 수 있도록 인증되었는지 확인합니다.

Cloud Run 요청의 액세스 토큰을 생성하여 Google Cloud API 호출

Cloud Run 코드에서 Cloud 클라이언트 라이브러리를 사용하는 경우 배포나 실행 시 서비스 계정을 할당하여 Cloud Run에서 서비스 ID를 구성합니다. 이렇게 하면 라이브러리에서 액세스 토큰을 자동으로 획득하여 코드 요청을 인증할 수 있습니다. Cloud Run 코드가 인증된 다른 Cloud Run 서비스와 통신하는 경우, 요청에 액세스 토큰을 추가해야 합니다.

서비스 계정을 서비스 ID로 할당하려면 다음 가이드를 참조하세요.

하지만 고유한 커스텀 코드를 사용하거나 프로그래매틱 방식으로 요청을 보내야 하는 경우에는 직접 메타데이터 서버를 사용하여 다음 섹션에 설명된 ID 토큰과 액세스 토큰을 수동으로 가져올 수 있습니다. Google Cloud에서 실행되는 워크로드에만 메타데이터 서버를 사용할 수 있으므로 로컬 머신에서 이 서버를 직접 쿼리할 수 없습니다.

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

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

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

토큰을 가져오려면 사용 중인 토큰 유형에 적합한 탭의 안내를 따르세요.

액세스 토큰

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

  1. Compute 메타데이터 서버를 사용하여 액세스 토큰을 가져옵니다.

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    --header "Metadata-Flavor: Google"

    이 엔드포인트는 access_token 속성과 함께 JSON 응답을 반환합니다.

  2. 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

다음 단계