Implementa casos de uso comunes

En esta página, se describe cómo implementar casos de uso comunes mediante la API de Cloud Quotas. Esta API te permite ajustar cuotas y automatizar los ajustes de cuota de manera programática en tus organizaciones, carpetas o proyectos de Google Cloud.

Para obtener más información, consulta la descripción general y la referencia de la API de Cloud Quotas.

Limitaciones

La API de Cloud Quotas tiene las siguientes limitaciones:

• La API no admite Google Cloud CLI.

• La API admite ajustes de cuota para cuotas a nivel de proyecto. Pueden solicitarse disminuciones de cuotas para cuotas a nivel de proyecto, carpeta y organización.

• La API admite Controles del servicio de VPC.

Importante: Consulta el Recurso de REST: folders.locations.quotaPreferences para ver los campos obligatorios y los valores esperados.

Haz un seguimiento del uso y solicita un aumento cuando supere el 80%

En este ejemplo, se realiza un seguimiento de uso cuota con Cloud Monitoring y se solicita un aumento cuando el uso supera el 80%.

1. Llama al QuotaInfo recurso para que tu servicio determine la corriente actualquotaValue. El servicio de este ejemplo es compute.googleapis.com:

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

   Reemplaza PROJECT_NUMBER por el número de tu proyecto.
2. Para encontrar las CPU por proyecto así como las ubicaciones aplicables, busca la respuesta QuotaInfo para el ID de cuota CPUS-per-project-region. El quotaValue es 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"
                   ]
               }
           ]
       },
         …
   ]
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
3. Llama a la API de Cloud Monitoring para buscar el uso de la cuota. En el siguiente ejemplo, se especificó la región us-central1. Las métricas de cuota admitidas se enumeran en 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
       }
   }
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
4. Para determinar tu uso, controla la respuesta de la API de Cloud Monitoring. Compara el valor de Cloud Monitoring con el quotaValue en los pasos anteriores para determinar el uso.
   
   En la siguiente respuesta de ejemplo, el valor de uso en Cloud Monitoring de la región us-central1 es 19. El quotaValue para todas las regiones es 20. El uso supera el 80% de la cuota y puede inicializarse una actualización de preferencia de cuota.

   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
       }
     }
   }
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_ID: Un identificador para tu proyecto que es único a nivel global.
5. Para evitar preferencias de cuota duplicadas, llama a ListQuotaPreferences para verificar si hay solicitudes pendientes. La marca reconciling=true llama a las solicitudes pendientes.

   GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true

   Reemplaza PROJECT_NUMBER por el número de tu proyecto.
6. Llama a UpdateQuotaPreference para aumentar el valor de cuota para la región us-central1. En el siguiente ejemplo, se especificó un nuevo valor preferido de 100.
   
   El campo allow_missing está configurado como true. Esto le dice al sistema que cree un recurso QuotaPreference en el que no exista ninguno con el nombre proporcionado.

   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"
       }
       ],
       }
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
   Para ajustar las dimensiones de tu preferencia de cuota, puedes hacer lo siguiente:

   • Si quieres que aplicar la preferencia de cuota a todas las regiones, quita la información de la región.
   • Si tu cuota se define por zona, reemplaza la información de la región por la de la zona.
7. Llama a GetQuotaPreference para verificar el estado del cambio de preferencia de cuota:

   GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1

   Reemplaza PROJECT_NUMBER por el número de tu proyecto. Mientras Google Cloud evalúa el valor de cuota solicitado, el estado de la conciliación se establece en 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"
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
   Luego de que la preferencia de cuota acaba de procesarse, se establece el campo reconciling en false. El grantedValue es el mismo que el preferredValue. Se otorga la cuota preferida por completo.
   
   Cuando Google Cloud rechaza o aprueba de forma parcial una solicitud del cliente, el valor otorgado de la cuota puede ser menor que el valor preferido.

Disminuye una cuota

En el siguiente ejemplo, se disminuye la cantidad de TPU a 10 en cada región.

1. Obtén el ID de cuota y el valor de cuota actual con una llamada ListQuotaInfos:

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos

   Reemplaza PROJECT_NUMBER por el número de tu proyecto.
2. Revisa los campos de respuesta con el fin de encontrar una entrada QuotaInfo para V2-TPUS-per-project-region.

   "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"
                   ]
               }
           ]
       },
         …
   ]
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
   En esta respuesta, el ID de cuota es V2-TPUS-per-project-region y el quotaValue actual es 20.
