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

了解 API 兼容性指南

API 兼容性指南

Red Hat 建议应用程序开发人员采用以下原则，以提高与 OpenShift Container Platform 的兼容性。

  • 使用与应用程序需求匹配的支持层级的 API 和组件。

  • 尽可能使用已发布的客户端库构建应用程序。

  • 只有在执行环境与构建应用程序的环境一样新的情况下，才能保证应用程序能够正确运行。针对 OpenShift Container Platform 4.14 构建的应用程序不能保证在 OpenShift Container Platform 4.13 上正常运行。

  • 不要设计依赖于系统软件包或其他组件提供的配置文件的应用程序。除非上游社区明确承诺保留这些文件，否则这些文件在不同版本之间可能会发生变化。在适当的情况下，依赖于任何 Red Hat 提供的针对这些配置文件的接口抽象，以保持向前兼容性。不鼓励直接修改配置文件的文件系统，强烈建议用户在可用情况下与运算符提供的 API 集成，以避免双写入冲突。

  • 不要依赖以unsupported<FieldName>为前缀的 API 字段或产品文档中未明确提及的注释。

  • 不要依赖于兼容性保证比您的应用程序更短的组件。

  • 不要对 etcd 服务器执行直接存储操作。所有 etcd 访问都必须通过 api-server 或通过已记录的备份和恢复过程执行。

Red Hat 建议应用程序开发人员遵循 Red Hat Enterprise Linux (RHEL) 定义的兼容性指南。OpenShift Container Platform 在构建应用程序或在平台上托管应用程序时，强烈建议遵循以下指南。

  • 不要依赖于特定的 Linux 内核或 OpenShift Container Platform 版本。

  • 避免读取proc、sys和debug文件系统或任何其他伪文件系统。

  • 避免使用ioctls直接与硬件交互。

  • 避免直接与cgroups交互，以免与提供容器执行环境的 OpenShift Container Platform 主机代理冲突。

在版本生命周期中，Red Hat 会尽商业上合理的努力，以保持所有次要版本和 z 流版本之间的 API 和应用程序操作环境 (AOE) 兼容性。如有必要，Red Hat 可能会为了解决严重的安全问题或其他重大问题而对这一兼容性目标做出例外。

API 兼容性例外

以下是 OpenShift Container Platform 中的兼容性例外情况。

未经支持的 Operator 进行的 RHEL CoreOS 文件系统修改

目前，我们无法保证对主机操作系统进行的修改在次要版本之间得以保留，除非该修改是通过支持的 Operator（例如 Machine Config Operator 或 Node Tuning Operator）公开的公共接口进行的。

对云或虚拟化环境中集群基础设施的修改

目前，我们无法保证对支持集群的云托管环境进行的修改得以保留，除非该修改是通过产品中公开的公共接口进行的，或被记录为受支持的配置。集群基础设施提供商负责保留其云或虚拟化基础设施，除非他们通过 API 将此权限委托给产品。

升级后的集群与全新安装之间的功能默认值

目前，我们无法保证产品次要版本的全新安装将具有与使用先前次要版本安装并升级到相同版本的相同功能默认值。例如，未来版本的该产品可能使用与先前次要版本不同的默认值来配置云基础设施。此外，未来版本的该产品可能做出与过去版本不同的默认安全选择。过去版本的该产品将进行前向升级，但在适当情况下保留旧的选项，以专门维护向后兼容性。

使用前缀为“unsupported”的 API 字段或未记录的注释

产品中的某些 API 公开了前缀为unsupported的字段。目前，我们无法保证在版本之间或版本内支持使用此字段。产品支持可以请求客户在调试特定问题时在此字段中指定一个值，但在该交互之外不支持使用此字段。对未明确记录的对象上的注释的使用，不保证在次要版本之间得到支持。

每个产品安装拓扑的 API 可用性

OpenShift 发行版将继续发展其支持的安装拓扑，并且并非所有安装拓扑中的所有 API 都一定会包含在另一个拓扑中。例如，某些拓扑可能会限制对特定 API 的读/写访问权限，如果它们与产品安装拓扑冲突，或者根本不包含特定 API，则与该拓扑无关。在给定拓扑中存在的 API 将根据上面定义的兼容性层进行支持。

