Descripción general de la API de Cloud Quotas

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

  • Automatizar 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 nuevo de Google Cloud, 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 la aprobación de Google Cloud.

  • Entrega solicitudes de cuotas de clientes: Si eres un proveedor de SaaS integrado en Google 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:

  • 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 de 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 y cloudquotas_quotaInfos, 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 y cloudquotas_quotaInfos. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

Se requieren los siguientes permisos para acceder a los recursos cloudquotas_quotaPreferences y cloudquotas_quotaInfos:

  • 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

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

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

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

Próximos pasos