Compute Engine 버전 관리 가이드: API, 클라이언트 라이브러리, 도구

이 가이드에서는 Compute Engine이 REST API, 클라이언트 라이브러리, gcloud 명령줄 도구에서 버전을 관리하는 방법을 설명합니다. 여기에서는 채널 기반 버전 관리 (CBV)와 인터페이스 기반 버전 관리 (IBV)의 차이점을 설명하며 주로 후자에 중점을 둡니다.

시작하기 전에

  • 아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인합니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음 옵션 중 하나를 선택하여 Compute Engine에 인증하면 됩니다.

    이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

    콘솔

    Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.

    gcloud

    1. Google Cloud CLI를 설치합니다. 설치 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다. 

      gcloud init

      외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  • 기본 리전 및 영역을 설정합니다.

    • REST

    로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

      Google Cloud CLI를 설치합니다.

      외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

    자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

채널 기반 버전 관리 및 인터페이스 기반 버전 관리

Compute Engine API는 채널 기반 버전 관리 (CBV)와 인터페이스 기반 버전 관리 (IBV)라는 두 가지 버전 관리 스키마를 지원합니다.

  • 채널 기반 버전 관리에서 버전은 수명이 길고 현재 위치 업데이트를 받습니다. Compute Engine은 v1, 베타, 알파 채널을 지원합니다.

  • 인터페이스 기반 버전 관리에서는 개별 인터페이스, 메서드, 리소스가 버전 관리되며 점진적으로 독립적으로 발전할 수 있습니다.

IBV는 CBV를 대체합니다. 하지만 CBV의 기존 구현은 IBV 도입과 새 버전에 영향을 받지 않습니다. 기존 API 버전을 유지하고 싶다면 CBV를 계속 사용할 수 있습니다.

IBV를 사용하면 API의 동작과 요청 및 응답 페이로드가 의도한 API 버전을 준수하는지 신뢰할 수 있습니다. 요청에서 쿼리 매개변수나 헤더를 사용하여 API 버전을 지정하면 IBV를 사용할 수 있습니다. 자세한 내용은 API 요청 만들기를 참고하세요.

IBV를 사용하면 다음과 같은 이점이 있습니다.

  • 안정성 향상: IBV를 사용하면 서비스가 응답해야 하는 API 버전을 나타낼 수 있으므로 실행 중인 애플리케이션이 변경되지 않도록 보호할 수 있습니다.
  • 변경사항 채택 관리: IBV를 사용하면 요청을 처리하는 버전을 선택할 수 있습니다. 이를 통해 원하는 일정에 따라 새로운 서비스 기능으로 업그레이드할 수 있습니다.

버전 관리 전략에 관한 자세한 내용은 API 개선 제안 185를 참고하세요.

인터페이스 기반 버전 관리 정책

Compute Engine IBV API의 모든 버전은 인터페이스가 독립적으로 버전을 변경할 수 있더라도 동일한 서비스 버전을 공유하는 인터페이스 변경사항의 모음입니다.

Compute Engine IBV API는 안정화 버전과 미리보기 버전을 지원합니다.

정식 버전

대부분의 API 버전은 안정화 버전입니다. 안정화된 버전은 AIP-180에 정의된 대로 엄격한 호환성을 유지하므로 동일한 버전의 최신 안정화된 출시가 기존 기능을 중단하거나 코드 재작성을 요구하지 않습니다.

Compute Engine은 YYYY-MM-DD 형식 (예: 2026-09-01)의 표준 날짜를 사용하여 안정적인 API 버전을 식별합니다. 날짜가 늦을수록 최신 출시를 나타냅니다.

Compute Engine은 장기간에 걸쳐 안정적인 버전을 지원하므로 프로덕션 시스템이 안정적이고 중단되지 않습니다. 대부분의 애플리케이션에서는 일상적인 작업을 실행하기 위해 하나의 안정화 버전만 사용하면 됩니다.

미리보기 버전

Compute Engine은 새로운 기능에 대한 초기 사용자 의견을 수집하기 위해 미리보기 버전을 출시할 수 있습니다. 미리보기 버전은 날짜에 -preview 태그를 추가합니다(예: 2026-10-01-preview).

