이 페이지에서는 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/quotaInfos
PROJECT_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" } }
GetQuotaPreference를 호출하여 할당량 환경설정 변경 상태를 확인합니다.GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
PROJECT_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/quotaInfos
PROJECT_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" ] } ] }, ... ]
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", "contactEmail": EMAIL }
- 할당량 ID를
V2-TPUS-per-project-region으로 정의하는GetQuotaInfo호출로 새 할당량 값을 확인합니다.GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region
PROJECT_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" ] } ]
다른 프로젝트에 할당량 환경설정 복사
다음 예시에서는 모든 할당량 환경설정을 한 프로젝트에서 다른 프로젝트로 복사합니다.
- 필터 없이 소스 프로젝트에서
ListQuotaPreferences를 호출합니다.GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
- 응답의 할당량 환경설정마다
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()) .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/quotaPreferences
PROJECT_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) .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-region
PROJECT_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"}, "contactEmail": EMAIL" }
다음을 바꿉니다.
PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.EMAIL: 추가 할당량을 부여하기 전에 Google Cloud에서 결정을 내리는 데 더 많은 정보가 필요한 경우에 연락처로 사용할 수 있는 이메일 주소입니다.
서비스별 측정기준의 할당량 환경설정 업데이트
다음 샘플 코드에서는 측정기준 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"},의 현재 값을 가져온 다음 원하는 값을 두 배로 설정합니다.
// 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) .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2)) .putAllDimensions(targetDimensions)); UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder() .setQuotaPreference(targetPreference) .setAllowMissing(true) .build(); cloudQuotas.updateQuotaPreference(updateRequest);
PROJECT_NUMBER를 프로젝트의 고유 식별자로 바꿉니다.