콘텐츠로 이동하기
개발 및 IT운영

Compute Engine API 다중 버전 관리 도입: 프로덕션 환경의 안정성을 유지하면서 예측 가능한 API 개선

2026년 11월 12일
https://storage.googleapis.com/gweb-cloudblog-publish/images/compute-engine-multi-version-hero.max-2500x2500.jpg
Michael Murstein

Software Engineer

지금 Gemini 을 사용해 보세요

비즈니스 현장에서 Google AI를 만나기 위한 첫걸음

지금 시작하기

*이 콘텐츠는 AI 번역 도구를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역에는 오류나 누락이 포함될 수 있습니다. 정확한 정보는 영문 원본을 참고해 주시기 바랍니다.

 

프로덕션 환경의 안정성을 유지하면서 인프라를 현대화하고 싶으신가요? 정식 버전으로 출시된 Compute Engine의 API 다중 버전 관리 기능을 사용하면 가능합니다. Compute Engine은 날짜 기반 API 버전을 통해 기존 /v1 API의 견고한 안정성을 유지하면서도 최신 API 동작 방식, 더욱 강력한 복원력을 제공하는 기본 설정, 개선된 개발자 경험을 정기적으로 제공할 수 있게 되었습니다.

10년이 넘는 기간 동안 Google Compute Engine /v1 API는 수백만 개의 가상 머신, Google Kubernetes Engine(GKE) 클러스터, 대규모 AI 인프라를 관리하는 핵심 컨트롤 플레인 역할을 해왔습니다. Google Cloud를 기반으로 솔루션을 구축하는 플랫폼팀과 개발자에게 단일 /v1 엔드포인트는 한 번 통합하면 수년간 안정적으로 작동한다는 중요한 이점을 제공했습니다.

그러나 클라우드 아키텍처의 규모와 복잡성이 커지면서 인프라팀은 점점 더 어려운 선택에 직면하게 되었습니다. 한편으로는 미션 크리티컬한 프로덕션 워크로드를 위해 절대적인 API 안정성과 엄격한 하위 호환성이 필요하지만 다른 한편으로 고객은 더욱 안전한 보안 기본 설정, 향상된 리전별 복원력, 기계 가독형 오류 모델, 선언형 구성에 적합한 최신 API를 더 빠르게 도입하길 원합니다. 단, 기존 API에 이러한 개선 사항을 직접 적용하면 기존 자동화가 중단될 위험이 있습니다. 새로운 버전 관리 모델을 사용하면 프로덕션 워크로드를 변경하지 않고도 원하는 일정에 따라 최신 API 동작 방식을 유연하게 도입할 수 있어 이러한 중단 위험을 방지할 수 있습니다.

Compute Engine을 위한 날짜 기반 API 버전

기존에 Compute Engine은 /v1(정식 버전), /beta, /alpha라는 세 가지 장기 운영 채널을 사용하는 채널 기반 버전 관리(CBV) 방식을 채택했습니다. /v1은 전 세계 모든 고객이 공유하며 동작 방식을 변경할 수 있는 단일 프로덕션 접점입니다. 따라서 직관적이지 않은 기본 설정을 변경하거나 오류 형식을 현대화하는 정도의 개선 사항도 기존 스크립트의 작동을 중단시킬 위험이 있었고, 경우에 따라 수년간의 마이그레이션이 필요했습니다.

Google AIP-185에 부합하는 인터페이스 기반 버전 관리(IBV)를 통해 Compute Engine은 /v1과 함께 변경 불가능한 날짜 기반 API 스냅샷을 도입합니다.

  • 안정화 버전(YYYY-MM-DD): 예측 가능한 분기별 일정(2026-09-01부터 시작)에 따라 출시되는 각 안정화 버전은 특정 시점에 정식 출시된 모든 Compute Engine 기능과 기본 동작 방식이 고정된 API 계약을 나타냅니다. 안정화 버전은 게시된 후 브레이킹 체인지가 적용되지 않으며 현재 지원 종료일이 정해져 있지 않습니다.

  • 프리뷰 버전(YYYY-MM-DD-preview): 2026-10-01-preview와 같이 빠른 주기로 출시됩니다. 안정화 버전에서 분기된 프리뷰 버전을 통해 개발자는 향후 제공될 기능과 API 설계를 사전에 체험해 볼 수 있습니다. 테스트와 의견 수렴을 위해 제공되며 수명 주기는 1년으로 정해져 있습니다.

  • 중단 없는 /v1 지원: 기존 /v1 API는 계속해서 완벽하게 지원되며, 날짜 기반 버전을 지정하지 않으면 기본 버전으로 사용됩니다. 기존 애플리케이션, 스크립트, 통합은 수정 없이 계속 작동합니다.

개발자를 위한 주요 이점

1. 안정성과 고객이 직접 제어하는 업그레이드

기존의 단일 버전 API에서 기본 동작 방식을 변경할 때는 플랫폼의 발전과 고객 환경의 안정성 사이에서 타협점을 찾아야 했습니다. 하지만 날짜 기반 다중 버전 관리를 사용하면 업그레이드 시점을 고객이 직접 결정할 수 있습니다.

  • 특정 API 계약에 버전 고정: REST를 직접 호출하거나 SDK를 사용하는 개발자는 2026-09-01과 같은 특정 버전 식별자를 지정하여 요청 및 응답 스키마가 변경되지 않도록 할 수 있습니다.

  • 원하는 일정에 따른 업그레이드: 새로운 분기별 안정화 버전에서 기본 설정이 업데이트되거나 리소스 스키마가 변경되면 출시 노트를 검토하고, 버전 문자열 하나만 변경하여 스테이징 환경에서 테스트한 후, 원하는 시점에 프로덕션 환경에 배포할 수 있습니다.

  • 일관된 리소스 URI: 날짜 기반 버전에서도 기준 URL 경로인 /compute/v1/을 계속 사용합니다. 대상 버전은 X-Goog-Api-Version HTTP 헤더 또는 $apiVersion 쿼리 매개변수를 통해 지정합니다. 즉, 리소스의 selfLink URI는 도구와 서비스 전반에서 일관되게 유지됩니다.

