일반적인 사용 사례 구현

이 페이지에서는 Cloud Quotas API를 사용하여 일반적인 사용 사례를 구현하는 방법을 설명합니다. 이 API를 사용하면 Google Cloud 프로젝트, 폴더 또는 조직에서 프로그래매틱 방식으로 할당량을 조정하고 할당량 조정을 자동화할 수 있습니다.

자세한 내용은 Cloud Quotas API 개요참조를 확인하세요.

제한사항

Cloud Quotas에는 다음과 같은 제한사항이 있습니다.

  • 모든 할당량 상향 조정은 Google Cloud 승인을 받아야 합니다.

  • 프로젝트 수준 할당량의 할당량 상향 및 하향 조정을 모두 요청할 수 있습니다.

  • project-, folder-, 조직 수준 할당량에 대한 할당량 하향 조정을 요청할 수 있습니다.

사용량 추적 및 사용량이 80%를 초과하면 상향 요청

이 예시에서는 Cloud Monitoring으로 할당량 사용량을 추적한 후 사용량이 80%를 초과하면 할당량 상향을 요청합니다.

  1. 서비스의 QuotaInfo 리소스를 호출하여 현재 quotaValue를 확인합니다. 이 예시의 서비스는 compute.googleapis.com입니다.
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
  2. 프로젝트당 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"
                    ]
                }
            ]
        },
        ...
    ]
    
  3. 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"
        }
    }
    
  4. 사용량을 확인하려면 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
        }
      }
    }
    
  5. 중복된 할당량 환경설정을 방지하려면 먼저 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를 프로젝트의 프로젝트 번호로 바꿉니다.
  6. 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" }
    }
    
  7. 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로 설정됩니다. grantedValuepreferredValue와 동일합니다. 선호 할당량이 완전히 부여됩니다.

    Google Cloud에서 고객 요청을 거부하거나 부분적으로 승인하는 경우 부여된 할당량 값이 원하는 값보다 작을 수 있습니다.

할당량 줄이기

다음 예시에서는 각 리전의 TPU 수를 10개로 줄입니다.

  1. ListQuotaInfos 호출을 사용하여 할당량 ID 및 현재 할당량 값을 가져옵니다.
    GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
    PROJECT_NUMBER를 프로젝트의 프로젝트 번호로 바꿉니다.
  2. 응답 필드를 검토하여 V2-TPUS-per-project-regionQuotaInfo 항목을 찾습니다.
    "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입니다.
  3. 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
    }
    
  4. 할당량 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"
            ]
        }
    ]
    

다른 프로젝트에 할당량 환경설정 복사

다음 예시에서는 모든 할당량 환경설정을 한 프로젝트에서 다른 프로젝트로 복사합니다.

  1. 필터 없이 소스 프로젝트에서 ListQuotaPreferences를 호출합니다.
    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
    PROJECT_NUMBER1은 소스 프로젝트의 프로젝트 번호입니다. 응답에는 소스 프로젝트의 모든 할당량 환경설정이 포함됩니다.
  2. 응답의 할당량 환경설정마다 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);
    }
    
  3. 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_missingtrue로 설정하여 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" },
    "contactEmail": EMAIL
}

다음을 바꿉니다.

  • PROJECT_NUMBER: 프로젝트의 고유 식별자입니다.
  • 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 키마다 quotaValueapplicableLocations가 다릅니다.

"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를 프로젝트의 고유 식별자로 바꿉니다.

다음 단계