Información general sobre la API Cloud Quotas

La API Cloud Quotas te permite ajustar mediante programación las cuotas a nivel de proyecto y automatizar las solicitudes de ajuste de cuotas a nivel de proyecto. Por ejemplo, puedes usar la API Cloud Quotas para hacer lo siguiente:

• Automatizar los ajustes de cuota: puedes usar la API Cloud Quotas para solicitar ajustes de cuota en función de tus propios criterios. Por ejemplo, para evitar errores de cuota superada, puedes usar la API para solicitar de forma programática un ajuste de cuota cuando los recursos de Compute Engine alcancen el 80% de la cuota disponible.

• Reutilizar configuraciones de cuota en varios proyectos: la API Cloud Quotas puede clonar tus configuraciones de cuota de un proyecto a otro. Si hay un conjunto conocido de cuotas que deben aumentarse en cada proyecto nuevo de Google Cloud , puedes usar la API Cloud Quotas para automatizar este proceso en la lógica de creación de tu proyecto. Las solicitudes de ajuste de cuota están sujetas a Google Cloud aprobación.

• Atender solicitudes de cuota de clientes: si eres un proveedor de SaaS integrado conGoogle Cloud, es posible que recibas solicitudes de aumento de cuota a través de un portal orientado al cliente que no sea la consola de Google Cloud . Estas solicitudes deben enviarse a Google Cloud para que se procesen. La API Cloud Quotas puede reenviar automáticamente las solicitudes de los clientes.

• Habilita el control de versiones de la configuración del cliente: la API Cloud Quotas es declarativa. Puedes tratar las configuraciones de cuota como código y almacenarlas en tu propio sistema de control de versiones para consultar el historial y revertir los cambios.

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.

Punto final de servicio

El endpoint de servicio es una URL base que especifica la dirección de red de un servicio de API. Un servicio puede tener varios endpoints. El servicio de la API Cloud Quotas tiene el siguiente endpoint y todos los URIs son relativos a él:

https://cloudquotas.googleapis.com

Roles obligatorios

Para obtener los permisos que necesitas para acceder a los recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos y cloudquotas_quotaAdjusterSettings, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de cuotas de Cloud (cloudquotas.admin) en el proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para acceder a los recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos y cloudquotas_quotaAdjusterSettings. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Se necesitan los siguientes permisos para acceder a los recursos cloudquotas_quotaPreferences, cloudquotas_quotaInfos y cloudquotas_quotaAdjusterSettings:

• cloudquotas.quotas.update
• cloudquotas.quotas.get
• monitoring.timeSeries.list
• resourcemanager.projects.get
• resourcemanager.projects.list

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Modelo de recursos de la API

El modelo de recursos de la API Cloud Quotas consta de dos recursos: QuotaPreference y QuotaInfo.

Preferencia de cuota

El recurso QuotaPreference representa tu preferencia de cuota para una combinación de dimensiones concreta. Usa este recurso para ajustar las cuotas de tus proyectos, carpetas u organizaciones.

Definir un valor preferido para una región

En el siguiente ejemplo se muestra un recurso QuotaPreference en un método CreateQuotaPreference.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

El preferredValue de 100 indica que el solicitante quiere que la cuota de GPUS-PER-GPU-FAMILY-per-project-region se establezca en ese valor. El campo "dimensions" indica que la preferencia solo se aplica a la región us-central1.

Verificar el valor concedido

Consulta tu preferencia de cuota y el campo grantedValue para verificar el valor concedido.

Para ver tu preferencia de cuota con la CLI de Google Cloud, ejecuta lo siguiente en tu terminal:

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

Haz los cambios siguientes:

• QUOTA_PREFERENCE_ID: el ID de tu preferencia de cuota. Es el valor que se especificó cuando se creó la preferencia de cuota.
• PROJECT: el ID o el número de tu proyecto de Google Cloud.

Si has enviado una solicitud de ajuste de cuota y se ha aprobado parcialmente, aparecerá el campo stateDetail después del campo grantedValue. El grantedValue muestra el ajuste que se ha realizado y el campo stateDetail describe el estado parcialmente aprobado.

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 los siguientes fragmentos de código se muestran ejemplos del objeto de preferencia de cuota. Usan una preferencia de cuota de demostración con el ID compute_googleapis_com-gpus-us-central1.

gcloud

Si consulta su preferencia de cuota mediante la CLI de gcloud, el resultado será similar al siguiente:

createTime: '2023-01-15T01:30:15.01Z'
dimensions:
    region: us-central1
name: projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1
quotaConfig:
    granteddValue: '100'
    preferredValue: '100'
    traceId: 123acd-345df23
    requestOrigin: ORIGIN_UNSPECIFIED
service: compute.googleapis.com
quotaId: GPUS-PER-GPU-FAMILY-per-project-region
updateTime: '2023-01-16T02:35:16.01Z'

REST

Si consultas tu preferencia de cuota mediante la API Cloud Quotas, el resultado será similar al siguiente:

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

Esta salida incluye los siguientes valores:

• PROJECT_NUMBER: un identificador único generado automáticamente para tu proyecto.

La respuesta muestra un grantedValue de 100, lo que significa que el preferredValue del ejemplo anterior se ha aprobado y completado. Las preferencias de las distintas dimensiones son QuotaPreference recursos diferentes. Por ejemplo, QuotaPreference para la CPU en las regiones us-central1 y us-east1 son dos recursos distintos.

