Google Cloud adota versões imutáveis por data na API do Compute Engine

O que muda na API do Compute Engine

Desde 14 de novembro de 2026, o Google Cloud↳Google Cloud13 conteúdosPrograma da Google Cloud no Brasil projeta formar de forma gratuita 30 mil universitáriosDev (Back & Front) · mar 2026Google Cloud OnBoard capacita estudantes e desenvolvedores de TIGestão Dev & TI · mai 2019Desenvolvedores poderão participar de treinamento gratuito do Google CloudGestão Dev & TI · mai 2019Ver tudo em DevSecOps → oferece multi-versionamento da API do Compute Engine em todas as regiões, segundo o InfoQ. Ao lado do histórico /v1, agora existem versões estáveis identificadas por data, no formato YYYY-MM-DD, lançadas a cada trimestre. A primeira é 2026-09-01; a versão preview mais recente, 2026-10-01-preview, também já está disponível.

Versões preview carregam o sufixo -preview e têm vida útil de um ano. O caminho da API continua o mesmo, /compute/v1/: quem quer uma versão específica define o header X-Goog-Api-Version ou o parâmetro de query $apiVersion. Uma chamada que não informa versão nenhuma continua caindo no /v1, que o Google não anunciou quando vai desativar.

Por que o /v1 virou um problema

O engenheiro de software Michael Murstein, autor do anúncio no blog do Google Cloud, explica que o /v1 era uma superfície única e mutável, compartilhada por todo cliente da API no mundo.

Era uma única superfície de produção mutável, compartilhada por todo cliente no mundo.

Michael Murstein, engenheiro de software, Google Clouda single, mutable production surface shared by every customer worldwide

Qualquer melhoria de comportamento nessa superfície, mesmo trocar um default contraintuitivo ou modernizar o formato de um erro, arriscava quebrar scripts existentes ou exigia migração de anos. O substituto é o que o Google chama de versionamento baseado em interface, alinhado à sua própria AIP-185, que exige que versões estáveis sejam datas e que previews tenham prazo de validade. Cada versão estável é um snapshot travado de todos os recursos e defaults disponíveis naquela data: depois de publicada, não recebe mudança que quebre comportamento.

As três diferenças que já aparecem

O anúncio lista três mudanças concretas que quem troca de versão vai notar:

• Default de resultado parcial: no /v1, AggregatedList só retorna resultado parcial se a chamada definir returnPartialSuccess; nas versões datadas, esse comportamento já vem ligado, então uma zona com falha não derruba mais a consulta inteira da frota.
• Erro estruturado: o corpo de erro passa a ser google.rpc.ErrorInfo, com reason, domain e metadata; pedir uma versão inexistente retorna, no metadata, a lista das versões que existem.
• Permissões mais estritas: segundo Murstein, as novas versões permitem apertar checagens de IAM legadas e amplas demais, adotar defaults de configuração mais seguros e começar a mover esquemas de recurso com dez anos de idade na direção das Google API Improvement Proposals. Automação presa ao /v1 não recebe nada disso.

O que muda nas ferramentas que o time já usa

Quem chama a API diretamente é minoria: a maior parte vai sentir a mudança pelas bibliotecas e ferramentas que já usa, sem mexer em header nenhum.

Cada lançamento das bibliotecas cliente para Python↳Python56 conteúdosVSCode + Python + Alexa: Desenvolva e teste skills para alexa localmente com pythonDev (Back & Front) · out 2025Dominando decoradores em Python: um guia completo com exemplosDev (Back & Front) · jan 2025Desenvolvimento de software: diferenças entre Python, JavaScript e JavaGestão Dev & TI · nov 2024Ver tudo em Dev (Back & Front) →, Go, Java, Node.js, C#, Ruby e PHP passa a mirar uma versão datada específica, mantendo os mesmos namespaces compute_v1 e apiv1: nenhum caminho de import muda. Lançamentos -preview dos SDKs miram as versões preview. O gcloud compute aponta para a versão estável empacotada, e um novo grupo gcloud preview compute aponta para a preview; scripts existentes com compute, beta e alpha continuam funcionando sem alteração. No Terraform, o provider google mira versões estáveis e o google-beta mira preview, sem precisar declarar versão no HCL. Documentos de descoberta (discovery documents) são publicados por versão.

Google chega por último entre as três grandes nuvens

Com este lançamento, o Google é o último dos três maiores provedores de nuvem a deixar quem chama a API escolher a versão por requisição.

A cadência trimestral do Google fica entre o ritmo por serviço da Azure e o ritmo mensal da Stripe. Diferente da Stripe, porém, o Google não disse quais versões trimestrais vão trazer mudança de comportamento em relação à anterior.

O que ainda fica em aberto

O anúncio não traz data de fim de vida para o /v1, nem caminho formal para uma versão preview virar estável. Também não há lista completa das diferenças de comportamento entre /v1 e 2026-09-01 além dos três exemplos citados, nem posição sobre se outras APIs do Google Cloud vão adotar o mesmo esquema. Os canais /beta e /alpha não são mencionados no material.

Para quem roda infraestrutura GCP no Brasil

Quem provisiona Compute Engine via Terraform, gcloud ou uma das bibliotecas cliente oficiais não precisa fazer nada imediato: a ferramenta já decide a versão por trás. Em resumo: o risco concentra-se em quem chama a API REST diretamente, com curl ou HTTP client próprio, sem versão fixada, porque essas chamadas continuam presas ao /v1 e não ganham os novos defaults nem a proteção de IAM mais estrita.

Vale testar o novo default do returnPartialSuccess antes de migrar: times que dependem de uma consulta AggregatedList falhar por completo diante de uma zona fora do ar (para disparar alerta, por exemplo) podem ter esse comportamento alterado silenciosamente ao trocar de versão. Da mesma forma, revisar as permissões de IAM que o time concedeu para automação de Compute Engine antes de adotar 2026-09-01 evita surpresa quando o Google apertar checagens legadas. Para quem já testa a versão preview 2026-10-01-preview, vale lembrar do prazo de um ano de validade e acompanhar o canal oficial do Google Cloud para saber quando ela deixa de existir.

Fonte

InfoQ: Google Cloud Moves the Compute Engine API to Immutable Date-Based Versions, por Steef-Jan Wiggers, 14 de novembro de 2026.

Fonte: InfoQ