Cloud Quotas API 개요

Cloud Quotas API를 사용하면 프로젝트 수준 할당량을 프로그래매틱 방식으로 조정하고 프로젝트 수준 할당량 조정 요청을 자동화할 수 있습니다. 예를 들어 Cloud Quotas API를 사용하여 다음을 수행할 수 있습니다.

  • 할당량 조정 자동화: Cloud Quotas API를 사용하여 자체 기준에 따라 할당량 조정을 요청할 수 있습니다. 예를 들어 할당량 초과 오류가 방지되도록 API를 사용하여 Compute Engine 리소스가 사용 가능한 할당량의 80%에 도달할 때 할당량 조정을 프로그래매틱 방식으로 요청할 수 있습니다.

  • 프로젝트 간에 할당량 구성 재사용: Cloud Quotas API는 프로젝트 간에 할당량 구성을 클론할 수 있습니다. 알려진 할당량 집합이 있고 이 집합을 모든 새 프로젝트에 대해 증가시켜야 하는 경우 Google Cloud Cloud Quotas API를 사용하여 프로젝트 생성 로직에서 이를 자동화할 수 있습니다. 할당량 조정 요청은 Google Cloud 승인을 받아야 합니다.

  • 고객 할당량 요청 처리:Google Cloud와 통합된 SaaS 제공업체인 경우 Google Cloud 콘솔이 아닌 고객 대상 포털을 통해 할당량 상향 요청을 받을 수 있습니다. 이러한 요청을 처리할 수 있도록 Google Cloud 로 전달해야 합니다. Cloud Quotas API는 자동으로 고객 요청을 전달할 수 있습니다.

  • 클라이언트 구성 버전 제어 사용 설정: Cloud Quotas API는 선언적입니다. 할당량 구성을 코드로 취급하고 기록과 롤백을 위해 구성을 자체 버전 제어 시스템에 저장할 수 있습니다.

제한사항

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

  • 대부분의 경우 할당량 상향 조정은 프로젝트 수준에서 이루어져야 합니다. 일부 제품만 조직 수준 할당량 상향 조정을 지원합니다. Google Cloud 제품이 조직 수준 할당량 증가 조정을 지원하는지 확인하려면 해당 제품의 문서를 참고하세요.

  • 프로젝트, 조직, 폴더 수준 할당량에 대한 할당량 감소 조정을 요청할 수 있습니다.

  • Cloud Quotas API는 프로젝트 수준의 작업만 지원합니다. 폴더 수준 및 조직 수준 작업은 지원되지 않습니다.

서비스 엔드포인트

서비스 엔드포인트는 API 서비스의 네트워크 주소를 지정하는 기준 URL입니다. 서비스 하나에 엔드포인트가 여러 개 있을 수 있습니다. Cloud Quotas API 서비스에는 다음 엔드포인트가 있으며 모든 URI가 이를 기준으로 합니다.

https://cloudquotas.googleapis.com

필요한 역할

