소비자 정책 관리

프리뷰 - Hierarchical service activation

이 기능에는 서비스별 약관이 적용됩니다. 정식 버전(GA) 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

계층적 서비스 활성화를 사용하면 Google Cloud 리소스 계층 구조를 통해 상속되는 서비스 사용 설정을 관리할 수 있습니다. 자세한 내용은 개요를 참고하세요.

ConsumerPolicy은Google Cloud 리소스 계층 구조의 각 수준에 있는 Service Usage API 리소스입니다. 이 리소스는 항상 default라는 이름이 지정되며 사용 설정된 서비스를 정의하는 enableRules이 포함되어 있습니다. 특정 서비스를 사용 설정 또는 사용 중지하는 대신 ConsumerPolicy 리소스를 수정할 수 있습니다. 서비스 이름이 목록에 있으면 해당 계층 수준에서 서비스가 사용 설정됩니다.

이 문서에서는 Google Cloud CLI를 사용하여 프로젝트, 폴더, 조직의 소비자 정책을 관리하는 방법을 보여줍니다.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우 필요한 권한이 이미 있습니다.

Verify that billing is enabled for your Google Cloud project.

Enable the Service Usage API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable serviceusage.googleapis.com

Install the Google Cloud CLI.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우 필요한 권한이 이미 있습니다.

Verify that billing is enabled for your Google Cloud project.

Enable the Service Usage API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable serviceusage.googleapis.com

1. 관리할 Google Cloud 리소스를 표시하지 않으면 이 문서의 명령어는 기본적으로 현재 프로젝트를 사용합니다. 예를 들어 gcloud beta services policies get --policy-name=default는 현재 프로젝트의 소비자 정책을 반환합니다.

   다음과 같이 현재 프로젝트 ID를 가져올 수 있습니다.

   gcloud config list --format='text(core.project)'

필요한 역할

