Descripción general de la API de Cloud Quotas

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

  • Automatiza los ajustes de cuota: Puedes usar la API de Cloud Quotas para solicitar ajustes de cuota según tus propios criterios. Por ejemplo, para evitar errores de cuota excedida, puedes usar la API para solicitar de manera programática un ajuste de cuota cuando los recursos de Compute Engine alcancen el 80% de la cuota disponible.

  • Reutiliza las configuraciones de cuotas en todos los proyectos: La API de Cloud Quotas puede clonar las configuraciones de cuotas de un proyecto a otro. Si hay un conjunto conocido de cuotas que debe aumentarse para cada proyecto Google Cloud nuevo, puedes usar la API de Cloud Quotas para automatizar esto en la lógica de creación de tu proyecto. Las solicitudes de ajuste de cuota están sujetas a Google Cloud aprobación.

  • Entrega solicitudes de cuotas de clientes: Si eres un proveedor de SaaS integrado enGoogle 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 se deben reenviar a Google Cloud para su procesamiento. La API de Cloud Quotas puede reenviar solicitudes de clientes de forma automática.

  • Habilita el control de versión de configuración del cliente: La API de Cloud Quotas es declarativa. Puedes tratar las configuraciones de cuota como código y almacenarlas en tu propio sistema controlado por versión para el historial y la reversión.

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.

Extremo de servicio

Un extremo de servicio es una URL base que especifica la dirección de la red de un servicio de API. Un servicio puede tener varios extremos. El servicio de la API de Cloud Quotas tiene el siguiente extremo, y todos los URI están relacionados con é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, pídele a tu administrador que te otorgue el rol de IAM de Administrador de Cloud Quotas (cloudquotas.admin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra 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 son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren 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 o con otros roles predefinidos.

Modelo de recursos de la API

El modelo de recursos de la API de 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 particular. Usa este recurso para ajustar las cuotas en tus proyectos, organizaciones o carpetas.

Establece 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 desea que la cuota GPUS-PER-GPU-FAMILY-per-project-region se establezca en ese valor. En el campo de dimensiones, se indica que la preferencia solo se aplica a la región us-central1.

Verifica el valor otorgado

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

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

gcloud alpha quotas preferences describe QUOTA_PREFERENCE_ID --project=PROJECT

Reemplaza lo siguiente:

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

Si realizaste una solicitud de ajuste de cuota y se aprueba de forma parcial, aparecerá un campo stateDetail después del campo grantedValue. grantedValue muestra el ajuste que se realizó, y el campo stateDetail describe el estado parcialmente aprobado.

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

En los siguientes fragmentos de código, se muestran ejemplos del objeto de preferencia de cuota. Usa una preferencia de cuota de demostración con el ID compute_googleapis_com-gpus-us-central1.

gcloud

Si ves tu preferencia de cuota con 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 ves tu preferencia de cuota con la API de Cloud Quotas, el resultado es 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"
}

En esta salida, se incluyen los siguientes valores:

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

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

La preferencia de cuota es obligatoria

Los recursos QuotaPreference se usan para indicar tu valor preferido para una cuota en particular. El valor actual de una cuota en particular se basa en lo siguiente:

  • QuotaPreference solicitudes que realizaste.

  • Solicitudes de aumento de cuota aprobadas por Google Cloud.

  • Cambios en las cuotas que inició Google Cloud.

No se admite la capacidad de borrar una QuotaPreference. Sin embargo, puedes establecer un valor de cuota preferido más bajo que el valor aprobado de Google Cloud para agregar más barreras de seguridad.

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

Para obtener más información sobre las consultas QuotaPreference, consulta Implementa casos de uso comunes.

Información de la cuota

QuotaInfo es un recurso de solo lectura que proporciona información sobre una cuota en particular para una carpeta, organizaciones o proyectos determinados. Muestra información de las cuotas definidas por los servicios de Google Cloud y cualquier ajuste de cuota completado que inicien los clientes. El recurso QuotaInfo contiene información como los metadatos, el tipo de contenedor y la dimensión.

Configura diferentes valores de cuota 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 100 para todas las demás 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"
            ]
        }
    ]
}

En esta salida, se incluyen los siguientes valores:

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

Configura 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 esta es una cuota global. Todas las cuotas sin 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"
            ]
        }
    ]
}

En esta salida, se incluyen los siguientes valores:

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

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

Para obtener más detalles sobre las consultas QuotaPreference, consulta Implementa casos de uso comunes.

Configuración del ajustador de cuotas

El recurso QuotaAdjusterSettings (Versión preliminar) representa la configuración del ajustador de cuotas para un proyecto en particular. Cuando está habilitado, el ajustador de cuotas supervisa el uso de los recursos especificados y emite solicitudes de ajuste de cuota cuando el uso de recursos se acerca a su valor de cuota.

  • Para ver la configuración actual del ajustador de cuotas de un proyecto, usa una operación GET para recuperar el recurso QuotaAdjusterSettings.

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

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

    Reemplaza PROJECT_NUMBER por el identificador único de tu proyecto.

Para obtener más información, consulta Habilita el ajustador de cuotas y Inhabilita el ajustador de cuotas.

Nombres de recursos

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

Recurso de preferencia de cuota

La convención de nombres para un recurso QuotaPreference usa el siguiente patrón:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Puedes configurar quotaPreferenceId cuando creas una preferencia de cuota; de lo contrario, se genera un ID. Se recomienda que un esquema de nombres quotaPreferenceId codifique el nombre del servicio, el ID de cuota, la ubicación y otras dimensiones. El quotaPreferenceId debe ser único para el proyecto, la carpeta o las organizaciones.

Como quotaPreference de ejemplo 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

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 la cuota

La convención de nombres para un recurso QuotaInfo usa el siguiente patrón:

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

Recurso de configuración del ajustador de cuotas

La convención de nombres para un recurso QuotaAdjusterSettings usa el siguiente patrón:

projects/PROJECT_NUMBER/locations/global/quotaAdjusterSettings

Próximos pasos