cloudquotas_quotaPreferences, cloudquotas_quotaInfos, cloudquotas_quotaAdjusterSettings 리소스에 액세스하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud 할당량 관리자 (cloudquotas.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

이 사전 정의된 역할에는 cloudquotas_quotaPreferences, cloudquotas_quotaInfos, cloudquotas_quotaAdjusterSettings 리소스에 액세스하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

cloudquotas_quotaPreferences, cloudquotas_quotaInfos, cloudquotas_quotaAdjusterSettings 리소스에 액세스하려면 다음 권한이 필요합니다.

  • cloudquotas.quotas.update
  • cloudquotas.quotas.get
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

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

API 리소스 모델

Cloud Quotas API 리소스 모델은 QuotaPreference 및 QuotaInfo의 두 가지 리소스로 구성됩니다.

할당량 환경설정

QuotaPreference 리소스는 특정 측정기준 조합의 할당량 환경설정을 나타냅니다. 이 리소스를 사용하여 프로젝트, 폴더 또는 조직의 할당량을 조정합니다.

리전의 선호 값 설정

다음 예시에서는 CreateQuotaPreference 메서드의 QuotaPreference 리소스를 보여줍니다.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

preferredValue가 100이면 요청자가 GPUS-PER-GPU-FAMILY-per-project-region 할당량을 해당 값으로 설정하려고 함을 나타냅니다. 측정기준 필드는 환경설정이 us-central1 리전에만 적용됨을 나타냅니다.

부여된 값 확인

할당량 환경설정을 확인하고 grantedValue 필드를 보고 부여된 값을 확인합니다.

Google Cloud CLI를 사용하여 할당량 환경설정을 보려면 터미널에서 다음을 실행합니다.

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

다음을 바꿉니다.

  • QUOTA_PREFERENCE_ID: 할당량 환경설정의 ID입니다. 할당량 환경설정을 만들 때 지정된 값입니다.
  • PROJECT: Google Cloud프로젝트의 ID 또는 번호입니다.

할당량 조정 요청을 제출했는데 요청이 부분적으로 승인된 경우 grantedValue 필드 뒤에 stateDetail 필드가 표시됩니다. grantedValue에는 적용된 조정이 표시되고 stateDetail 필드에는 부분적으로 승인된 상태가 설명됩니다.

부여된 값이 승인된 최종 값인지 확인하려면 reconciling 필드를 살펴보세요. 요청이 아직 평가 중인 경우 reconciling 필드는 true로 설정됩니다. reconciling 필드가 false로 설정되거나 생략된 경우 승인된 값이 승인된 최종 값입니다.

다음 코드 스니펫은 할당량 환경설정 객체의 예를 보여줍니다. ID가 compute_googleapis_com-gpus-us-central1인 데모 할당량 환경설정을 사용합니다.

gcloud

gcloud CLI를 사용하여 할당량 환경설정을 확인하면 다음과 유사한 출력이 표시됩니다.

createTime: '2023-01-15T01:30:15.01Z'
dimensions:
    region: us-central1
name: projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1
quotaConfig:
    granteddValue: '100'
    preferredValue: '100'
    traceId: 123acd-345df23
    requestOrigin: ORIGIN_UNSPECIFIED
service: compute.googleapis.com
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
updateTime: '2023-01-16T02:35:16.01Z'

REST

Cloud Quotas API를 사용하여 할당량 환경설정을 확인하면 다음과 유사한 출력이 표시됩니다.

{
    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1",
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 100,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
    },
    "dimensions": {
        "region": "us-central1"
    },
    "createTime": "2023-01-15T01:30:15.01Z",
    "updateTime": "2023-01-16T02:35:16.01Z"
}

이 출력에는 다음 값이 포함됩니다.

  • PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.

응답에 grantedValue 100이 표시됩니다. 즉, 이전 예시의 preferredValue가 승인되고 처리되었습니다. 다른 측정기준의 환경설정은 다른 QuotaPreference 리소스입니다. 예를 들어 us-central1 및 us-east1 리전의 CPU에 대한 QuotaPreference는 두 개의 개별 리소스입니다.

할당량 환경설정은 필수 항목입니다

QuotaPreference 리소스는 특정 할당량에 선호하는 값을 나타내는 데 사용됩니다. 특정 할당량의 현재 값은 다음을 기반으로 합니다.

  • 수행한 QuotaPreference 요청

  • Google Cloud에서 승인한 할당량 상향 요청

  • Google Cloud에서 시작한 할당량 변경사항

QuotaPreference 삭제 기능은 지원되지 않습니다. 하지만 Google Cloud 승인된 값보다 낮게 할당량 선호 값을 설정하여 가드레일을 추가할 수 있습니다.

QuotaPreference 리소스에 대한 자세한 내용은 Cloud Quotas API 참조를 확인하세요.

QuotaPreference 쿼리에 대한 자세한 내용은 일반적인 사용 사례 구현을 참조하세요.

할당량 정보

QuotaInfo는 지정된 프로젝트, 폴더 또는 조직의 특정 할당량에 대한 정보를 제공하는 읽기 전용 리소스입니다. 서비스에서 정의한 할당량과 고객이 시작한 처리된 할당량 조정에 대한 정보가 표시됩니다. Google Cloud QuotaInfo 리소스에는 메타데이터, 컨테이너 유형, 측정기준과 같은 정보가 포함됩니다.

리전별로 다른 할당량 값 설정

다음 QuotaInfo 리소스 예시에서는 프로젝트의 CPU 할당량이 us-central1 리전의 경우 200, 다른 모든 리전의 경우 100입니다.