소비자 정책을 관리하는 데 필요한 권한을 얻으려면 관리자에게 타겟 리소스에 대한 서비스 사용량 관리자 (roles/serviceusage.serviceUsageAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 소비자 정책을 관리하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

소비자 정책을 관리하려면 다음 권한이 필요합니다.

• 소비자 정책 가져오기: serviceusage.consumerpolicy.get
• 소비자 정책을 업데이트합니다.
  • serviceusage.consumerpolicy.analyze
  • serviceusage.consumerpolicy.update
• 유효 정책 가져오기: serviceusage.effectivepolicy.get
• 서비스가 사용 설정되어 있는지 확인합니다. serviceusage.values.test

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

소비자 정책 가져오기

gcloud beta services policies get 명령어를 사용하여 프로젝트, 폴더 또는 조직의 ConsumerPolicy을 가져올 수 있습니다.

이 명령어는 상속된 규칙이 아닌 정확한 리소스 수준에서 설정된 enableRules를 반환합니다. 상속된 규칙을 포함하는 전체 보기를 보려면 유효 정책을 검색하세요. default 정책 이름만 지원됩니다.

프로젝트

gcloud beta services policies get --policy-name=default \
    --project=PROJECT_ID \
    --output-file=OUTPUT_FILE

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID 또는 플래그를 생략하여 현재 프로젝트를 기본값으로 설정합니다.
• OUTPUT_FILE: (선택사항) 소비자 정책의 콘텐츠를 저장할 수 있는 출력 파일의 경로입니다. 지원되는 파일 형식은 JSON 및 YAML입니다.

폴더

gcloud beta services policies get --policy-name=default \
    --folder=FOLDER_ID \
    --output-file=OUTPUT_FILE

다음을 바꿉니다.

• FOLDER_ID: Google Cloud 폴더 ID
• OUTPUT_FILE: (선택사항) 소비자 정책의 콘텐츠를 저장할 수 있는 출력 파일의 경로입니다. 지원되는 파일 형식은 JSON 및 YAML입니다.

조직

gcloud beta services policies get --policy-name=default \
    --organization=ORGANIZATION_ID \
    --output-file=OUTPUT_FILE

다음을 바꿉니다.

• ORGANIZATION_ID: Google Cloud 조직 리소스 ID입니다.
• OUTPUT_FILE: (선택사항) 소비자 정책의 콘텐츠를 저장할 수 있는 출력 파일의 경로입니다. 지원되는 파일 형식은 JSON 및 YAML입니다.

소비자 정책 업데이트

gcloud beta services policies update 명령어를 사용하여 ConsumerPolicy를 업데이트할 수 있습니다. 이렇게 하면 현재 정책을 대체하고 YAML 파일을 사용하여 사용 설정된 여러 서비스를 한 번에 업데이트할 수 있습니다.

이 명령어는 서비스 종속 항목을 자동으로 사용 설정하지 않습니다. 입력 파일에 모든 서비스 종속 항목을 명시적으로 나열해야 합니다. --validate-only 플래그를 사용하여 변경사항을 적용하기 전에 미리 볼 수 있습니다.

gcloud beta services policies update --consumer-policy-file=PATH_TO_CONSUMER_POLICY

PATH_TO_CONSUMER_POLICY을 소비자 정책이 포함된 YAML 파일의 경로로 바꿉니다. 예를 들면 다음과 같습니다.

gcloud beta services policies update --consumer-policy-file=/path/to/the/file.yaml

지원되는 플래그:

• --bypass-api-usage-check를 사용하여 사용량 확인을 우회합니다. 그렇지 않으면 사용 중지하려는 서비스가 지난 30일 동안 사용되었거나 지난 3일 동안 사용 설정된 경우 시스템에서 오류를 반환합니다.

• --bypass-dependency-check를 사용하여 종속 항목 검사를 우회합니다. 서비스를 추가할 때는 모든 서비스 종속 항목이 정책에 있어야 합니다. 서비스를 삭제할 때는 정책의 다른 서비스가 해당 서비스에 종속될 수 없습니다. 그렇지 않으면 업데이트가 성공하지 못하고 오류가 반환됩니다.

• --validate-only를 사용하여 실제로 작업을 실행하지 않고 업데이트를 검증합니다.

다음에 유의하세요.

• 정책 파일의 YAML 템플릿을 가져오려면 먼저 소비자 정책을 가져오고 --output-file 플래그를 사용하여 정책을 파일에 저장합니다. 그런 다음 이 파일을 수정하고 업데이트 명령어의 입력으로 사용합니다. 샘플 템플릿:

  name: projects/PROJECT_ID/consumerPolicies/default
  enableRules:
    services:
      - services/SERVICE
      - ...
      - ...
  

  다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID 지원되는 기타 리소스 이름도 유사한 형식을 따릅니다(예: folders/FOLDER_ID/consumerPolicies/default).

  • SERVICE: 서비스 이름입니다(예: bigquery.googleapis.com).

유효 정책 가져오기

gcloud beta services policies get-effective 명령어를 사용하여 리소스의 유효 정책을 검색할 수 있습니다.

유효 정책은 리소스의 ConsumerPolicy와 모든 상위 항목의 정책을 결합합니다. 이렇게 하면 리소스에서 직접 사용 설정된 서비스와 상위 항목에서 상속된 서비스를 비롯하여 사용 설정된 모든 서비스를 완전히 파악할 수 있습니다.

프로젝트

gcloud beta services policies get-effective --project=PROJECT_ID \
    --view=VIEW

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID 또는 플래그를 생략하여 현재 프로젝트를 기본값으로 설정합니다.
• VIEW: 제한된 메타데이터 집합을 가져오려면 BASIC, 계층 구조에서 각 서비스가 사용 설정된 위치를 포함한 전체 메타데이터 집합을 가져오려면 FULL 기본값은 BASIC입니다.

폴더

gcloud beta services policies get-effective --folder=FOLDER_ID \
    --view=VIEW

다음을 바꿉니다.

• FOLDER_ID: Google Cloud 폴더 ID
• VIEW: 제한된 메타데이터 집합을 가져오려면 BASIC, 계층 구조에서 각 서비스가 사용 설정된 위치를 포함한 전체 메타데이터 집합을 가져오려면 FULL 기본값은 BASIC입니다.

조직

gcloud beta services policies get-effective --organization=ORGANIZATION_ID \
    --view=VIEW

다음을 바꿉니다.

• ORGANIZATION_ID: Google Cloud 조직 리소스 ID입니다.
• VIEW: 제한된 메타데이터 집합을 가져오려면 BASIC, 계층 구조에서 각 서비스가 사용 설정된 위치를 포함한 전체 메타데이터 집합을 가져오려면 FULL 기본값은 BASIC입니다.

서비스가 사용 설정되어 있는지 확인

gcloud beta services policies test-enabled 명령어를 사용하여 리소스에서 서비스가 사용 설정되었는지 확인할 수 있습니다.

서비스 상태를 확인할 때 이 명령어는 유효한 정책과 전체 Google Cloud 리소스 계층 구조를 고려합니다.

프로젝트

gcloud beta services policies test-enabled SERVICE \
    --project=PROJECT_ID

다음을 바꿉니다.

• SERVICE: 확인할 서비스의 이름입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID 또는 플래그를 생략하여 현재 프로젝트를 기본값으로 설정합니다.

폴더

gcloud beta services policies test-enabled SERVICE \
    --folder=FOLDER_ID

다음을 바꿉니다.

• SERVICE: 확인할 서비스의 이름입니다.
• FOLDER_ID: Google Cloud 폴더 ID

조직

gcloud beta services policies test-enabled SERVICE \
    --organization=ORGANIZATION_ID

다음을 바꿉니다.

• SERVICE: 확인할 서비스의 이름입니다.
• ORGANIZATION_ID: Google Cloud 조직 리소스 ID입니다.

예시

소비자 정책 가져오기

• 현재 프로젝트의 소비자 정책 가져오기:

  gcloud beta services policies get

  출력:

  name: projects/PROJECT_ID/consumerPolicies/default
  enableRules:
   services:
    - services/apikeys.googleapis.com
    - services/compute.googleapis.com
    - services/oslogin.googleapis.com
    - services/serviceusage.googleapis.com
  updateTime: 2025-09-11T23:05:22.758394Z
  createTime: 2025-01-31T20:17:37.272343Z
  etag: W/"W9nsVJK0V1m7ee7tM7pFDg=="

소비자 정책 업데이트

• 소비자 정책 업데이트 성공:

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

  출력:

  Operation [operations/ucpat.p39-581601899707-86fe7e37-c7f9-4624-90c4-d54754d57eed] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"1970-01-01T00:00:00Z",
      "enableRules":[
          {
              "services":[
                  "services/apikeys.googleapis.com"
              ]
          }
      ],
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"1970-01-01T00:00:00Z"
  }

