Un AggregatedList que hoy falla entero porque una sola zona tiene problemas pasará a devolver lo que sí responde, pero solo si tu cliente pide la versión nueva de la API. Desde el 5 de noviembre de 2026, Compute Engine ofrece en disponibilidad general versiones de API fechadas e inmutables, y la primera estable, 2026-09-01, es un contrato que Google se compromete a no romper.
Para quien automatiza flotas de VMs con scripts, SDK o Terraform, el cambio importa por dos motivos: los valores por defecto ya pueden evolucionar sin sorpresas para /v1, y una actualización del SDK pasa a ser también un cambio de versión de la API.
De canales a versiones con fecha
Hasta ahora Compute Engine evolucionaba por canales de larga vida (/v1, /beta y /alpha) que recibían cambios en el sitio. Google lo llama versionado por canal (CBV) y lo sustituye por versionado por interfaz (IBV), alineado con la AIP-185:
| Tipo | Formato | Cadencia | Vida |
|---|---|---|---|
| Estable | 2026-09-01 | Trimestral, desde 2026-09-01 | Sin cambios incompatibles tras publicarse; sin fecha de fin de soporte |
| Preview | 2026-10-01-preview | Cuando haga falta | Un año |
/v1 | Sin cambios | — | Sigue soportada y es la versión por defecto |
La guía de versionado matiza dos cosas: las versiones estables se mantienen "a perpetuidad" bajo la política de deprecación estándar de Google Cloud, y las novedades que lleguen por IBV no estarán disponibles en /v1. Migrar no es obligatorio, pero quedarse en /v1 significa quedarse sin lo que venga.
Qué cambia al pedir una versión fechada
Google pone tres ejemplos de comportamiento que /v1 no puede tocar sin romper a nadie:
- Listados globales tolerantes a fallos. En
/v1,AggregatedListtienereturnPartialSuccessafalsepor defecto, así que un problema en una zona tumba la consulta de toda la flota. En las versiones fechadas la respuesta parcial viene activada. - Errores estructurados. Las respuestas de error siguen la AIP-193, con
google.rpc.ErrorInfoy camposreason,domainymetadata. Si pides una versión que no existe,metadataincluyesupported_versions. - Seguridad. Las versiones nuevas pueden endurecer comprobaciones de IAM que eran demasiado amplias e introducir valores por defecto más seguros.
Cómo elegir la versión
La ruta base sigue siendo /compute/v1/; la versión va en la cabecera X-Goog-Api-Version o en el parámetro $apiVersion:
curl -X GET \
"https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Goog-Api-Version: 2026-09-01"Cada versión tiene su propio documento de descubrimiento, por ejemplo https://www.googleapis.com/discovery/v1/apis/compute/2026-09-01/rest. En el resto de herramientas no hay que tocar código:
- SDK (Python, Go, Java, Node.js, C#, Ruby, PHP): cada release se ata a una versión fechada y conserva el espacio de nombres
v1(compute_v1,apiv1), sin cambiar imports. - gcloud:
gcloud computeusa la versión estable incluida y el nuevo grupogcloud preview computeusa la preview. Los scripts conbetayalphasiguen funcionando. Basta congcloud components update. - Terraform: el proveedor
googleapunta a las versiones estables ygoogle-betaa las preview; solo hay que subir la versión del proveedor, sin configurar nada en HCL.
La versión usada queda registrada en Cloud Audit Logs, en protoPayload.requestMetadata.callerSuppliedUserAgent, lo que permite auditar qué automatizaciones siguen en /v1.
Azure lo hace así desde siempre, pero obligatorio
El modelo recuerda al de Azure Resource Manager, donde cada petición lleva un parámetro api-version con fecha (2016-02-01, 2014-04-01-preview). La diferencia es que en Azure ese parámetro es obligatorio, y en Compute Engine es opcional y, si no lo pones, sigues en /v1. Es un camino de adopción más suave, con un coste: puedes pasar años sin saber que tu código no recibe las mejoras.
La trampa: la versión viaja con la librería
Si actualizas el SDK o el proveedor de Terraform, cambias de versión de API y heredas sus nuevos valores por defecto. El caso de returnPartialSuccess es el que más me preocupa: un script de inventario o de limpieza que asumía que el listado era completo (o fallaba) ahora puede recibir una lista a la que le falta una zona sin que nada falle. Si ese script decide qué borrar o recrear comparando con un estado esperado, una respuesta parcial puede acabar en una acción equivocada. Antes de subir la librería, revisa dónde usas listados agregados, fija la versión del SDK en tus dependencias y prueba con la preview en un proyecto que no sea de producción.
Fuentes
- Introducing Compute Engine API multi-versioning, Google Cloud Blog, 5 de noviembre de 2026.
- Compute Engine API Versioning Guide, documentación de Google Cloud.
- Azure REST API reference, Microsoft Learn.