API 兼容性常用术语

应用程序编程接口 (API)

API 是由软件程序实现的公共接口，使它能够与其他软件进行交互。在 OpenShift Container Platform 中，API 来自集中的 API 服务器，并用作所有系统交互的中心。

应用程序操作环境 (AOE)

AOE 是执行最终用户应用程序程序的集成环境。AOE 是一个容器化环境，它提供了与主机操作系统的隔离。至少，AOE 允许应用程序以与主机操作系统库和二进制文件隔离的方式运行，但仍与主机上的所有其他容器共享相同的操作系统内核。AOE 在运行时强制执行，它描述了应用程序与其操作环境之间的接口。它包括平台、操作系统和环境之间的交叉点，以及用户应用程序，包括向下 API、DNS、资源会计、设备访问、平台工作负载标识、容器之间的隔离、容器与主机操作系统之间的隔离的投影。

AOE 不包括可能因安装而异的组件，例如容器网络接口 (CNI) 插件选择或对产品的扩展（例如准入钩子）。在容器环境以下级别与集群集成的组件在版本之间可能会出现更多差异。

虚拟化环境中的兼容性

虚拟环境模拟裸机环境，以便在裸机环境上运行的无特权应用程序可以在相应的虚拟环境中运行，无需修改。虚拟环境提供物理资源的简化抽象视图，因此可能存在一些差异。

云环境中的兼容性

OpenShift Container Platform 可能会选择通过特定于云提供商的集成来提供与托管云环境的集成点。这些集成点的兼容性取决于本地云供应商提供的保证及其与 OpenShift Container Platform 兼容性窗口的交叉点。在 OpenShift Container Platform 本地作为默认安装的一部分提供与云环境的集成时，Red Hat 使用稳定的云 API 端点进行开发，以提供具有前瞻性兼容性的商业上合理的支持，其中包括稳定的弃用策略。云提供商和 OpenShift Container Platform 之间的集成示例区域包括但不限于动态卷配置、服务负载均衡器集成、Pod 工作负载标识、计算的动态管理以及作为初始安装一部分配置的基础设施。

主要、次要和 z 流版本

Red Hat 主要版本代表产品开发中的一个重要步骤。次要版本在主要版本范围内出现得更频繁，并且代表可能影响未来应用程序兼容性的弃用边界。z 流版本是对次要版本的更新，它为关联的次要版本提供持续的修复流。除了为了响应不可预见的安全影响而明确覆盖此策略外，在 z 流版本中 API 和 AOE 兼容性绝不会被破坏。

例如，在 4.13.2 版本中

  • 4 是主要版本号

  • 13 是次要版本号

  • 2 是 z 流版本号

扩展用户支持 (EUS)

OpenShift Container Platform 主要版本中的次要版本，具有扩展的支持窗口，用于修复关键错误。用户可以通过逐步采用 EUS 版本之间的次要版本来在 EUS 版本之间迁移。需要注意的是，弃用策略是在次要版本之间定义的，而不是 EUS 版本之间。因此，当迁移到未来的 EUS 时，EUS 用户可能需要响应弃用，同时通过每个次要版本进行顺序升级。

开发者预览版

Red Hat 不正式支持的可选产品功能，但旨在提供探索早期阶段技术的机制。默认情况下，开发者预览版功能是可选的，并且随时可能被移除。启用开发者预览版功能可能会使集群无法支持，具体取决于功能的范围。

如果您是 Red Hat 客户或合作伙伴，并且对这些开发者预览版有反馈，请使用OpenShift Bug 追踪器提交问题。请勿使用正式的 Red Hat 支持服务工单流程。您可以在以下知识文章中阅读更多关于支持处理的信息。

技术预览版

一项可选的产品功能，可在产品创新发布之前提供抢先体验，以便在开发过程中测试功能并提供反馈。此功能并非完全受支持，可能功能不完整，并且并非用于生产环境。使用技术预览功能需要明确选择加入。了解更多关于技术预览功能支持范围的信息。