• 소비자 정책을 업데이트할 수 없음:

  gcloud beta services policies update --consumer-policy-file=/tmp/test.json

  오류 메시지:

  ERROR: (gcloud.beta.services.policies.update) Invalid consumer_policy_file format. Please provide path to a yaml file.

• 서비스가 최근에 사용되었거나 사용 설정된 경우 소비자 정책을 업데이트하려고 시도:

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

  출력:

  The operation "operations/ucpat.p39-581601899707-4884bdb0-d899-49ac-9c83-38457950ef33" resulted in a failure "The services apikeys.googleapis.com have usage in the last 30 days or were enabled in the past 3 days. Please specify force if you want to proceed with the destructive policy change. Help Token: AVSZLmtCfGwMm4oHmOyExdDEFRQ0pFiBrl879nbZlY2JkfVzeU63u66ApXYr6MIEAoig..."

• 사용 확인을 우회하여 서비스가 최근에 사용되거나 사용 설정된 경우 소비자 정책 업데이트:

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml --bypass-api-usage-check

  출력:

  Operation [operations/ucpat.p39-581601899707-8ffda670-ed04-4776-8d43-d2f8e1817e00] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"1970-01-01T00:00:00Z",
      "enableRules":[
          {
              "services":[
                  "services/serviceusage.googleapis.com"
              ]
          }
      ],
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"1970-01-01T00:00:00Z"
  }

유효 정책 검색

• 현재 프로젝트의 유효 정책에 대한 BASIC 뷰를 가져옵니다.

  gcloud beta services policies get-effective

  출력:

  EnabledRules:
   Services:
    -   services/apikeys.googleapis.com
    -   services/compute.googleapis.com
    -   services/computescanning.googleapis.com
    -   services/containeranalysis.googleapis.com
    -   services/containerscanning.googleapis.com
    -   services/gkebackup.googleapis.com
    -   services/osconfig.googleapis.com
    -   services/oslogin.googleapis.com
    -   services/serviceusage.googleapis.com

• 현재 프로젝트의 유효 정책에 대한 FULL 뷰를 가져옵니다.

  gcloud beta services policies get-effective --view=FULL

  출력:

  EnabledRules:
   Services:
    -   services/apikeys.googleapis.com
    -   services/compute.googleapis.com
    -   services/computescanning.googleapis.com
    -   services/containeranalysis.googleapis.com
    -   services/containerscanning.googleapis.com
    -   services/gkebackup.googleapis.com
    -   services/osconfig.googleapis.com
    -   services/oslogin.googleapis.com
    -   services/serviceusage.googleapis.com
  
  Metadata of effective policy:
  EnabledService: services/apikeys.googleapis.com
  EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
  
  EnabledService: services/bcidcloudenforcer-pa.googleapis.com
  EnabledPolicies: ['folders/FOLDER_ID/consumerPolicies/default']
  
  EnabledService: services/compute.googleapis.com
  EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
  ...

서비스가 사용 설정되어 있는지 확인

• 현재 프로젝트에 사용 설정된 API 키 서비스의 상태를 확인합니다.

  gcloud beta services policies test-enabled apikeys.googleapis.com

  출력:

  Service apikeys.googleapis.com is ENABLED for resource projects/test-project Hierarchical Service Activation.

• 현재 프로젝트에서 사용 중지된 App Hub 서비스의 상태를 확인합니다.

  gcloud beta services policies test-enabled apphub.googleapis.com

  출력:

  Service apphub.googleapis.com is NOT ENABLED for resource projects/test-project Hierarchical Service Activation.

다음 단계

• 서비스를 사용 설정 및 중지하려면 서비스 사용 설정 관리를 참고하세요.
• 서비스 종속 항목을 검사하려면 서비스 종속 항목 나열을 참고하세요.