3. Reduce la cuota de TPU a 10 en cada región con un CreateQuotaPreferenceRequest. Establece preferredValue en 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",
   }
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.
4. Confirma el nuevo valor de la cuota con una llamada GetQuotaInfo que define al ID de cuota como V2-TPUS-per-project-region.

   GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

   Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto. La siguiente es una respuesta de ejemplo en la que value es 10 y se aplica a todas las regiones.

   "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"
           ]
       }
   ]
   

   Esta salida cuenta con los siguientes valores:
   • PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.

Copiar preferencias de cuota en otro proyecto

En el siguiente ejemplo, todas las preferencias de cuota se copian de un proyecto a otro.

1. Llama a ListQuotaPreferences en el proyecto de origen sin filtro:

   GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

   PROJECT_NUMBER1 es el número del proyecto de origen. La respuesta contiene todas las preferencias de cuota del proyecto de origen.
2. Para cada preferencia de cuota en la respuesta, llama a UpdateQuotaPreference y define los siguientes campos:
   • name: El campo de nombre actualizado se toma de la respuesta y el número de proyecto de origen (PROJECT_NUMBER1) es reemplazado por el número de proyecto de destino (PROJECT_NUMBER2).
   • service, quotaId, preferredValue, dimensions: Estos campos pueden tomarse de forma directa de la respuesta en sí.

   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. Llama a ListQuotaPreferences para verificar el estado de las preferencias de cuota del proyecto de destino:

   GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences

   Reemplaza PROJECT_NUMBER2 por el número de tu proyecto de destino.

Enumerar las solicitudes de cuota pendientes

Para enumerar todas las solicitudes de preferencia de cuota pendientes de un proyecto, llama a ListQuotaPreferences con el filtro reconciling=true.

Get projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto.

La respuesta a esta solicitud muestra la última preferencia de cuota pendiente. Debido a que la API de Cloud Quotas es una API declarativa, el sistema intenta entregar la preferencia de cuota más reciente.

Esta es una respuesta de ejemplo.

"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"
    }
]

En esta salida, se incluyen los siguientes valores:

• PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.

Solicitar aumentos de cuota de grupos

Para solicitar que aumenten un grupo de cuotas en un proyecto nuevo, almacena las cuotas preferidas para el proyecto nuevo en un archivo CSV que cuente con los siguientes valores: nombre del servicio, ID de cuota, valor de cuota preferido y dimensiones.

Para cada fila del archivo CSV, lee el contenido en los campos serviceName, quotaId, preferredValue y 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);

Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto.

Como el proyecto de destino es nuevo, se recomienda llamar al método CreateQuotaPreference mientras lees y asignas los campos por motivos de seguridad. También puedes llamar al método UpdateQuotaPreference con allow_missing configurado como true.

El método buildYourOwnQuotaPreferenceId compila un ID de preferencia de cuota en base al nombre del servicio, el ID de cuota y un mapa de dimensiones según tu esquema de nombres. Otra opción es no configurar el ID de preferencia de cuota. Se genera un ID de preferencia de cuota para ti.

Obtén información sobre las cuotas de una dimensión específica del servicio

La familia de GPU es una dimensión específica del servicio. En la siguiente solicitud de ejemplo, se usa el ID de cuota GPUS-PER-GPU-FAMILY-per-project-region para obtener el recurso QuotaInfo.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto.

Esta es una respuesta de ejemplo. Para cada clave gpu_family única, quotaValue y applicableLocations son diferentes:

"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"
        ]
    }
]

En esta salida, se incluyen los siguientes valores:

• PROJECT_NUMBER: Un identificador único generado de forma automática para tu proyecto.

Crear una preferencia de cuota para una dimensión específica del servicio

En el siguiente ejemplo, se muestra cómo crear una cuota para una región y familia de GPU determinadas con un valor preferido de 100. La ubicación de segmentación se especifica en el mapa de dimensiones con la clave region y la familia GPU de destino con la clave gpu_family.

En el siguiente CreateQuotaPreference ejemplo, se especifica una familia de GPU deNVIDIA_H100 y una región deus-central1. Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto.

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"
        }
    ],
}

Para ajustar las dimensiones de tu preferencia de cuota, puedes hacer lo siguiente:

• Si quieres crear un QuotaPreference para las GPU de NVIDIA_H100 en todas las regiones, quita el mapa region del mapa de dimensiones.
• Para crear un QuotaPreference para todas las familias de GPU en la región us-central1, quita el mapa gpu_family del mapa de dimensiones.

Actualiza una preferencia de cuota para una dimensión específica del servicio

El siguiente código de muestra tiene el valor actual por las dimensiones {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} y, luego, establece el valor preferido para duplicarlo. Reemplaza PROJECT_NUMBER por el número de proyecto para tu proyecto.

// 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);

¿Qué sigue?

• Acerca de la API de Cloud Quotas

• Referencia de la API de Cloud Quotas

• Comprende las cuotas