이 페이지에서는 Cloud Quotas API를 사용하여 일반적인 사용 사례를 구현하는 방법을 설명합니다. 이 API를 사용하면 Google Cloud 프로젝트, 폴더 또는 조직에서 프로그래매틱 방식으로 할당량을 조정하고 할당량 조정을 자동화할 수 있습니다.
자세한 내용은 Cloud Quotas API 개요 및 참조를 확인하세요.
제한사항
Cloud Quotas API에는 다음과 같은 제한사항이 있습니다.
API는 Google Cloud CLI를 지원하지 않습니다.
이 API는 프로젝트 수준 할당량의 할당량 조정을 지원합니다. 프로젝트, 폴더, 조직 수준 할당량에 대해 할당량 감소를 요청할 수 있습니다.
API는 VPC 서비스 제어를 지원하지 않습니다.
사용량 추적 및 사용량이 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" ] } ] }, … ]이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
- 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 } }이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
- 사용량을 확인하려면 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 } } }이 출력에는 다음 값이 포함됩니다.PROJECT_ID: 프로젝트의 전역적으로 고유한 식별자입니다.
- 중복된 할당량 환경설정을 방지하려면 먼저
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": [ "mapField": { "key": "region", "value": "us-central1" } ], }이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
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": [ "mapField": { "key": "region", "value": "us-central1" } ], "reconciling": true "createTime": "2023-01-15T01:30:15.01Z", "updateTime": "2023-01-16T02:35:16.01Z"이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
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" ] } ] }, … ]이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
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", }이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
- 할당량 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" ] } ]이 출력에는 다음 값이 포함됩니다.PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
다른 프로젝트에 할당량 환경설정 복사
다음 예시에서는 모든 할당량 환경설정을 한 프로젝트에서 다른 프로젝트로 복사합니다.
- 필터 없이 소스 프로젝트에서
ListQuotaPreferences를 호출합니다.GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
PROJECT_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()) .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": [
"map_field": {
"key": "region",
"value": "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"
}
]
이 출력에는 다음 값이 포함됩니다.
PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
요청 그룹 할당량 상향 조정
새 프로젝트에서 할당량 그룹 상향을 요청하려면 서비스 이름, 할당량 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가 자동으로 생성됩니다.
서비스별 측정기준의 할당량 정보 가져오기
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": [
"mapField": {
"key": "region",
"value": "us-central1"
},
"mapField": {
"key": "gpu_family",
"value": "NVIDIA_H200"
}
],
"details": {
"quotaValue": 30,
"resetValue": 30,
},
"applicableLocations": [
"us-central1"
]
},
{
"dimensions": [
"mapField": {
"key": "region",
"value": "us-central1"
}
],
"details": {
"quotaValue": 100,
"resetValue": 100,
},
"applicableLocations": [
"us-central1"
]
},
{
"dimensions": [
"mapField": {
"key": "gpu_familly",
"value": "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"
]
}
]
이 출력에는 다음 값이 포함됩니다.
PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.
서비스별 측정기준의 할당량 환경설정 만들기
다음 예시에서는 선호하는 값이 100인 특정 리전 및 GPU 제품군의 할당량을 만드는 방법을 보여줍니다. 대상 위치는 region 키가 있는 측정기준 맵과 gpu_family 키가 있는 대상 GPU 제품군에 지정됩니다.
다음 CreateQuotaPreference 예시에서는 GPU 제품군 NVIDIA_H100 및 리전 us-central1을 지정합니다. PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
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": [
"mapField": {
"key": "region",
"value": "us-central1"
}
"mapField": {
"key": "gpu_family",
"value": "NVIDIA_H100"
}
],
}
서비스별 측정기준의 할당량 환경설정 업데이트
다음 샘플 코드에서는 {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} 측정기준의 현재 값을 가져온 다음 선호하는 값을 두 배로 설정합니다. PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
// 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);