本文档的目的是将 Hadoop 兼容性指南 提炼成与系统管理员相关的有用信息。
目标受众是负责维护 Apache Hadoop 集群并必须规划和执行集群升级的管理员。
Hadoop 开发社区会定期推出新的 Hadoop 发行版，以引入新功能并修复现有问题。发行版分为三类
Hadoop 所依赖的本机组件集合被视为 Hadoop ABI 的一部分。Hadoop 开发社区努力在最大程度上维护 ABI 兼容性。在次要版本之间，Hadoop 的本机依赖项的最低支持版本号不会增加，除非有必要，例如出于安全或许可问题。当发生此类更改时，Hadoop 开发人员社区会尝试保留相同的主版本，只更新次要版本。
Hadoop 依赖于 Java 虚拟机。在 Hadoop 的主要版本之间，JVM 的最低支持版本不会发生更改。如果在主要版本之间当前最低支持的 JVM 版本不再受支持，则最低支持的 JVM 版本可能会在次要版本中更改。
Hadoop 依赖于一些传输层技术，例如 SSL。这些依赖项的最低支持版本不会增加，除非有必要，例如出于安全或许可问题。当发生此类更改时，Hadoop 开发人员社区会尝试保留相同的主版本，只更新次要版本。
Hadoop 的服务端口号在主要版本内保持不变，但在主要版本中可能会更改。
Hadoop 的内部线缆协议在同一主要版本内的次要版本之间，无论是客户端与服务器之间还是服务器之间，都将保持向后和向前兼容，目的是实现滚动升级。线缆协议在主要版本之间的向前和向后兼容性是可能的，并且在某些条件下可能允许滚动升级，但不能保证。
Hadoop REST API 提供了一种简单机制，用于收集有关 Hadoop 系统状态的信息。为了支持 REST 客户端，Hadoop REST API 已版本化，并且在版本内不会发生不兼容的更改。端点本身以及受支持参数列表和端点输出均禁止在 REST 端点版本内发生不兼容的更改。但是，请注意，引入新字段和其他累加更改被视为兼容性更改，因此 REST API 的任何使用者都应足够灵活以忽略未知字段。
REST API 版本是一个数字，与 Hadoop 版本号无关。版本号编码在以“v”为前缀的端点 URL 中，例如“v1”。只有在次要或主要版本中才能引入新的 REST 端点版本。REST 端点版本只有在被标记为已弃用一个完整的主要版本后才能被删除。
Hadoop 会产生各种输出，可以由自动化工具解析。在使用 Hadoop 输出时，请考虑以下内容
Hadoop 的 CLI 集合提供了管理系统各个方面以及发现有关系统状态的信息的能力。在主要版本之间，不会移除或语义化更改任何 CLI 工具选项。该规则的例外情况是明确标记为实验性和可更改的 CLI 工具和工具选项。除非另有说明，否则 CLI 工具的输出在主要版本号内也将保持不变。
请注意，对 CLI 工具输出的任何更改都被视为不兼容的更改，因此在主要版本之间，CLI 输出不会更改。请注意，CLI 工具输出不同于 CLI 工具生成的日志输出。日志输出不适用于自动化使用，并且可能随时更改。
Hadoop 公开的 Web UI 仅供人工使用。抓取 UI 数据不是受支持的用法。不会做出任何努力来确保任何 Web UI 中显示的数据在各个版本之间具有任何类型的兼容性。
Hadoop 的内部系统状态是私有的，不应直接修改。以下策略管理各种内部状态存储的升级特性
Hadoop 使用两种主要形式的配置文件：XML 配置文件和日志记录配置文件。
XML 配置文件包含一组属性，以名称-值对的形式。属性的名称和含义由 Hadoop 定义，并且保证在小版本中保持稳定。属性只能在主要版本中删除，并且仅当它已被标记为至少一个完整主要版本的弃用属性时才能删除。大多数属性都有一个默认值，如果属性未在 XML 配置文件中显式设置，则将使用该默认值。默认属性值不会在维护版本中更改。有关各种 Hadoop 组件支持的属性的详细信息，请参阅组件文档。
下游项目和用户可以将自己的属性添加到 XML 配置文件中，以便其工具和应用程序使用。虽然 Hadoop 对定义新属性没有正式限制，但与 Hadoop 定义的属性冲突的新属性可能导致意外和不良结果。建议用户避免使用与 Hadoop 定义的属性命名空间冲突的自定义配置属性名称，因此应避免使用 Hadoop 使用的任何前缀，例如 hadoop、io、ipc、fs、net、file、ftp、kfs、ha、file、dfs、mapred、mapreduce 和 yarn。
Hadoop 守护程序和 CLI 生成的日志输出受一组配置文件控制。这些文件控制 Hadoop 的各个组件将输出的最低日志消息级别，以及这些消息的存储位置和方式。在小版本之间，不会对日志配置进行任何更改，以减少、消除或重定向日志消息。
Hadoop 使用多种格式的许多其他类型的配置文件，例如 JSON 资源配置文件或 XML 公平调度程序配置。在小版本中不会引入不兼容的配置文件格式更改。即使在小版本之间，如果可能，也会避免不兼容的配置文件格式更改。
Hadoop 配置文件、作业历史信息（作业历史服务器使用）和 Hadoop 生成的日志文件的位置和一般结构将在维护版本中保持不变。
Hadoop 发行版的内容（例如 JAR 文件）可能会随时更改，除了客户端工件外，不应将其视为可靠的。客户端工件及其内容将在主要版本中保持兼容。Hadoop 开发社区的目标是允许应用程序代码在小版本中继续保持不变，并且尽可能在主要版本中保持不变。当前的客户端工件列表如下
某些 Hadoop 组件通过环境变量接收信息。例如，HADOOP_OPTS 环境变量被大多数 Hadoop 进程解释为在启动新的 JVM 时要使用的附加 JVM 参数字符串。在小版本之间，Hadoop 解释环境变量的方式不会以不兼容的方式更改。换句话说，放入同一变量的相同值应该对同一主要版本中的所有 Hadoop 版本产生相同的结果。
Hadoop 依赖大量第三方库才能运行。尽可能地，Hadoop 开发者社区致力于向下游开发者隐藏这些依赖项。尽管如此，Hadoop 确实公开了它的一些依赖项，尤其是在 Hadoop 3 之前。Hadoop 不会通过主要版本之间的客户端工件公开任何新的依赖项。
一个常见的下游反模式是使用 hadoop classpath 的输出来设置下游应用程序的类路径或将所有随 Hadoop 包含的第三方 JAR 添加到下游应用程序的类路径。这种做法在 Hadoop 的第三方依赖项和下游应用程序之间造成了紧密耦合，从而导致了一个脆弱的应用程序，随着 Hadoop 依赖项的变化而难以维护。强烈建议不要使用这种做法。
Hadoop 还包括几个本机组件，包括压缩、容器执行程序二进制文件和各种本机集成。这些本机组件为 Hadoop 引入了一组本机依赖项。本机依赖项集可能会在小版本中更改，但 Hadoop 开发者社区将尽可能地尝试将任何依赖项版本更改限制为小版本更改。
Hadoop 目前由 Linux 和 Windows 上运行的 x86 和 AMD 处理器的 Hadoop 开发者社区提供支持。这些操作系统和处理器在可预见的未来可能会继续受到支持。如果支持计划发生变化，将在至少一个完整的次要版本（但理想情况下是一个完整的版本）中将被废弃的操作系统或处理器记录为已弃用，然后再实际废弃。Hadoop 可以在其他操作系统和处理器架构上运行，但社区可能无法在出现问题时提供帮助。
即使是维护版本，Hadoop 守护进程所需的最低资源在不同版本之间如何变化也没有任何保证。尽管如此，Hadoop 开发者社区仍将尝试避免在次要版本中增加需求。
Hadoop 支持的任何文件系统（例如通过 FileSystem API）在大多数情况下将在整个主要版本中继续受到支持。在主要版本中放弃对文件系统支持的唯一情况是提供了到备用客户端实现的干净迁移路径。
有关针对 Apache Hadoop 开发应用程序和项目的疑问，请联系用户邮件列表。