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:

  • En la mayoría de los casos, los ajustes de aumento de cuota deben realizarse a nivel de proyecto. Una cantidad limitada de productos admite ajustes de aumento de cuota a nivel de la organización. Para ver si un producto de Google Cloud admite ajustes de aumento de cuota a nivel de la organización, consulta la documentación de ese producto.

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

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

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 recurso QuotaInfo de tu servicio para determinar el quotaValue actual. 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 CPUs 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 se puede iniciar 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 primero 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 proyecto para tu proyecto.

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

    El campo allow_missing se establece como true. Esto le indica 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" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}

    Reemplaza lo siguiente:

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

  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"

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

    Reemplaza lo siguiente:

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

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

    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. 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 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) se reemplaza por el número de proyecto de destino (PROJECT_NUMBER2).

    • service, quotaId, preferredValue, dimensions: Estos campos se pueden tomar directamente de la respuesta tal como está.

    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

    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)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .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 una cadena opcional que explica tu solicitud.
  • EMAIL: Una dirección de correo electrónico que se puede usar como contacto, en caso de que Google Cloud necesite más informació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"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

Reemplaza lo siguiente:

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

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

Reemplaza PROJECT_NUMBER por el identificador único de tu proyecto.

¿Qué sigue?