{
    "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"
    ],
    "isPrecise": true,
    "quotaDisplayName": "CPUs per project per region",
    "metricDisplayName": "CPUs",
    "dimensionsInfo": [
        {
            "dimensions": {
                "region": "us-central1"
            },
            "details": {
                "quotaValue": 200,
                "resetValue": 200
            },
            "applicableLocations": [
                "us-central1",
            ]
        },
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 100
            },
            "applicableLocations": [
                "us-central2",
                "us-west1",
                "us-east1"
            ]
        }
    ]
}

이 출력에는 다음 값이 포함됩니다.

  • PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.

전역 할당량 설정

다음 QuotaInfo 리소스 예시에서는 분당 새로고침 간격이 있는 비율 할당량을 보여줍니다. 측정기준은 비어 있으며, 이는 전역 할당량임을 나타냅니다. 리전 또는 영역 측정기준이 없는 모든 할당량은 전역 할당량입니다.

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject",
    "quotaId": "ReadRequestsPerMinutePerProject",
    "metric": "compute.googleapis.com/read_requests",
    "refreshInterval": "minute",
    "containerType": "PROJECT",
    "dimensions": [],
    "isPrecise": false,
    "quotaDisplayName": "Read Requests per Minute",
    "metricDisplayName": "Read Requests",
    "dimensionsInfo": [
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 200
            },
            "applicableLocations": [
                "global"
            ]
        }
    ]
}

이 출력에는 다음 값이 포함됩니다.

  • PROJECT_NUMBER: 자동으로 생성되는 프로젝트의 고유 식별자입니다.

QuotaInfo 리소스에 대한 자세한 내용은 Cloud Quotas API 참조를 확인하세요.

QuotaPreference 쿼리에 대한 자세한 내용은 일반적인 사용 사례 구현을 참조하세요.

할당량 조정자 설정

QuotaAdjusterSettings 리소스 (미리보기)는 특정 프로젝트의 할당량 조정자 설정을 나타냅니다. 사용 설정하면 할당량 조정자가 지정된 리소스의 사용량을 모니터링하고 리소스 사용량이 할당량 값에 가까워지면 할당량 조정 요청을 실행합니다.

  • 프로젝트의 현재 할당량 조정자 설정을 보려면 GET 작업을 사용하여 QuotaAdjusterSettings 리소스를 가져옵니다.

  • 프로젝트에 할당량 조정자를 사용 설정하려면 PATCH 작업을 사용하여 다음 QuotaAdjusterSettings 리소스 옵션을 설정합니다.

      "quota_adjuster_settings" :{
     "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
     "enablement": ENABLED,
}

    PROJECT_NUMBER를 프로젝트의 고유 식별자로 바꿉니다.

자세한 내용은 할당량 조정자 사용 설정 및 할당량 조정자 사용 중지를 참고하세요.

리소스 이름

리소스는 이름이 지정된 항목이며 리소스 이름으로 식별됩니다. 리소스 이름은 모든 요청과 응답에 사용되며 각 리소스에는 고유한 리소스 이름이 있어야 합니다. 각 리소스 이름은 필드 집합으로 인코딩됩니다.

할당량 환경설정 리소스

QuotaPreference 리소스 명명 규칙에서는 다음 패턴을 사용합니다.

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

할당량 환경설정을 만들 때 quotaPreferenceId를 설정할 수 있습니다. 그렇지 않으면 ID가 생성됩니다. quotaPreferenceId 이름 지정 스키마가 서비스 이름, 할당량 ID, 위치, 기타 측정기준을 인코딩하는 것이 좋습니다. quotaPreferenceId는 프로젝트, 폴더 또는 조직에 고유해야 합니다.

예시: quotaPreference 할당량 환경설정 ID를 인코딩하는 한 가지 패턴은 다음과 같습니다. 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

다음 예시에서는 이 패턴을 보여줍니다. 

compute_us-central1_nvidia-200

리소스 이름을 사용할 때는 GET 메서드를 사용하여 QuotaPreference를 검색해야 합니다. 또한 allow_missing 옵션을 사용 설정하고 PATCH 메서드를 호출하여 QuotaPreference를 만들거나 업데이트할 수 있습니다.

할당량 정보 리소스

QuotaInfo 리소스 명명 규칙에서는 다음 패턴을 사용합니다.

projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID

할당량 조정자 설정 리소스

QuotaAdjusterSettings 리소스 명명 규칙에서는 다음 패턴을 사용합니다.

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

다음 단계