Implementar casos prácticos habituales

En este documento se describe cómo implementar casos prácticos habituales con la API Cloud Quotas. Esta API te permite ajustar de forma programática las cuotas y automatizar los ajustes de cuotas en tus Google Cloud proyectos, carpetas u organización.

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

Limitaciones

Cloud Quotas tiene las siguientes limitaciones:

  • En la mayoría de los casos, los ajustes de aumento de cuota deben hacerse a nivel de proyecto. Solo se pueden ajustar las cuotas de nivel de organización de un número limitado de productos. Para saber si un producto admite ajustes de aumento de cuota a nivel de organización, consulta la documentación de ese producto. Google Cloud

  • Puedes solicitar ajustes para reducir las cuotas a nivel de proyecto, de organización y de carpeta.

Monitorizar el uso y solicitar un aumento cuando supere el 80%

En este ejemplo, se monitoriza el uso de la cuota con Cloud Monitoring y, a continuación, se solicita un aumento cuando el uso supera el 80%.

  1. Llama al recurso QuotaInfo de tu servicio para determinar el actual quotaValue. El servicio de este ejemplo es compute.googleapis.com:

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

    Sustituye PROJECT_NUMBER por el número de tu proyecto.

  2. Para encontrar las CPUs por proyecto y las ubicaciones aplicables, busca el ID de cuota CPUS-per-project-region en la respuesta QuotaInfo. El valor de 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 Cloud Monitoring para consultar el uso de la cuota. En el siguiente ejemplo, se ha especificado la región us-central1. Las métricas de cuota admitidas se indican 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, gestiona la respuesta de la API Cloud Monitoring. Compara el valor de Cloud Monitoring con el quotaValue de los pasos anteriores para determinar el uso.

    En el siguiente ejemplo de respuesta, el valor de uso en Cloud Monitoring es 19 en la región us-central1. El quotaValue de todas las regiones es 20. El uso es superior al 80% de la cuota y se puede iniciar una actualización de las preferencias 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 primero para comprobar si hay alguna solicitud pendiente. 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

    Sustituye PROJECT_NUMBER por el número de tu proyecto.

  6. Llama a UpdateQuotaPreference para aumentar el valor de la cuota de la región us-central1. En el ejemplo siguiente, se ha especificado un nuevo valor preferido de 100.

    El campo allow_missing tiene el valor true. De esta forma, se le indica al sistema que cree un recurso QuotaPreference si no existe 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" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}

    Haz los cambios siguientes:

    • PROJECT_NUMBER: identificador único de tu proyecto.
    • JUSTIFICATION: cadena opcional que explica tu solicitud.
    • EMAIL: una dirección de correo que se pueda usar como contacto en caso de que Google Cloud necesite más información antes de poder conceder cuota adicional.

  7. Llama al GetQuotaPreference para comprobar el estado del cambio de preferencia de cuota:

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

    Sustituye PROJECT_NUMBER por el número de tu proyecto.

    Mientras Google Cloud evalúa el valor de cuota solicitado, el estado de conciliación de tu cuota se define como true.

    A veces, Google Cloud aprueba parte de tu solicitud de aumento en lugar de aprobar el aumento completo. Si la solicitud se aprueba parcialmente, la preferencia de cuota incluye un campo stateDetail. El campo stateDetail describe el estado parcialmente aprobado. El campo grantedValue muestra el ajuste que se ha realizado para completar parcialmente tu solicitud.

    Para ver si el valor concedido es el valor final aprobado, consulta el campo reconciling. Si tu solicitud aún está en proceso de evaluación, el campo reconciling se define como true. Si el campo reconciling se define como false o se omite, el valor concedido es el valor final aprobado.

    En el ejemplo siguiente, el valor de cuota solicitado es 100 y el campo reconciling indica que la solicitud está en proceso de revisión.

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

    Una vez que se haya procesado la preferencia de cuota, el campo reconciling se establecerá en false. El grantedValue es el mismo que el preferredValue. La cuota preferente se ha concedido por completo.

    Cuando Google Cloud rechaza o aprueba parcialmente una solicitud de un cliente, el valor de cuota concedido puede seguir siendo inferior al valor preferido.

Reducir una cuota

En el siguiente ejemplo se reduce el número de TPUs 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

    Sustituye PROJECT_NUMBER por el número de tu proyecto.

  2. Busca en los campos de respuesta 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 valor de quotaValue es 20.

  3. Reduce la cuota de TPU de cada región a 10 con un CreateQuotaPreferenceRequest. Define 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",
  "justification": "JUSTIFICATION",
  "contactEmail": "EMAIL"
}

    Haz los cambios siguientes:

    • PROJECT_NUMBER: identificador único de tu proyecto.
    • JUSTIFICATION: cadena opcional que explica tu solicitud.
    • EMAIL: una dirección de correo que se pueda usar como contacto en caso de que Google Cloud necesite más información antes de poder conceder cuota adicional.

  4. Confirma el nuevo valor de cuota con una llamada GetQuotaInfo que defina el 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

    Sustituye PROJECT_NUMBER por el número de tu proyecto.

    A continuación se muestra un ejemplo de respuesta. El valor de value es 10 y se aplica en 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 las preferencias de cuota en otro proyecto

En el siguiente ejemplo se copian todas las preferencias de cuota de un proyecto a otro. Está escrito en Java, pero puedes usar cualquier lenguaje de programación.

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

    GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences

    PROJECT_NUMBER1 es el número de proyecto del proyecto de origen. La respuesta contiene todas las preferencias de cuota del proyecto de origen.

  2. Para cada preferencia de cuota de 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) se sustituye por el número de proyecto de destino (PROJECT_NUMBER2).

    • service, quotaId, preferredValue y dimensions: estos campos se pueden tomar directamente de la respuesta tal cual.

    for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
  QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
      .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
      .setService(srcPreference.getService())
      .setQuotaId(srcPreference.getQuotaId())
      .setJustification(srcPreference.getJustification())
      .setContactEmail(srcPreference.getContactEmail())
      .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

    Sustituye PROJECT_NUMBER2 por el número del proyecto de destino.

Lista de 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

Sustituye PROJECT_NUMBER por el número de tu proyecto.

La respuesta a esta solicitud devuelve la última preferencia de cuota pendiente. Como la API Cloud Quotas es una API declarativa, el sistema intenta cumplir la preferencia de cuota más reciente.

Un ejemplo de respuesta tiene un aspecto similar al siguiente:

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

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

En cada fila del archivo CSV, lee el contenido de 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)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Sustituye PROJECT_NUMBER por el número de tu proyecto.

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

El método buildYourOwnQuotaPreferenceId crea un ID de preferencia de cuota a partir del nombre del servicio, el ID de cuota y un mapa de dimensiones según tu esquema de nomenclatura. También puede optar por no definir ningún ID de preferencia de cuota. Se genera un ID de preferencia de cuota.

Solicitar ajustes en cuotas que no se han usado

En el caso de las cuotas que aún no tienen uso y que tienen dimensiones específicas del servicio, como vm_family, es posible que no se muestren en la consola Google Cloud . Es posible que tengas que usar la API Cloud Quotas.

Por ejemplo, puedes clonar un proyecto y saber de antemano que tienes que aumentar el valor de compute.googleapis.com/gpus_per_gpu_family. Este valor solo aparece en la consola Google Cloud para las familias de GPUs que ya hayas usado. Para usar la API Cloud Quotas y solicitar un aumento de las GPUs 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"
}

Haz los cambios siguientes:

  • PROJECT_NUMBER: identificador único de tu proyecto.
  • JUSTIFICATION: cadena opcional que explica tu solicitud.
  • EMAIL: una dirección de correo que se pueda usar como contacto en caso de que Google Cloud necesite más información antes de poder conceder cuota adicional.

Para obtener más información, consulte también las descripciones de Precedencia de las dimensiones y Combinación de dimensiones.

Obtener información sobre la cuota de una dimensión específica de un servicio

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

Sustituye PROJECT_NUMBER por el número de 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"
        ]
    }
]

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

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

En el siguiente ejemplo de CreateQuotaPreference se especifica la familia de GPU NVIDIA_H100 y la región 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"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

Haz los cambios siguientes:

  • PROJECT_NUMBER: identificador único de tu proyecto.
  • JUSTIFICATION: cadena opcional que explica tu solicitud.
  • EMAIL: una dirección de correo que se pueda usar como contacto en caso de que Google Cloud necesite más información antes de poder conceder cuota adicional.

Actualizar una preferencia de cuota de una dimensión específica de un servicio

El siguiente código de ejemplo obtiene el valor actual de la dimensión {"region" : "us-central1"; gpu_family:"NVIDIA_H100"}, y, a continuación, asigna el doble de ese valor como valor preferido. Está escrito en Java, pero puedes usar cualquier lenguaje de programación.

// 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)
        .setJustification(justification)
        .setContactEmail(contactEmail)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

Sustituye PROJECT_NUMBER por el identificador único de tu proyecto.

Siguientes pasos