跳至内容

版本控制

概述

每个新的 Gateway API 版本都定义了一个“捆绑版本”，它代表一个版本的 Git 标签，例如 v1.0.0。它包含以下内容

  • API 类型 (资源的 Go 绑定)
  • CRDs (资源的 Kubernetes 定义)

发布渠道

发布渠道用于指示 Gateway API 中的功能稳定性。所有新功能和资源都从实验性发布渠道开始。从那时起，它们可能会毕业到标准发布渠道，或者完全从 API 中删除。

下图提供了 Gateway API 中由新的 GEP (增强提案) 提出的功能或资源生命周期的概述

flowchart TD
    0([Implementable GEP]) --> 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

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

标准发布渠道包括

  • 已毕业到 Beta 或 GA API 版本的资源（请注意，Beta API 版本正在 Gateway API 中逐步淘汰）
  • 从实验性渠道毕业到标准的所有字段

实验性发布渠道包括标准发布渠道中的所有内容，以及

  • 具有 Alpha API 版本的资源
  • 所有新字段在毕业到标准渠道之前

Release Channel Overlap

我们建议默认情况下使用标准渠道，因为它将提供稳定的体验。许多实现还提供了对实验性渠道的支持，这使我们能够快速迭代新功能。请注意，该渠道不提供任何向后兼容性保证，并且可能会在任何时候发布重大更改。

API 版本

上游 Kubernetes API 具有 3 个稳定性级别，分别由 alpha、beta 和 GA API 版本表示。在 Gateway API 中，我们将此缩减为 2 个稳定性级别，如上所述由我们的发布渠道表示。

一般来说，这意味着当资源从实验性渠道毕业到标准渠道时，它们也将从 Alpha API 版本 (v1alpha2) 毕业到 GA API 版本 (v1)。

理由

我们逐步淘汰 beta 的原因如下

  1. 在大多数情况下，实际上存在两个级别的 API 稳定性 - 默认安装（稳定）和 alpha/实验性（不稳定）。对于 Gateway API，中间（Beta）状态的价值并不明显。
  2. 我们越分离“稳定”和“实验性”API，获得新功能的有效反馈所需的时间就越长。
  3. 我们维护的每个唯一的 API 版本都会给用户、实施者和维护者带来额外的成本。

Beta

尽管一些 Gateway API 资源在毕业到标准渠道时已经收到了 Beta API 版本，但其他资源不会出现这种情况。所有未来毕业到标准渠道的资源都将包括 v1 API 版本，作为该过程的一部分。

已经具有 beta API 版本 (v1beta1) 的资源是

  • HTTPRoute
  • 网关
  • 网关类
  • ReferenceGrant

在 v1.0 版本中，HTTPRoute、Gateway 和 GatewayClass 都毕业了，包括一个 GA API 版本 (v1)。

ReferenceGrant 是一个特殊情况，因为它正在 过渡到由 sig-auth 拥有的上游 Kubernetes API。在问题解决之前，ReferenceGrant 可能在 Gateway API 中被有效地冻结为 beta。当它作为内置 Kubernetes API 广泛可用时，我们可能会将其从 Gateway API 的标准渠道中删除。

版本指示器

每个 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 字段或资源进行重大更改
    • 在未事先弃用情况下删除 API 字段或资源
  • 标准渠道
  • 所有渠道
    • 更改状态中推荐的条件或原因
    • 放宽验证（包括使必填字段可选）
    • 更改一致性测试以匹配规范更新
    • 引入新的 API 版本，其中可能包含重命名的字段或 新的 Kubernetes API 版本 中有效的任何其他内容

主要版本 (例如 v0.x 到 v1.0)

  • 主要版本更改时，没有 API 兼容性保证。

毕业标准

为了使资源、字段或功能从实验性渠道毕业到标准渠道，它必须满足以下标准

  • 完整的符合性测试覆盖率。
  • 多个符合性实现。
  • 广泛的实施和使用。
  • 至少 6 个月的浸泡时间作为 alpha API。
  • 至少 1 个次要版本和 3 个月没有重大更改。
  • 获得子项目所有者 + KEP 评审员的批准。

支持的版本

该项目旨在为各种 Kubernetes 版本提供支持，并在版本之间提供一致的升级体验。为此，我们承诺

  1. 至少支持最新的 5 个 Kubernetes 次要版本。
  2. 确保 v1beta1 和 v1 之间的标准渠道更改完全兼容且可转换。
  3. 尽一切努力避免引入转换 webhook。如果需要引入转换 webhook，它将在 API 的整个生命周期内得到支持，或者至少在有替代方案可用之前得到支持。

CRD 管理

有关如何在您的集群中管理 Gateway API CRD 的信息，请参阅我们的 CRD 管理指南。

超出范围

未发布的 API

该项目的主分支将频繁更新。在任何分支（包括主分支）中的代码发布之前，没有任何与兼容性相关的保证。例如，在发布版本之前可能会恢复更改。为了获得最佳效果，请使用该项目的最新发布版本。

源代码

我们不提供源代码导入的稳定性保证。接口和行为可能会在任何未来的版本中以意外且向后不兼容的方式发生变化。