미리보기 버전에는 최신 안정화 버전의 모든 기능과 새로 추가된 실험용 기능이 포함됩니다. 미리보기 버전을 사용할 때는 다음 사항에 유의하세요.

  • 미리보기 기능은 이전 또는 향후 출시와의 호환성을 보장하지 않습니다.
  • 미션 크리티컬 프로덕션 환경에는 미리보기 버전을 사용하지 않는 것이 좋습니다.
  • 안정화 버전으로 승격하는 동안 미리보기 기능이 변경, 개선 또는 삭제될 수 있습니다.

새 기능을 실험하고 안정화 버전이 출시되면 코드를 업데이트할 계획이라면 미리보기 버전을 사용하세요.

요청에서 API 버전 지정

IBV를 사용하여 API를 호출하려면 요청에서 쿼리 매개변수 또는 헤더를 사용하여 타겟 버전을 지정합니다. API 요청을 만드는 방법의 예는 API 요청 만들기를 참고하세요.

Cloud 클라이언트 라이브러리

Cloud 클라이언트 라이브러리는 원시 REST 호출을 빌드하고 파싱하는 부담을 덜어줍니다. 각 라이브러리 버전은 특정 날짜 기반 API 버전과 직접 연결됩니다.

새 기능을 사용하려면 Cloud 클라이언트 라이브러리 패키지를 최신 버전으로 업데이트하세요. 새로운 안정화 및 미리보기 API 출시와 함께 업데이트된 Cloud 클라이언트 라이브러리가 게시됩니다.

안정적인 Cloud 클라이언트 라이브러리에서 프로덕션 애플리케이션을 실행하고 테스트 환경에 미리보기 라이브러리를 격리하는 것이 좋습니다.

Google Cloud CLI (gcloud)

gcloud CLI를 사용하면 개별 REST 엔드포인트를 수동으로 추적하지 않고도 Compute Engine 리소스를 관리할 수 있습니다.

gcloud CLI는 명령어를 두 가지 카테고리로 나눕니다.

  • 안정적인 명령어: 안정적인 API 버전을 타겟팅하는 표준 명령어 (예: gcloud compute instances create)입니다. 이러한 명령어는 완전히 지원되고 예측 가능하며 프로덕션 스크립트에 권장됩니다.
  • 미리보기 명령어: 사전 체험판 기능은 gcloud preview 그룹(예: gcloud preview compute ...)을 사용합니다. 이러한 명령어는 최종 출시 전에 계약이 변경될 수 있으므로 간단한 경고를 표시합니다.

Terraform

Google Cloud Terraform 프로바이더는 API 버전 관리를 추상화하고 기본 API 상호작용을 관리합니다. Terraform 구성은 수동 버전 헤더 설정을 노출하거나 요구하지 않습니다.

새 기능에 액세스하려면 Google Cloud Terraform Provider를 최신 버전으로 업데이트하세요. 미리보기 기능의 경우 google-beta 제공자를 사용합니다.

자주 묻는 질문(FAQ)

이 섹션에서는 Compute Engine API 버전 관리에 관해 자주 묻는 질문에 답변합니다.

  • v1 (CBV)에서 IBV로 마이그레이션해야 하나요?

    아니요. 기존 CBV v1 API 요청은 이전과 동일하게 계속 작동합니다. 하지만 IBV API에서 사용할 수 있는 새로운 기능에는 액세스할 수 없습니다.

  • IBV API 버전은 얼마나 오래 지원되나요?

    안정화 버전은 표준 Google Cloud 지원 중단 정책에 따라 영구적으로 유지됩니다.

  • 새 IBV API 버전은 얼마나 자주 출시되나요?

    새로운 IBV API 버전은 분기별 출시를 통해 계획됩니다. 미리보기 버전은 언제든지 출시할 수 있습니다.

  • Google Cloud 콘솔에서 사용 설정해야 하는 항목이 있나요?

    아니요. IBV API는 Compute Engine API와 함께 기본적으로 사용 설정됩니다.

  • 요청에 버전을 지정하지 않으면 어떻게 되나요?

    요청은 기본적으로 CBV v1 엔드포인트로 설정됩니다.

  • Cloud 감사 로그 항목에서 API 버전을 어디에서 찾을 수 있나요?

    API 버전은 protoPayload.requestMetadata.callerSuppliedUserAgent 및 요청 헤더 또는 쿼리 매개변수에 로깅됩니다.

다음 단계

Compute Engine API에 대해 자세히 알아보려면 다음 문서를 참고하세요.