버전 관리¶

개요¶

게이트웨이 API의 각 새로운 릴리스는 v1.0.0과 같은 릴리스의 Git 태그를 나타내는 "번들 버전"으로 정의한다. 이 번들은 다음을 포함한다.

• API 타입(리소스에 대한 Go 바인딩)
• CRD(리소스에 대한 쿠버네티스 정의)

릴리스 채널 ¶

릴리스 채널은 게이트웨이 API 내에서 기능의 안정성을 나타내는 데 사용된다. 모든 새로운 기능과 리소스는 실험적 릴리스 채널에서 시작된다. 그 후, 이들은 표준 릴리스 채널로 승격되거나 API에서 완전히 제거될 수 있다.

아래 다이어그램은 게이트웨이 API에서 새로운 GEP(기능 향상 제안서)로 제안된 기능이나 리소스의 라이프사이클에 대한 높은 수준의 개요를 제공한다.

flowchart TD
    0([Provisional GEP]) --> 1([Sponsors Committed])
    1 --> 2([Implementable GEP])
    2 --> A
    A>Experimental Channel] --> B([Widely used and working well?])
    B -->|Yes| C>Standard Channel]
    B -->|No| D([Could Changes Help?])
    D -->|Yes| E([Adjust and try again])
    D -->|No| F>Remove From API]
    E -->A
    A -- No progress in 6 months --> G(["Auto-dropped"])

style A fill:#eeb
style C fill:#beb
style F fill:#ebb
style G fill:#ebb

표준 릴리스 채널에는 다음이 포함된다.

• beta 또는 GA API 버전으로 승격된 리소스(beta API 버전은 게이트웨이 API에서 점진적으로 제거되고 있다는 점에 유의해야 한다.)
• 실험적 채널에서 표준 채널로 승격된 모든 필드

실험적 릴리스 채널에는 표준 채널에 포함된 모든 항목에 추가로 다음을 포함한다.

• alpha API 버전의 리소스
• 표준 채널로 승격되기 전의 모든 신규 필드

기본적으로 안정적인 사용 경험을 제공하므로 표준 채널을 사용하는 것을 권장한다. 많은 구현체들이 실험적 채널도 지원하며, 이를 통해 새로운 기능을 빠르게 반복 개발할 수 있다. 이 채널은 이전 버전과의 호환성에 대한 보장을 제공하지 않으며, 언제든지 호환되지 않는 변경 사항이 릴리스될 수 있다는 점에 유의해야 한다.

VAP(Validating Admission Policy, 검증 승인 정책)¶

게이트웨이 API는 VAP(Validating Admission Policy, 검증 승인 정책)를 사용하여 채널 경계를 보호한다.

• 업그레이드 VAP: 표준 채널 CRD 위에 실험적 채널 CRD를 적용하는 것을 방지한다. 이를 수행해야 하는 경우, 해당 VAP를 먼저 제거해야 한다.
• 가드레일 VAP: 어노테이션이 함께 존재하지 않으면 리소스의 실험적 필드를 설정하는 것을 방지한다. 어노테이션 없이는 표준 채널 기능만 사용할 수 있다.

API 버전¶

업스트림 쿠버네티스 API는 안정성 수준을 alpha, beta, GA API 버전의 세 가지로 구분한다. 게이트웨이 API에서는 위에서 설명한 릴리스 채널을 통해 이를 두 가지 안정성 수준으로 축소하였다.

일반적으로, 리소스가 실험적 채널에서 표준 채널로 승격될 때, Alpha API 버전(v1alpha2)에서 GA API 버전(v1)으로도 승격된다는 것을 의미한다.

근거¶

아래와 같은 이유로 beta는 점진적으로 제거되고 있다.

