Guía de versiones de Compute Engine: APIs, bibliotecas cliente y herramientas

En esta guía, se explica cómo Compute Engine administra las versiones en las APIs de REST, las bibliotecas cliente y la herramienta de línea de comandos de gcloud. Describe la diferencia entre el control de versiones basado en canales (CBV) y el control de versiones basado en interfaces (IBV), y se enfoca principalmente en este último.

Antes de comenzar

  • Si aún no lo hiciste, configura la autenticación. La autenticación verifica tu identidad para acceder a los servicios y las APIs de Google Cloud . Para ejecutar código o muestras desde un entorno de desarrollo local, puedes autenticarte en Compute Engine seleccionando una de las siguientes opciones:

    Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:

    Console

    Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud , no necesitas configurar la autenticación.

    gcloud

    1. Instala Google Cloud CLI. Después de la instalación, inicializa Google Cloud CLI con el siguiente comando: 

      gcloud init

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  • Configura una región y una zona predeterminadas.

    • REST

    Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.

      Instala Google Cloud CLI.

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

    Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .

Control de versiones basado en canales y en interfaces

La API de Compute Engine admite dos esquemas de versiones: versiones basadas en canales (CBV) y versiones basadas en interfaces (IBV).

  • En el control de versiones basado en canales, las versiones son duraderas y reciben actualizaciones en el lugar. Compute Engine admite los canales v1, beta y alfa.

  • En el control de versiones basado en interfaces, se controlan las versiones de las interfaces, los métodos y los recursos individuales, y estos pueden evolucionar de forma incremental e independiente.

El IBV reemplaza al CBV. Sin embargo, las implementaciones existentes de CBV no se ven afectadas por la introducción de IBV ni por las versiones nuevas. Puedes seguir usando CBV si prefieres mantenerte en la versión existente de la API.

El IBV te ayuda a confiar en que el comportamiento de la API y su carga útil de solicitud y respuesta se ajustan a una versión de API prevista. Para usar IBV, debes especificar una versión de la API en tu solicitud, ya sea con un parámetro de consulta o un encabezado. Para obtener más información, consulta Crea una solicitud a la API.

El uso de IBV proporciona los siguientes beneficios:

  • Mayor estabilidad: IBV protege las aplicaciones en ejecución de los cambios, ya que te permite indicar la versión de la API con la que debe responder el servicio.
  • Control sobre la adopción de cambios: Con IBV, eliges qué versión responde a tu solicitud. Esto te permite actualizar a las nuevas funciones del servicio según tu propio cronograma.

Para obtener más información sobre las estrategias de versiones, consulta la propuesta 185 de mejora de la API.

Política de versiones basada en la interfaz

Cada versión de la API de IBV de Compute Engine es una colección de cambios en la interfaz que comparten la misma versión del servicio, aunque las interfaces pueden cambiar de versión de forma independiente.

La API de IBV de Compute Engine admite versiones estables y de vista previa.

Versiones estables

La mayoría de las versiones de la API son versiones estables. Las versiones estables mantienen una compatibilidad estricta, como se define en AIP-180, lo que significa que las versiones estables más recientes de la misma versión no interrumpen la funcionalidad existente ni requieren reescrituras de código.

Compute Engine identifica las versiones estables de la API con fechas estándar en formato YYYY-MM-DD (como 2026-09-01). Las fechas posteriores indican versiones más recientes.

Compute Engine admite versiones estables durante períodos prolongados para que tus sistemas de producción sigan siendo confiables y sin interrupciones. En la mayoría de las aplicaciones, solo necesitas usar una versión estable para realizar tus tareas diarias.

Versiones preliminares

Compute Engine puede lanzar versiones preliminares para recopilar comentarios anticipados de los usuarios sobre las nuevas funciones. Las versiones preliminares agregan una etiqueta -preview a la fecha (por ejemplo, 2026-10-01-preview).