Es obligatorio indicar la preferencia de cuota

Los recursos QuotaPreference se usan para indicar el valor que prefieres para una cuota concreta. El valor actual de una cuota concreta se basa en lo siguiente:

• QuotaPreference solicitudes que has hecho.

• Solicitudes de aumento de cuota aprobadas por Google Cloud.

• Cambios en las cuotas iniciados por Google Cloud.

No se puede eliminar un QuotaPreference. Sin embargo, puedes definir un valor de cuota preferido inferior al Google Cloud valor aprobado para añadir más medidas de protección.

Para obtener más información sobre el recurso QuotaPreference, consulta la referencia de la API Cloud Quotas.

Para obtener más información sobre las consultas QuotaPreference, consulta el artículo Implementar casos prácticos habituales.

Información sobre la cuota

QuotaInfo es un recurso de solo lectura que proporciona información sobre una cuota concreta de un proyecto, una carpeta o una organización. Muestra información sobre las cuotas definidas por los servicios y los ajustes de cuota completados que hayan iniciado los clientes. Google Cloud El recurso QuotaInfo contiene información como los metadatos, el tipo de contenedor y la dimensión.

Nota: Los recursos QuotaInfo se crean incorporando información de diferentes fuentes. Existe una configuración de cuota predeterminada incluso en el caso de que no se haya definido ningún QuotaPreference. Hasta que el cliente envíe un estado elegido mediante un comando quotaPreference.create o quotaPreference.patch, el recurso QuotaInfo se basa en la información de cuota predeterminada disponible.

Definir valores de cuota diferentes por región

En el siguiente ejemplo de recurso QuotaInfo se muestra que la cuota de CPU del proyecto es de 200 para la región us-central1 y de 100 para el resto de las regiones.

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

Esta salida incluye los siguientes valores:

• PROJECT_NUMBER: un identificador único generado automáticamente para tu proyecto.

Definir una cuota global

En el siguiente ejemplo de recurso QuotaInfo se muestra una cuota de frecuencia con un intervalo de actualización por minuto. Las dimensiones están en blanco, lo que indica que se trata de una cuota global. Todas las cuotas que no tienen una dimensión de región o zona son globales.

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

Esta salida incluye los siguientes valores:

• PROJECT_NUMBER: un identificador único generado automáticamente para tu proyecto.

Para obtener más información sobre el recurso QuotaInfo, consulta la referencia de la API Cloud Quotas.

Para obtener más información sobre las consultas QuotaPreference, consulta el artículo Implementar casos prácticos habituales.

Configuración del ajustador de cuotas

El recurso QuotaAdjusterSettings (Vista previa) representa los ajustes del modificador de cuota de un proyecto concreto. Cuando está habilitado, el ajustador de cuotas monitoriza el uso que haces de los recursos especificados y emite solicitudes de ajuste de cuota cuando el uso de los recursos se acerca al valor de la cuota.

• Para ver los ajustes actuales del ajustador de cuotas de un proyecto, usa una operación GET para obtener el recurso QuotaAdjusterSettings.

• Para habilitar el ajustador de cuotas en un proyecto, usa una operación PATCH para definir las siguientes opciones de recursos QuotaAdjusterSettings:

    "quota_adjuster_settings" :{
       "name": "projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings",
       "enablement": ENABLED,
  }
  

  Sustituye PROJECT_NUMBER por el identificador único de tu proyecto.

Para obtener más información, consulta los artículos Habilitar el ajustador de cuotas y Inhabilitar el ajustador de cuotas.

Nombres de recursos

Los recursos son entidades con nombre y se identifican por sus nombres. Los nombres de recursos se usan en todas las solicitudes y respuestas, y cada recurso debe tener su propio nombre de recurso único. Cada nombre de recurso se codifica mediante un conjunto de campos.

Recurso de preferencia de cuota

La convención de nomenclatura de un recurso QuotaPreference sigue el siguiente patrón:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Puedes definir el quotaPreferenceId al crear una preferencia de cuota. De lo contrario, se generará un ID. Se recomienda que un quotaPreferenceIdesquema de nomenclatura codifique el nombre del servicio, el ID de cuota, la ubicación y otras dimensiones. El quotaPreferenceId debe ser único en el proyecto, la carpeta o las organizaciones.

Por ejemplo, quotaPreference Un patrón para codificar tu ID de preferencia de cuota es el siguiente:

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

En el siguiente ejemplo se muestra este patrón:

compute_us-central1_nvidia-200

El campo location de un nombre de recurso siempre es global. La API Cloud Quotas es un servicio global.

Con un nombre de recurso, debes usar el método GET para recuperar un QuotaPreference. También puedes llamar al método PATCH con la opción allow_missing habilitada para crear o actualizar un QuotaPreference.

Recurso de información de cuota

La convención de nomenclatura de un recurso QuotaInfo sigue el siguiente patrón:

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

Recurso de configuración de ajuste de cuota

La convención de nomenclatura de un recurso QuotaAdjusterSettings sigue el siguiente patrón:

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

Siguientes pasos

• Implementar casos prácticos habituales

• Referencia de la API Cloud Quotas

• Información sobre las cuotas