1. 대부분의 경우 API 안정성 수준은 실질적으로 두 가지이다.
2. 기본적(stable)으로 설치되는 상태와 alpha/experimental(unstable) 상태 게이트웨이 API에서는 중간 단계 (Beta 상태)의 가치가 명확하지 않다.
3. "안정(stable)"과 "실험적(experimental)" API를 더 멀리 분리할수록, 새로운 기능에 대한 의미 있는 피드백을 얻는 데 더 오래 걸린다.
4. 우리가 관리하는 각 고유 API 버전은 사용자, 구현자, 유지관리자 모두에게 상당한 추가 비용을 발생시킨다.

베타¶

일부 게이트웨이 API 리소스는 표준 채널로 승격될 때 Beta API 버전을 받은 경우가 있지만, 앞으로 추가되는 리소스에는 해당되지 않는다. 앞으로 표준 채널로 승격되는 모든 리소스는 그 과정의 일부로 v1 API 버전을 포함하게 된다.

이미 beta API 버전(v1beta1)을 가진 리소스는 다음과 같다.

• HTTPRoute
• 게이트웨이(Gateway)
• 게이트웨이 클래스(GatewayClass)
• 레퍼런스그랜트(ReferenceGrant)

v1.0 릴리스에서 HTTPRoute, 게이트웨이, 게이트웨이 클래스는 모두 GA API 버전(v1)으로 승격되었다.

레퍼런스그랜트는 예외적이다. 이 리소스는 현재 상위 쿠버네티스 API로 전환 중이며, sig-auth에서 관리한다. 이 과정이 완료될 때까지 레퍼런스그랜트는 게이트웨이 API에서 사실상 베타로 동결될 가능성이 높다. 레퍼런스그랜트가 내장 쿠버네티스 API로 널리 제공되면, 게이트웨이 API의 표준 채널에서 제거할 예정이다.

릴리스 프로세스¶

표준 채널 릴리스¶

표준 채널 릴리스는 4개월 주기를 목표로 한다. 릴리스 날짜는 미리 정해지며 연기되지 않는다. 다만, 포함되는 내용은 유동적이다. 릴리스 날짜 시점에 준비된 내용이 릴리스되며, 준비되지 않은 내용은 다음 릴리스에서 진행된다. 릴리스 번호는 포함되는 내용이 확정되는 시점에 결정하는 것이 이상적이다.

월별 실험적 릴리스¶

게이트웨이 API는 실험적 채널의 월별 릴리스를 monthly-$year-$month (예: monthly-2025-11) 형식의 태그로 발행한다. 이 릴리스는 다음과 같은 특징이 있다.

• experimental-install.yaml만 포함
• 표준 채널을 변경할 수 없음
• main 브랜치의 스냅샷
• 버그 수정 백포트를 받지 않음(대신 새로운 월별 릴리스로 업그레이드)
• SemVer 릴리스 번호를 사용하지 않음. 실험적 리소스와 필드에 대한 호환되지 않는 변경은 월별 릴리스 간에 항상 허용됨

월별 릴리스의 목적은 실험적 채널에서의 빠른 반복 개발을 가능하게 하는 것이다.

SemVer 릴리스¶

게이트웨이 API는 정기적인 주기로 SemVer 릴리스(예: 1.5.0, 1.6.0)를 발행한다. 릴리스 번호 구성에 시맨틱 버전 관리를 사용하지만, 릴리스 채널로 인해 엄격한 SemVer와는 다른 버전 관리 체계를 갖는다. 실험적 채널에서 마이너 릴리스 시 발생할 수 있는 호환되지 않는 변경에 대한 자세한 내용은 변경 가능한 것을 참고하자.

SemVer 릴리스의 특징은 다음과 같다.

• experimental-install.yaml과 standard-install.yaml 모두 포함
• 버그 수정 백포트를 위한 릴리스 브랜치 사용
• 대부분의 경우 experimental-install.yaml이 직전 월별 릴리스와 동일하지만, 필수 사항은 아님

버전 표시¶

각 CRD는 번들 버전과 채널을 나타내는 어노테이션과 함께 배포된다.

