Compute Engine API 날짜 기반 버전 정리: Terraform·SDK 점검 포인트

3줄 요약

• Compute Engine API에 날짜로 이름 붙은 불변(immutable) 버전이 정식 출시되었습니다. 첫 안정 버전은 2026-09-01이고, 기존 /v1은 종료일 없이 유지됩니다 ^[1].
• 날짜 버전에서는 AggregatedList 부분 결과 기본값, 오류 응답 형식, IAM 권한 검사가 /v1과 다르게 동작할 수 있습니다 ^[1].
• 대부분의 사용자는 헤더를 직접 쓰기보다 클라이언트 라이브러리, gcloud, Terraform provider 업그레이드를 통해 이 변화를 겪게 됩니다 ^[1].

무엇이 바뀌었나

Google Cloud는 Compute Engine API의 다중 버전 지원을 정식(GA)으로 제공하기 시작했습니다. 오래 쓰여 온 /v1 옆에 날짜가 찍힌 불변 버전이 추가된 구조입니다 ^[1]. 안정 버전은 YYYY-MM-DD 형식의 이름으로 분기마다 나오고, 프리뷰 버전은 -preview 접미사가 붙으며 수명이 1년입니다 ^[1].

버전 선택은 경로가 아니라 요청 단위로 합니다. 경로는 그대로 /compute/v1/을 쓰고, X-Goog-Api-Version 헤더나 $apiVersion 쿼리 파라미터로 원하는 버전을 지정합니다 ^[1]. 아무 버전도 지정하지 않은 요청은 계속 /v1으로 처리됩니다 ^[1].

배경은 /v1이 전 세계 모든 고객이 함께 쓰는 하나의 변경 가능한 표면이었다는 점입니다. Google 엔지니어 Michael Murstein의 설명에 따르면, 직관에 어긋나는 기본값 하나를 고치는 일조차 기존 스크립트를 깨뜨릴 위험이 있었습니다 ^[1]. Google은 이를 인터페이스 기반 버전 관리라고 부르며 자사 API 설계 지침인 AIP-185에 맞췄습니다 ^[1]. 각 안정 버전은 해당 날짜 시점의 GA 기능과 기본값을 고정한 스냅샷이고, 공개 후에는 호환성을 깨는 변경이 들어가지 않습니다 ^[1].

운영 관점에서 볼 점

동작 차이 세 가지. 발표에서 언급된 차이는 다음과 같습니다 ^[1].

• 부분 결과: /v1의 AggregatedList는 returnPartialSuccess를 명시해야 부분 결과를 주지만, 날짜 버전은 이를 기본으로 켭니다. 한 존(zone)이 실패해도 전체 조회가 실패하지 않는 대신, 결과가 일부만 올 수 있다는 점을 스크립트가 처리해야 합니다.
• 오류 형식: 오류 본문이 reason, domain, metadata를 담은 구조화된 google.rpc.ErrorInfo로 바뀝니다. 오류 메시지 문자열을 파싱하는 자동화는 점검이 필요합니다. 존재하지 않는 버전을 요청하면 metadata에 사용 가능한 버전 목록이 담깁니다.
• 권한(보안): 새 버전에서는 지나치게 넓던 기존 IAM 권한 검사를 강화하고 더 안전한 기본값을 도입할 수 있다고 합니다. 반대로 /v1에 고정된 자동화는 이런 개선을 받지 못합니다.

도구 업그레이드가 곧 버전 변경입니다. Python, Go, Java, Node.js, C#, Ruby, PHP 클라이언트 라이브러리는 릴리스마다 하나의 날짜 버전에 묶입니다. import 경로(compute_v1, apiv1)는 그대로라 코드 변경 없이도 동작이 바뀔 수 있습니다 ^[1]. gcloud의 compute는 번들된 안정 버전을, 새 gcloud preview compute 그룹은 번들된 프리뷰를 대상으로 합니다 ^[1]. Terraform은 google provider가 안정 버전, google-beta가 프리뷰를 대상으로 하며 HCL에 버전 설정 항목은 없습니다 ^[1]. 즉 버전 통제는 provider와 SDK 버전 고정으로 해야 합니다.

아직 확인되지 않은 것. /v1 종료일, 프리뷰가 안정 버전이 되는 경로, /v1과 2026-09-01 간 전체 동작 차이 목록, 다른 Google Cloud API로의 확대 여부는 공개되지 않았습니다. /beta, /alpha 채널에 대한 언급도 없습니다 ^[1]. 어떤 분기 버전이 이전 버전 대비 호환성을 깨는지도 밝히지 않았습니다 ^[1]. 비용 관련 내용은 자료에 없습니다.

적용해 보려면

1. 클라이언트 라이브러리, gcloud, Terraform provider가 어떤 버전으로 고정되어 있는지 확인하고, 업그레이드를 API 동작 변경으로 취급해 검증 단계를 둡니다 ^[1].
2. AggregatedList를 쓰는 스크립트에서 부분 결과와 실패 존 정보를 처리하는지 확인합니다 ^[1].
3. 오류 메시지 문자열에 의존하는 로직을 ErrorInfo의 reason, domain 기반으로 바꿀 수 있는지 검토합니다 ^[1].
4. 직접 REST를 호출한다면 X-Goog-Api-Version 헤더나 $apiVersion으로 2026-09-01을 지정해 비교 테스트합니다. 현재 2026-09-01과 2026-10-01-preview는 모든 리전에서 쓸 수 있습니다 ^[1].
5. 프리뷰 버전을 쓰는 경우 1년 수명을 감안해 교체 일정을 잡습니다 ^[1].

정리

이번 변경으로 Google은 3대 클라우드 중 마지막으로 요청 단위 API 버전 고정을 제공하게 되었습니다. Azure Resource Manager는 처음부터 날짜형 api-version을 요구해 왔고, AWS는 요청 단위 선택을 노출하지 않습니다 ^[1]. 당장 /v1이 사라지지는 않지만, SDK와 provider 업그레이드만으로 기본값과 오류 형식, 권한 검사가 바뀔 수 있으므로 버전 고정과 업그레이드 검증 절차를 먼저 갖추는 것이 핵심입니다.

참고 자료

1. Google Cloud Moves the Compute Engine API to Immutable Date-Based Versions · InfoQ DevOps, 2026-11-14