Las versiones preliminares incluyen todas las capacidades de la versión estable más reciente, además de las funciones experimentales agregadas recientemente. Ten en cuenta lo siguiente cuando uses versiones preliminares:

  • Las funciones en versión preliminar no garantizan la compatibilidad con versiones anteriores o futuras.
  • No recomendamos usar versiones preliminares en entornos de producción críticos.
  • Es posible que cambiemos, mejoremos o quitemos funciones en versión preliminar mientras las promocionamos para un lanzamiento estable.

Usa las versiones preliminares cuando quieras experimentar con nuevas capacidades y planees actualizar tu código cuando se lance una versión estable.

Cómo especificar una versión de API en la solicitud

Para realizar llamadas a la API con IBV, tus solicitudes deben especificar una versión de destino con un parámetro de consulta o un encabezado. Para ver ejemplos de cómo realizar solicitudes a la API, consulta Crea una solicitud a la API.

Bibliotecas cliente de Cloud

Las bibliotecas cliente de Cloud eliminan la carga de compilar y analizar llamadas REST sin procesar. Cada versión de la biblioteca se conecta directamente a una versión específica de la API basada en la fecha.

Para acceder a las funciones nuevas, actualiza tu paquete de bibliotecas cliente de Cloud a la versión más reciente. Publicamos bibliotecas cliente de Cloud actualizadas junto con las nuevas versiones de API estables y en versión preliminar.

Recomendamos ejecutar aplicaciones de producción en bibliotecas cliente de Cloud estables y aislar las bibliotecas de versión preliminar en entornos de prueba.

Google Cloud CLI (gcloud)

La CLI de gcloud te permite administrar recursos de Compute Engine sin tener que hacer un seguimiento manual de los extremos de la API de REST individuales.

La CLI de gcloud divide los comandos en dos categorías:

  • Comandos estables: Los comandos estándares (como gcloud compute instances create) tienen como objetivo versiones de API estables. Estos comandos son totalmente compatibles, predecibles y recomendados para los secuencias de comandos de producción.
  • Comandos de vista previa: Las funciones de acceso anticipado usan el grupo gcloud preview (como gcloud preview compute ...). Estos comandos muestran una breve advertencia porque los contratos pueden cambiar antes del lanzamiento final.

Terraform

El proveedor de Terraform Google Cloud abstrae el control de versiones de la API y administra las interacciones subyacentes de la API. Las configuraciones de Terraform no exponen ni requieren parámetros de configuración manuales del encabezado de versión.

Para acceder a las funciones nuevas, actualiza tu proveedor de Google Cloud Terraform a la versión más reciente. Para las funciones de versión preliminar, usa el proveedor google-beta.

Preguntas frecuentes

En esta sección, se responden las preguntas frecuentes sobre el control de versiones de la API de Compute Engine.

  • ¿Tengo que migrar de la versión 1 (CBV) a la IBV?

    No, las solicitudes existentes de la API de CBV v1 siguen funcionando como antes. Sin embargo, no podrás acceder a las nuevas funciones disponibles en la API de IBV.

  • ¿Durante cuánto tiempo se admitirá una versión de la API de IBV?

    Las versiones estables se mantienen de forma perpetua según la política de baja estándar de Google Cloud.

  • ¿Con qué frecuencia se lanzan nuevas versiones de la API de IBV?

    Se planean nuevas versiones de la API de IBV con lanzamientos trimestrales. Las versiones preliminares se pueden lanzar en cualquier momento.

  • ¿Debo habilitar algo en la consola de Google Cloud ?

    No, la API de IBV está habilitada de forma predeterminada con la API de Compute Engine.

  • ¿Qué sucede si no especifico una versión en mi solicitud?

    Tu solicitud se establece de forma predeterminada en el extremo de la CBV v1.

  • ¿Dónde puedo encontrar la versión de la API en las entradas de los registros de auditoría de Cloud?

    La versión de la API se registra en protoPayload.requestMetadata.callerSuppliedUserAgent y en los encabezados de la solicitud o los parámetros de consulta.

¿Qué sigue?

Para obtener más información sobre la API de Compute Engine, consulta los siguientes documentos: