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

Cloud Quotas tiene las siguientes limitaciones:

• Los ajustes de aumento de cuota deben realizarse a nivel de proyecto y están sujetos a la aprobación de Google Cloud.

• Puedes solicitar ajustes de disminución de cuota para cuotas de nivel de project-, folder- y organización.

• La API de Cloud Quotas solo admite operaciones a nivel del proyecto. No se admiten las operaciones a nivel de carpeta y de organización.

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 en 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 proyecto para 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"
                   ]
               }
           ]
       },
       ...
   ]

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

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

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": { "region": "us-central1" }
   }

   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 proyecto para 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": { "region": "us-central1" },
   "reconciling": true,
   "createTime": "2023-01-15T01:30:15.01Z",
   "updateTime": "2023-01-16T02:35:16.01Z"

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

   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",
       "contactEmail": EMAIL
   }

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

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 proyecto para 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.

Un ejemplo de respuesta se ve de la siguiente manera:

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

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.

Solicita ajustes en las cuotas que no tienen uso

En el caso de las cuotas que aún no tienen uso de cuota y que tienen dimensiones específicas del servicio, como vm_family, es posible que esas cuotas no sean visibles en la consola de Google Cloud. Es posible que debas usar la API de Cloud Quotas en su lugar.

Por ejemplo, puedes clonar un proyecto y saber de antemano que debes aumentar el valor de compute.googleapis.com/gpus_per_gpu_family. Este valor solo aparece en la consola de Google Cloud para las familias de GPU que ya usaste. Para usar la API de Cloud Quotas y solicitar un aumento de las GPU NVIDIA_H100 en us-central1, puedes enviar una solicitud como la siguiente:

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" },
    "justification": "JUSTIFICATION",
    "contactEmail": "EMAIL"
}

Reemplaza lo siguiente:

• PROJECT_NUMBER: Es el identificador único de tu proyecto.
• JUSTIFICATION: Es el motivo de esta solicitud.
• EMAIL: Es una dirección de correo electrónico que se puede usar como contacto, en caso de que Google Cloud necesite más información para tomar una decisión antes de que se pueda otorgar una cuota adicional.

Para obtener más información, consulta también las descripciones de Prioridad de las dimensiones y Cómo combinar dimensiones.

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

Crea 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.

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

Reemplaza lo siguiente:

• PROJECT_NUMBER: Es el identificador único de tu proyecto.
• EMAIL: Es una dirección de correo electrónico que se puede usar como contacto, en caso de que Google Cloud necesite más información para tomar una decisión antes de que se pueda otorgar una cuota adicional.

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

En el siguiente código de muestra, se obtiene el valor actual de la dimensión {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, y, luego, se establece el valor preferido para duplicarlo.

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

Reemplaza PROJECT_NUMBER por el identificador único de tu proyecto.

¿Qué sigue?

• Acerca de la API de Cloud Quotas

• Referencia de la API de Cloud Quotas

• Comprende las cuotas