OpenShift 文档正在迁移，很快将只能在 docs.redhat.com（所有 Red Hat 产品文档的中心）访问。立即体验 新的文档体验。
  1. 文档
    2. history bug_report picture_as_pdf
×

了解 API 层次

本指南不涵盖分层的 OpenShift Container Platform 产品。

裸机配置的 API 层次也适用于虚拟化配置，但任何直接与硬件交互的功能除外。那些直接与硬件相关的功能的应用程序运行环境 (AOE) 兼容性级别不超过硬件供应商提供的级别。例如，依赖于图形处理单元 (GPU) 功能的应用程序受 GPU 供应商驱动程序提供的 AOE 兼容性限制。

云环境中针对云特定集成点的 API 层次不具有超过托管云供应商提供的 API 或 AOE 兼容性级别。例如，执行计算、入口或存储动态管理的 API 依赖于云平台公开的基础 API 功能。如果云供应商修改了先决条件 API，Red Hat 将尽商业上合理的努力维护对 API 的支持，其功能目前由云基础设施供应商提供。

Red Hat 要求应用程序开发人员验证他们所依赖的任何行为都在正式 API 文档中明确定义，以防止引入对未指定的实现特定行为的依赖或对 API 特定实现中的错误的依赖。例如，如果应用程序使用未记录的 API 或依赖于未定义的行为，则入口路由器的新的版本可能与旧的版本不兼容。

API 层次

所有商业支持的 API、组件和功能都与以下支持级别之一相关联

API 1 层

API 和应用程序运行环境 (AOE) 在主要版本中保持稳定。它们可以在主要版本中被弃用，但直到后续主要版本才会被删除。

API 2 层

在主要版本发布后，API 和 AOE 至少稳定 9 个月或自弃用公告之日起 3 个次要版本，以较长者为准。

API 级别 3

此级别适用于通过 Operator Hub 包含在 OpenShift Container Platform 中的语言、工具、应用程序和可选 Operator。每个组件都将指定 API 和 AOE 将受支持的寿命。较新版本的特定于语言运行时的组件将尝试在次要版本之间尽可能与 API 和 AOE 兼容。但是，不保证次要版本之间的兼容性。

通过 Operator Hub 持续更新的组件和开发工具（称为 Operator 和操作数）应视为 API 级别 3。开发人员应谨慎操作并了解这些组件在每个次要版本中可能如何变化。鼓励用户查阅组件记录的兼容性指南。

API 级别 4

不提供兼容性。API 和 AOE 随时可能更改。需要长期支持的应用程序不应使用这些功能。

Operator 通常在内部使用自定义资源定义 (CRD) 来完成任务。这些对象并非供 Operator 外部的参与者使用，而是旨在隐藏。如果任何 CRD 不供 Operator 外部的参与者使用，则应在 Operator 的 `ClusterServiceVersion` (CSV) 中指定 `operators.operatorframework.io/internal-objects` 注解，以表明相应的资源仅供内部使用，并且 CRD 可能会被明确标记为 4 级。

将 API 级别映射到 API 组

对于 Red Hat 定义的每个 API 级别，我们都提供特定 API 组的映射表，其中上游社区致力于保持向前兼容性。除非另有说明，否则任何未指定显式兼容级别且未在下面专门讨论的 API 组均默认分配 API 级别 3，但 `v1alpha1` API 默认分配级别 4。

对 Kubernetes API 组的支持

以后缀 `*.k8s.io` 结尾或具有 `version.<name>` 形式（无后缀）的 API 组受 Kubernetes 弃用策略的约束，并遵循公开的 API 版本和相应支持级别之间的常规映射，除非另有说明。

API 版本示例 API 级别

v1

1 级

v1beta1

2 级

v1alpha1

4 级

对 OpenShift API 组的支持

以后缀 `*.openshift.io` 结尾的 API 组受 OpenShift Container Platform 弃用策略的约束，并遵循公开的 API 版本和相应兼容级别之间的常规映射，除非另有说明。

API 版本示例 API 级别

apps.openshift.io/v1

1 级

authorization.openshift.io/v1

1 级，部分 1 级已弃用

build.openshift.io/v1

1 级，部分 1 级已弃用

config.openshift.io/v1

1 级

image.openshift.io/v1

