이 페이지에서는 Cloud Quotas API를 사용하여 일반적인 사용 사례를 구현하는 방법을 설명합니다. 이 API를 사용하면 Google Cloud 프로젝트, 폴더 또는 조직에서 프로그래매틱 방식으로 할당량을 조정하고 할당량 조정을 자동화할 수 있습니다.
자세한 내용은 Cloud Quotas API 개요 및 참조를 확인하세요.
제한사항
Cloud Quotas에는 다음과 같은 제한사항이 있습니다.
대부분의 경우 할당량 상향 조정은 프로젝트 수준에서 이루어져야 합니다. 일부 제품만 조직 수준 할당량 상향 조정을 지원합니다. Google Cloud 제품에서 조직 수준 할당량 증가 조정을 지원하는지 확인하려면 해당 제품의 문서를 참고하세요.
프로젝트, 조직, 폴더 수준 할당량에 대한 할당량 감소 조정을 요청할 수 있습니다.
Cloud Quotas API는 프로젝트 수준의 작업만 지원합니다. 폴더 수준 및 조직 수준 작업은 지원되지 않습니다.
사용량 추적 및 사용량이 80%를 초과하면 상향 요청
이 예시에서는 Cloud Monitoring으로 할당량 사용량을 추적한 후 사용량이 80%를 초과하면 할당량 상향을 요청합니다.
서비스의
QuotaInfo리소스를 호출하여 현재quotaValue를 확인합니다. 이 예시의 서비스는compute.googleapis.com입니다.GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfosPROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.프로젝트당 CPU 수와 적용 가능한 위치를 찾으려면
CPUS-per-project-region할당량 ID의QuotaInfo응답을 검토합니다.quotaValue는 20입니다."quotaInfos": [ ... { "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region", "quotaId": "CPUS-per-project-region", "metric": "compute.googleapis.com/cpus", "containerType": "PROJECT", "dimensions": [ "region" ], "dimensionsInfo": [ { "dimensions": [], "details": { "quotaValue": 20, "resetValue": 20 }, "applicableLocations": [ "us-central1", "us-central2", "us-west1", "us-east1" ] } ] }, ... ]
Cloud Monitoring API를 호출하여 할당량 사용량을 찾습니다. 다음 예시에서는
us-central1리전이 지정되었습니다. 지원되는 할당량 측정항목은serviceruntime에 나와 있습니다.{ "name": "projects/PROJECT_NUMBER" "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND resource.label.location=\"us-central1\" ", "interval": { "startTime": "2023-11-10T18:18:18.0000Z", "endTime": "2023-11-17T18:18:18.0000Z" }, "aggregation": { "alignmentPeriod": "604800s", // 7 days "perSeriesAligner": "ALIGN_MAX", "crossSeriesReducer": "REDUCE_MAX" } }
사용량을 확인하려면 Cloud Monitoring API에서 응답을 처리합니다. Cloud Monitoring의 값을 이전 단계의
quotaValue와 비교하여 사용량을 확인합니다.다음 예시 응답에서 Cloud Monitoring의 사용량 값은
us-central1리전의 19입니다. 모든 리전의quotaValue는 20입니다. 사용량이 할당량의 80% 를 초과하면 할당량 환경설정 업데이트를 시작할 수 있습니다.time_series { metric { labels { key: "quota_metric" value: "compute.googleapis.com/cpus" } type: "serviceruntime.googleapis.com/quota/allocation/usage" } resource { type: "consumer_quota" labels { key: "project_id" value: "PROJECT_ID" } labels { key: "location" value: "us-central1" } } metric_kind: GAUGE value_type: INT64 points { interval { start_time { seconds: "2023-11-10T18:18:18.0000Z" } end_time { seconds: "2023-11-17T18:18:18.0000Z" } } value { int64_value: 19 } } }
중복된 할당량 환경설정을 방지하려면 먼저
ListQuotaPreferences를 호출하여 대기 중인 요청이 있는지 확인합니다.reconciling=true플래그는 대기 중인 요청을 호출합니다.GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.UpdateQuotaPreference를 호출하여us-central1리전의 할당량 값을 늘립니다. 다음 예에서는 새로운 선호 값으로 100이 지정되었습니다.allow_missing필드는true로 설정됩니다. 이렇게 하면 시스템에서 제공된 이름이 없는QuotaPreference리소스를 만듭니다.PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true { "service": "compute.googleapis.com", "quotaId": "CPUS-per-project-region", "quotaConfig": { "preferredValue": 100 }, "dimensions": { "region": "us-central1" }, "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
다음을 바꿉니다.
PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.JUSTIFICATION: 요청을 설명하는 선택적 문자열입니다.EMAIL: 추가 할당량을 부여하기 전에 Google Cloud에서 더 많은 정보가 필요한 경우에 연락처로 사용할 수 있는 이메일 주소입니다.
GetQuotaPreference를 호출하여 할당량 환경설정 변경 상태를 확인합니다.GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.Google Cloud에서 요청된 할당량 값을 평가하는 동안 조정 상태가
true로 설정됩니다."name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1", "service": "compute.googleapis.com", "quotaId": "CPUS-per-project-region", "quotaConfig": { "preferredValue": 100, "grantedValue": 50, "traceId": "123acd-345df23", "requestOrigin": "ORIGIN_UNSPECIFIED" }, "dimensions": { "region": "us-central1" }, "reconciling": true, "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z"
할당량 환경설정이 처리되면
reconciling필드가false로 설정됩니다.grantedValue는preferredValue와 동일합니다. 선호 할당량이 완전히 부여됩니다.Google Cloud에서 고객 요청을 거부하거나 부분적으로 승인하는 경우 부여된 할당량 값이 원하는 값보다 작을 수 있습니다.
할당량 줄이기
다음 예시에서는 각 리전의 TPU 수를 10개로 줄입니다.
ListQuotaInfos호출을 사용하여 할당량 ID와 현재 할당량 값을 가져옵니다.GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfosPROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.응답 필드를 검토하여
V2-TPUS-per-project-region의QuotaInfo항목을 찾습니다."quotaInfos": [ ... { "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region", "quotaId": "V2-TPUS-per-project-region", "metric": "compute.googleapis.com/Tpus", "containerType": "PROJECT", "dimensions": [ "region" ], "dimensionsInfo": [ { "dimensions": [], "details": { "quotaValue": 20, "resetValue": 20 }, "applicableLocations": [ "us-central1", "us-central2", "us-west1", "us-east1" ] } ] }, ... ]
이 응답에서 할당량 ID는
V2-TPUS-per-project-region이고 현재quotaValue는 20입니다.CreateQuotaPreferenceRequest를 사용하여 각 리전의 TPU 할당량을 10으로 줄입니다.preferredValue를 10으로 설정합니다.POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions { "quotaConfig": { "preferredValue": 10 }, "dimensions": [], "service": "compute.googleapis.com", "quotaId": "V2-TPUS-per-project-region", "justification": "JUSTIFICATION", "contactEmail": "EMAIL" }
다음을 바꿉니다.
PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.JUSTIFICATION: 요청을 설명하는 선택적 문자열입니다.EMAIL: 추가 할당량을 부여하기 전에 Google Cloud에서 더 많은 정보가 필요한 경우에 연락처로 사용할 수 있는 이메일 주소입니다.
할당량 ID를
V2-TPUS-per-project-region으로 정의하는GetQuotaInfo호출로 새 할당량 값을 확인합니다.GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-regionPROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.다음은 응답의 예시입니다.
value는 10이며 모든 리전에 적용할 수 있습니다."name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region", "quotaId": "V2-TPUS-per-project-region", "metric": "compute.googleapis.com/v2_tpus", "containerType": "PROJECT", "dimensions": [ "region" ], "dimensionsInfo": [ { "dimensions": [], "details": { "value": 10, }, "applicableLocations": [ "us-central1", "us-central2", "us-west1", "us-east1" ] } ]
다른 프로젝트에 할당량 환경설정 복사
다음 예시에서는 모든 할당량 환경설정을 한 프로젝트에서 다른 프로젝트로 복사합니다. Java로 작성되었지만 어떤 프로그래밍 언어든 사용할 수 있습니다.
필터 없이 소스 프로젝트에서
ListQuotaPreferences를 호출합니다.GET projects/PROJECT_NUMBER1/locations/global/quotaPreferencesPROJECT_NUMBER1은 소스 프로젝트의 프로젝트 번호입니다. 응답에는 소스 프로젝트의 모든 할당량 환경설정이 포함됩니다.
응답의 할당량 환경설정마다
UpdateQuotaPreference를 호출하고 다음 필드를 정의합니다.name- 업데이트된 이름 필드를 응답에서 가져오고 소스 프로젝트 번호 (PROJECT_NUMBER1)를 대상 프로젝트 번호 (PROJECT_NUMBER2)로 바꿉니다.service,quotaId,preferredValue,dimensions- 이러한 필드는 응답에서 있는 그대로 직접 가져올 수 있습니다.
for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) { QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder() .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2")) .setService(srcPreference.getService()) .setQuotaId(srcPreference.getQuotaId()) .setJustification(srcPreference.getJustification()) .setContactEmail(srcPreference.getContactEmail()) .setQuotaConfig( QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue())) .putAllDimensions(srcPreference.getDimensionsMap()); UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder() .setQuotaPreference(targetPreference) .setAllowMissing(true) .build(); cloudQuotas.updateQuotaPreference(updateRequest); }
ListQuotaPreferences를 호출하여 대상 프로젝트의 할당량 환경설정 상태를 확인합니다.GET projects/PROJECT_NUMBER2/locations/global/quotaPreferencesPROJECT_NUMBER2를 대상 프로젝트의 프로젝트 번호로 바꿉니다.
대기 중인 할당량 요청 나열
프로젝트의 대기 중인 모든 할당량 환경설정 요청을 나열하려면 reconciling=true 필터를 사용하여 ListQuotaPreferences를 호출합니다.
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true
PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
이 요청에 대한 응답은 대기 중인 최신 할당량 환경설정을 반환합니다. Cloud Quotas API는 선언적 API이므로 최신 할당량 환경설정을 시스템이 처리하려고 합니다.
응답 예시는 다음과 비슷합니다.
"quotaPreferences": [ { "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1", "service": "compute.googleapis.com", "quotaId": "CPUS-per-project-region", "quotaConfig": { "preferredValue": 100, "grantedValue": 30, "traceId": "123acd-345df23", "requestOrigin": "ORIGIN_UNSPECIFIED" }, "dimensions": { "region": "us-central1" }, "reconciling": true, "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z" }, { "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions", "service": "compute.googleapis.com", "quotaId": "CPUS-per-project-region", "quotaConfig": { "preferredValue": 10, "grantedValue": 5, "traceId": "456asd-678df43", "requestOrigin": "ORIGIN_UNSPECIFIED" }, "reconciling": true, "createTime": "2023-01-15T01:35:15.01Z", "updateTime": "2023-01-15T01:35:15.01Z" } ]
요청 그룹 할당량 상향 조정
새 프로젝트에서 할당량 그룹 상향을 요청하려면 서비스 이름, 할당량 ID, 선호되는 할당량 값, 측정기준과 함께 새 프로젝트의 선호 할당량을 CSV 파일에 저장합니다.
CSV 파일의 각 행의 콘텐츠를 serviceName, quotaId, preferredValue, dimensionMap 필드로 읽습니다.
CreateQuotaPreferenceRequest request = CreateQuotaPreferenceRequest.newBuilder() .setParent("projects/PROJECT_NUMBER/locations/global") .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap)) .setQuotaPreference( QuotaPreference.newBuilder() .setService(serviceName) .setQuotaId(quotaId) .setJustification(justification) .setContactEmail(contactEmail) .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue)) .putAllDimensions(dimensionMap)) .build(); cloudQuotas.createQuotaPreference(request);
PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
대상 프로젝트가 새 프로젝트이므로 필드를 읽고 할당할 때 CreateQuotaPreference 메서드를 호출하는 것이 안전합니다. 또는 allow_missing을 true로 설정하여 UpdateQuotaPreference 메서드를 호출할 수 있습니다.
buildYourOwnQuotaPreferenceId 메서드는 이름 지정 스킴에 따라 서비스 이름, 할당량 ID, 측정기준 맵 중에서 할당량 환경설정 ID를 만듭니다. 또는 할당량 환경설정 ID를 설정하지 않을 수 있습니다. 할당량 환경설정 ID가 자동으로 생성됩니다.
사용량이 없는 할당량 조정 요청
아직 할당량 사용량이 없고 vm_family와 같은 서비스별 측정기준이 있는 할당량의 경우 Google Cloud 콘솔에 표시되지 않을 수 있습니다. 대신 Cloud Quotas API를 사용해야 할 수도 있습니다.
예를 들어 프로젝트를 클론하고 compute.googleapis.com/gpus_per_gpu_family의 값을 늘려야 한다는 것을 미리 알 수 있습니다.
이 값은 이미 사용한 GPU 계열의 Google Cloud 콘솔에만 표시됩니다. Cloud Quotas API를 사용하여 us-central1에서 NVIDIA_H100 GPU를 늘리도록 요청하려면 다음과 같은 요청을 전송하면 됩니다.
POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
"service": "compute.googleapis.com",
"quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
"quotaConfig": { "preferredValue": 100 },
"dimensions": { "region": "us-central1", "gpu_family": "NVIDIA_H100" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}
다음을 바꿉니다.
PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.JUSTIFICATION: 요청을 설명하는 선택적 문자열입니다.EMAIL: 추가 할당량을 부여하기 전에 Google Cloud에서 더 많은 정보가 필요한 경우에 연락처로 사용할 수 있는 이메일 주소입니다.
자세한 내용은 측정기준 우선순위 및 측정기준 결합에 관한 설명도 참고하세요.
서비스별 측정기준의 할당량 정보 가져오기
GPU 제품군은 서비스별 측정기준입니다. 다음 요청 예시에서는 GPUS-PER-GPU-FAMILY-per-project-region 할당량 ID를 사용하여 QuotaInfo 리소스를 가져옵니다.
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-regionPROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
다음은 응답 예입니다. 고유한 gpu_family 키마다 quotaValue 및 applicableLocations가 다릅니다.
"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion", "quotatName": "CPUS-per-project-region", "metric": "compute.googleapis.com/gpus_per_gpu_family", "isPrecise": true, "quotaDisplayName": "GPUs per GPU family", "metricDisplayName": "GPUs", "dimensions": [ "region", "gpu_family" ], "dimensionsInfo": [ { "dimensions": { "region": "us-central1", "gpu_family": "NVIDIA_H200" }, "details": { "quotaValue": 30, "resetValue": 30, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": { "region": "us-central1" } "details": { "quotaValue": 100, "resetValue": 100, }, "applicableLocations": [ "us-central1" ] }, { "dimensions": { "gpu_familly": "NVIDIA_H100" } "details": { "quotaValue": 10, }, "applicableLocations": [ "us-central2", "us-west1", "us-east1" ] } { "dimensions": [], "details": { "quotaValue": 50, "resetValue": 50, }, "applicableLocations": [ "us-central1", "us-central2", "us-west1", "us-east1" ] } ]
서비스별 측정기준의 할당량 환경설정 만들기
다음 예시에서는 선호하는 값이 100인 특정 리전 및 GPU 제품군의 할당량을 만드는 방법을 보여줍니다. 대상 위치는 region 키가 있는 측정기준 맵과 gpu_family 키가 있는 대상 GPU 제품군에 지정됩니다.
다음 CreateQuotaPreference 예시에서는 GPU 제품군 NVIDIA_H100 및 리전 us-central1을 지정합니다.
POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 { "service": "compute.googleapis.com", "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region", "quotaConfig": { "preferredValue": 100 }, "dimensions": {"region": "us-central1", "gpu_family": "NVIDIA_H100"}, "justification": "JUSTIFICATION", "contactEmail": ""EMAIL" }
다음을 바꿉니다.
PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.JUSTIFICATION: 요청을 설명하는 선택적 문자열입니다.EMAIL: 추가 할당량을 부여하기 전에 Google Cloud에서 더 많은 정보가 필요한 경우에 연락처로 사용할 수 있는 이메일 주소입니다.
서비스별 측정기준의 할당량 환경설정 업데이트
다음 샘플 코드에서는 측정기준 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"},의 현재 값을 가져온 다음 원하는 값을 두 배로 설정합니다. Java로 작성되었지만 어떤 프로그래밍 언어든 사용할 수 있습니다.
// Get the current quota value for the target dimensions Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100"); long currentQuotaValue = 0; QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo( "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId; for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) { If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) { currentQuotaValue = dimensionsInfo.getDetails().getValue(); break; }) } // Set the preferred quota value to double the current value for the target dimensions QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder() .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions)) .setService(serviceName) .setQuotaId(quotaId) .setJustification(justification) .setContactEmail(contactEmail) .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2)) .putAllDimensions(targetDimensions)); UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder() .setQuotaPreference(targetPreference) .setAllowMissing(true) .build(); cloudQuotas.updateQuotaPreference(updateRequest);
PROJECT_NUMBER를 프로젝트의 고유 식별자로 바꿉니다.