로드 중...

2. 더욱 안전한 기본 설정, 향상된 복원력, 최신 API 표준

Compute Engine은 동작 변경사항을 새로운 날짜 기반 버전에만 적용함으로써 클라우드 애플리케이션의 복원력과 보안을 강화하고 자동화를 간소화하는 개선사항을 제공하고 있습니다.

  • 기본적으로 복원력이 우수한 전역 쿼리: 기존 /v1에서 모든 영역과 리전에 걸쳐 AggregatedList를 호출하면 returnPartialSuccess의 기본값이 false로 설정됩니다. 따라서 호출자가 부분 성공을 명시적으로 허용하지 않는 한, 단일 영역에서 발생한 일시적인 문제로 인해 전역 목록 요청 전체가 실패할 수 있습니다. 새로운 날짜 기반 버전에서는 부분 성공이 기본으로 활성화되므로, 특정 영역에서 유지보수나 장애가 발생하더라도 전역 Fleet 쿼리는 안정적으로 작동합니다.

  • 실질적인 문제 해결에 도움이 되는 기계 가독형 오류(AIP-193): 날짜 기반 버전은 구조화된 reason, domain, 컨텍스트 metadata가 포함된 표준화된 google.rpc.ErrorInfo 페이로드를 채택하여 오류 문자열을 정규 표현식으로 파싱하는 취약한 방식에 의존할 필요가 없습니다. 가령 잘못된 버전 식별자를 요청하면 지원되는 버전 목록인 supported_versions가 반환됩니다.

  • 강화된 보안 및 최소 권한 원칙 준수: 새로운 API 버전을 사용하면 Compute Engine에서 지나치게 광범위한 기존 IAM 권한 검사를 강화하고 더욱 안전한 기본 구성 설정을 도입할 수 있습니다. 이때 /v1에서 실행되는 기존 자동화에는 영향을 주지 않습니다.

  • 선언형 구성에 적합한 간결한 API 설계: 다중 버전 관리는 10년 이상 사용해 온 복잡한 리소스 스키마를 최신 Google API 개선 제안서(AIP)에 맞게 발전시킬 수 있는 명확한 경로를 제공합니다.

3. 클라이언트 라이브러리, gcloud, Terraform 전반에 걸친 원활한 채택

REST API를 직접 호출하든 상위 수준의 도구를 통해 인프라를 관리하든 Compute Engine API 다중 버전 관리는 기존 워크플로에 지장을 주지 않도록 설계되었습니다.

접점

다중 버전 관리 작동 방식

개발자의 책임

클라이언트 라이브러리(Python, Go, Java, Node.js, C#, Ruby, PHP)

각 SDK 버전은 특정 날짜 기반 API 버전에 자동으로 연결되며, 기존 /v1 패키지 네임스페이스(compute_v1, apiv1)는 유지됩니다. enum은 문자열로 표현되어 원활한 상위 및 하위 호환성을 제공합니다.

평소처럼 클라이언트 라이브러리 종속 항목을 업그레이드하면 되며 가져오기 경로를 다시 작성할 필요가 없습니다. 프리뷰 기능을 테스트하려면 -preview SDK 버전을 사용하세요.

Google Cloud CLI(gcloud)

gcloud compute는 함께 제공되는 안정화 API 버전을 대상으로 합니다. 새로운 gcloud preview compute 명령어 그룹은 함께 제공되는 미리보기 API 버전을 대상으로 합니다.

gcloud를 최신 상태로 유지하세요. 기존 gcloud compute, beta, alpha 스크립트는 수정 없이 계속 작동합니다.

Terraform(google 및 google-beta)

google 제공업체는 날짜 기반 안정화 API를, google-beta는 내부적으로 프리뷰 API를 타겟팅합니다.

새로운 기능을 도입하려면 Terraform 제공업체 버전을 업그레이드하세요. HCL 스크립트에서 API 버전을 수동으로 구성할 필요는 없습니다.

직접 HTTP/REST 호출

-H "X-Goog-Api-Version: YYYY-MM-DD" 또는 ?$apiVersion=YYYY-MM-DD를 사용하여 현재 지원되는 버전 중 하나를 선택하고 버전별 탐색 문서를 가져올 수 있습니다.

HTTP 클라이언트에서 헤더나 쿼리 매개변수를 전달하여 2026-09-01, 2026-10-01-preview와 같은 특정 버전을 사용하세요.

시작하기

Compute Engine API 멀티 버전 관리는 현재 모든 Google Cloud 리전에서 사용할 수 있습니다. 최초 안정화 버전은 2026-09-01이고 프리뷰 테스트를 위한 2026-10-01-preview 버전도 제공됩니다.

다음 단계를 통해 워크플로에서 날짜 기반 버전을 살펴보고 도입해 보세요.

  1. 다음 문서를 살펴보세요.

  2. gcloud preview compute 사용해 보세요. gcloud components update를 실행한 다음 새로운 gcloud preview compute 명령어 그룹을 사용하여 향후 제공될 프리뷰 기능을 테스트해 보세요.

게시 위치