1 级

network.openshift.io/v1

1 级

network.operator.openshift.io/v1

1 级

oauth.openshift.io/v1

1 级

imagecontentsourcepolicy.operator.openshift.io/v1alpha1

1 级

project.openshift.io/v1

1 级

quota.openshift.io/v1

1 级

route.openshift.io/v1

1 级

quota.openshift.io/v1

1 级

security.openshift.io/v1

1 级，但 `RangeAllocation` (4 级) 和 `*Reviews` (2 级) 除外

template.openshift.io/v1

1 级

console.openshift.io/v1

2 级

对监控 API 组的支持

以后缀 `monitoring.coreos.com` 结尾的 API 组具有以下映射

API 版本示例 API 级别

v1

1 级

v1alpha1

1 级

v1beta1

1 级

对 Operator 生命周期管理器 API 组的支持

Operator 生命周期管理器 (OLM) 提供的 API 包括以后缀 `operators.coreos.com` 结尾的 API 组。这些 API 具有以下映射

API 版本示例 API 级别

v2

1 级

v1

1 级

v1alpha1

1 级

API 弃用策略

OpenShift Container Platform 由来自许多上游社区的许多组件组成。预计组件集、相关的 API 接口和相关功能将随着时间的推移而发展，并且可能需要正式弃用才能删除该功能。

弃用 API 的部分内容

OpenShift Container Platform 是一个分布式系统，其中多个组件通过一组结构化 API 与集群控制平面管理的共享状态交互。根据 Kubernetes 约定，OpenShift Container Platform 提供的每个 API 都与一个组标识符相关联，并且每个 API 组都独立版本化。每个 API 组都在不同的上游社区中管理，包括 Kubernetes、Metal3、Multus、Operator Framework、Open Cluster Management、OpenShift 本身等等。

虽然每个上游社区都可能为给定的 API 组和版本定义他们自己独特的弃用策略，但 Red Hat 会根据我们在每个上游社区中的集成和了解，将社区特定的策略规范化为前面定义的兼容级别之一，以简化最终用户的使用和支持。

API 的弃用策略和时间表因兼容级别而异。

弃用策略涵盖 API 的所有元素，包括：

  • REST 资源，也称为 API 对象

  • REST 资源的字段

  • REST 资源上的注释，不包括特定于版本的限定符

  • 枚举或常量值

除了每个组中最新的 API 版本之外，在宣布弃用后，必须支持较旧的 API 版本，持续时间不少于：

API 级别 持续时间

1 级

在主要版本中稳定。它们可能在主要版本中被弃用，但直到后续主要版本才会被删除。

2 级

9 个月或自弃用公告之日起 3 个版本，以较长者为准。

3 级

请参阅特定于组件的时间表。

4 级

无。不保证兼容性。

以下规则适用于所有 1 级 API：

  • 只能通过递增组的版本来删除 API 元素。

  • API 对象必须能够在 API 版本之间往返，而不会丢失信息，但某些版本中不存在的整个 REST 资源除外。在版本之间不存在等效字段的情况下，数据将以注释的形式在转换过程中保留。

  • 给定组中的 API 版本在发布至少同样稳定的新 API 版本之前不能弃用，除非整个 API 对象被删除。

弃用 CLI 元素

面向客户端的 CLI 命令的版本控制方式与 API 不同，而是面向用户的组件系统。用户与 CLI 交互的两种主要方式是通过命令或标志，在此上下文中称为 CLI 元素。

除非另有说明或 CLI 依赖于较低级别的 API，否则所有 CLI 元素默认为 API 1 级。

元素 API 级别

普遍可用 (GA)

标志和命令

1 级

技术预览

标志和命令

3 级

开发者预览

标志和命令

4 级

弃用整个组件

弃用整个组件的持续时间和时间表直接映射到该组件公开的 API 的最高 API 级别相关的持续时间。例如，公开具有 1 级和 2 级 API 的组件在满足 1 级弃用时间表之前不能被删除。

API 级别 持续时间

1 级

在主要版本中稳定。它们可能在主要版本中被弃用，但直到后续主要版本才会被删除。

2 级

9 个月或自弃用公告之日起 3 个版本，以较长者为准。

3 级

请参阅特定于组件的时间表。

4 级

无。不保证兼容性。