gateway.networking.k8s.io/bundle-version: v0.4.0
gateway.networking.k8s.io/channel: standard|experimental

변경 가능한 것¶

이 API를 사용하거나 구현할 때, 번들 버전 간에 무엇이 변경될 수 있는지 이해하는 것이 중요하다.

패치 버전(예: v0.4.0 -> v0.4.1)¶

• API 명세:
  • 명확성 개선
  • 오타 수정
• 버그 수정:
  • 유효성 검사 수정
  • 릴리스 프로세스 또는 산출물 수정
• 호환성 테스트:
  • 기존 테스트 수정
  • 기존 기능에 대한 호환성 테스트 커버리지 추가

마이너 버전(예: v0.4.0 -> v0.5.0)¶

• 패치 릴리스에서 유효한 모든 변경
• 실험적 채널:
  • 새로운 API 필드 또는 리소스 추가
  • 기존 API 필드 또는 리소스에 대한 중대 변경
  • 사전 사용 중단(deprecation) 없이 API 필드 또는 리소스 제거
• 표준 채널:
  • 실험적에서 표준 채널로의 필드 또는 리소스 승격
  • 쿠버네티스 사용 중단 정책에 따라 API 리소스 제거
• 모든 채널:
  • 상태에서 권장 조건 또는 사유 변경
  • 유효성 검사 완화(필수 필드를 선택적 필드로 변경 등)
  • 명세 업데이트에 맞춘 호환성 테스트 변경
  • 필드명 변경이나 새로운 쿠버네티스 API 버전에서 유효한 기타 모든 변경 사항을 포함할 수 있는 새로운 API 버전의 도입

메이저 버전(예: v0.x -> v1.0)¶

• 메이저 버전이 변경될 때는 API 호환성 보장을 하지 않는다.

승격 기준 ¶

리소스, 필드, 기능이 실험적에서 표준으로 승격되기 위해서는 다음 기준을 충족해야 한다.

• 완전한 호환성 테스트 커버리지
• 여러 구현체에서 호환성 통과
• 광범위한 구현 및 사용
• alpha API로 최소 6개월간 운영된 시간(soak time)
• 최소 1회 마이너 릴리스 및 3개월간 주요 변경 없음
• 서브프로젝트 오너 및 KEP 리뷰어 승인

지원 버전 ¶

이 프로젝트는 다양한 쿠버네티스 버전에서 일관된 업그레이드 경험을 지원하는 것을 목표로 한다. 이를 달성하기 위해 다음과 같은 사항을 준수한다.

1. 가장 최근 쿠버네티스 마이너 버전 5개 이상을 최소 지원 대상으로 한다.
2. v1beta1과 v1 사이의 표준 채널 변경은 모두 완전히 호환 및 변환 가능하도록 보장한다.
3. 변환(conversion) 웹훅 도입은 최대한 피하도록 노력한다. 만약 변환 웹훅이 도입되어야 할 경우, 해당 API의 라이프타임 동안 또는 최소한 대안이 제공될 때까지 지원한다.

CRD 관리¶

클러스터에서 게이트웨이 API CRD를 관리하는 방법은 CRD 관리 가이드를 참고하자.

범위 외 항목¶

미출시 API¶

이 프로젝트는 main 브랜치에 자주 업데이트가 발생한다. main을 포함한 어떤 브랜치의 코드에도 릴리스되기 전까지는 호환성 보장이 없다. 예를 들어, 릴리스가 공개되기 전에 변경이 되돌려질 수 있다. 최상의 결과를 위해서는 이 프로젝트의 최신 공개 릴리스를 사용하는 것이 좋다.

소스 코드¶

소스 코드 import에 대한 안정성은 보장하지 않는다. 인터페이스와 동작은 향후 릴리스에서 예기치 않게, 그리고 이전 버전과 호환되지 않는 방식으로 변경될 수 있다.