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 승인을 받아야 합니다.

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

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

서비스 엔드포인트

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

https://cloudquotas.googleapis.com

필요한 역할

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

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

필수 권한

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

  • 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 리전에만 적용됨을 나타냅니다.

부여된 값 확인

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

{
    "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 쿼리에 대한 자세한 내용은 일반적인 사용 사례 구현을 참조하세요.

리소스 이름

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

할당량 환경설정 리소스

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 옵션을 사용 설정하고 UPDATE 메서드를 호출하여 QuotaPreference를 만들거나 업데이트할 수 있습니다.

할당량 정보 리소스

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

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

다음 단계