目的

本文档的目的是将Hadoop兼容性指南的信息提炼为对系统管理员相关的信息。

目标受众

目标受众是负责维护Apache Hadoop集群并必须计划和执行集群升级的管理员。

Hadoop版本

Hadoop开发社区定期发布新的Hadoop版本，引入新功能并修复现有问题。发布分为三类：

  • 主要版本：主要版本通常包含重要的新功能，并且通常代表着最大的升级兼容性风险。主要版本增加发布版本的第一个数字，例如从2.8.2到3.0.0。
  • 次要版本：次要版本通常包含一些新功能以及修复一些显着问题。在大多数情况下，次要版本不应该带来太多的升级风险。次要版本增加发布版本的中间数字，例如从2.8.2到2.9.0。
  • 维护版本：维护版本不应包含任何新功能。维护版本的目的是解决开发社区认为足以推送新版本以解决这些问题的一组问题。维护版本在升级方面应该几乎没有风险。维护版本增加发布版本的最后一个数字，例如从2.8.2到2.8.3。

平台依赖关系

Hadoop依赖的本机组件被视为Hadoop ABI的一部分。Hadoop开发社区致力于在最大程度上保持ABI兼容性。在次要版本之间，除非出于安全性或许可问题的原因，否则不会提高Hadoop的本机依赖关系的最低支持版本号。发生此类更改时，Hadoop开发社区将尝试保持相同的主要版本并仅更新次要版本。

Hadoop依赖于Java虚拟机。在Hadoop的主要版本之间，支持的JVM的最低版本不会更改。如果当前支持的JVM版本在主要版本之间变得不受支持，则可以在次要版本中更改最低支持的JVM版本。

网络

Hadoop对一些传输级技术，例如SSL，有依赖关系。除非出于安全性或许可问题的原因，否则将不会提高这些依赖关系的最低支持版本。发生此类更改时，Hadoop开发社区将尝试保持相同的主要版本并仅更新次要版本。

Hadoop的服务端口号在一个主要版本内将保持不变，但可能在主要版本中更改。

Hadoop的内部传输协议将在相同主要版本内在次要版本之间保持向前和向后兼容性，包括客户端和服务器之间以及服务器之间，以实现滚动升级。

在主要版本之间，通过特定条件可能实现传输协议的向前和向后兼容性，并可能允许滚动升级，但不提供任何保证。

脚本和自动化

REST API

Hadoop的REST API提供了一个方便的机制，用于收集有关Hadoop系统状态的信息。为了支持REST客户端，Hadoop的REST API是有版本的，并且在一个版本内不会发生不兼容的更改。REST端点本身以及支持的参数列表和端点输出在REST端点版本内禁止发生不兼容的更改。但是请注意，引入新字段和其他可添加的更改被视为兼容的更改，因此REST API的任何消费者应足够灵活，以忽略未知字段。

REST API版本是一个数字，并且与Hadoop版本号无关。版本号编码在以“v”为前缀的端点URL中，例如“v1”。只有在次要或主要发布版本时才能引入新的REST端点版本。只有在被标记为完整的主要发布版本之后，才能删除REST端点版本。

解析Hadoop输出

Hadoop生成各种可能被自动化工具解析的输出。在消耗Hadoop输出时，请考虑以下事项：

  • Hadoop的日志输出不应在维护版本中发生变化，除非解决了正确性问题。虽然日志输出可以直接被软件消耗，但它主要用于供人类读者使用。
  • Hadoop为各种操作生成审计日志。审计日志旨在供机器读取，尽管添加新的记录和字段被认为是兼容的更改。任何审计日志的消费者都应该允许意外的记录和字段。审计日志格式在主要发布版本之间不会发生不兼容的更改。
  • Hadoop生成的度量数据主要用于自动化消费。度量格式在主要版本之间不会以不兼容的方式更改，但新的记录和字段可以在任何时候以兼容的方式添加。度量数据的消费者应该允许未知的记录和字段。

命令行界面（CLIs）

Hadoop的一系列CLIs提供了管理系统各个方面以及发现系统状态信息的能力。在主要版本之间，不会删除或在语义上更改任何CLI工具选项。该规则的例外是显式标记为实验性并可能更改的CLI工具和工具选项。CLI工具的输出将在主要版本号内保持相同，除非另有文档说明。

请注意，对CLI工具输出的任何更改都被视为不兼容的更改，因此在主要版本之间，CLI输出将不会更改。请注意CLI工具输出与CLI工具生成的日志输出是不同的。日志输出不适用于自动化消费，并且可以在任何时候更改。

Web用户界面（Web UI）

Hadoop暴露的Web用户界面仅供人类使用。不支持通过UI对数据进行爬取。不会努力确保在不同版本之间显示的数据之间的任何兼容性。

Hadoop状态数据

Hadoop的内部系统状态是私有的，不应直接修改。以下策略规定了各种内部状态存储的升级特性：

  • 内部MapReduce状态数据将在相同主要版本的次要发布之间保持兼容，以促进在MapReduce工作负载执行时进行滚动升级。
  • HDFS在私有的、内部版本化格式中维护有关存储在HDFS中的数据的元数据。在发生不兼容的更改时，存储的版本号将递增。在升级现有集群时，如果可能，元数据存储将自动升级。升级完成后，始终可以反向升级过程。
  • AWS S3A guard保留了一个私有的、内部的元数据存储。现在，该功能已被移除，存储已过时并可以被删除。
  • YARN资源管理器保留有关应用程序和调度程序信息的私有、内部状态存储，该存储是版本化的。不兼容的更改将导致版本号递增。如果升级需要重新格式化存储，将在发布说明中指示。
  • YARN节点管理器保留了一个私有的、内部的应用程序信息状态存储，该存储是版本化的。不兼容的更改将导致版本号递增。如果升级需要重新格式化存储，将在发布说明中指示。
  • YARN联邦服务保留有关应用程序和集群信息的私有、内部状态存储，该存储是版本化的。不兼容的更改将导致版本号递增。如果升级需要重新格式化存储，将在发布说明中指示。

Hadoop配置

Hadoop使用两种主要形式的配置文件：XML配置文件和日志配置文件。

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分发的内容，例如JAR文件，可能随时更改，不应视为可靠，除了客户端工件。客户端工件及其内容将在主要版本内保持兼容。Hadoop开发社区的目标是允许应用程序代码在次要版本和尽可能的情况下在主要版本之间保持不变。当前的客户端工件列表如下：

  • hadoop-client
  • hadoop-client-api
  • hadoop-client-minicluster
  • hadoop-client-runtime
  • hadoop-hdfs-client
  • hadoop-hdfs-native-client
  • hadoop-mapreduce-client-app
  • hadoop-mapreduce-client-common
  • hadoop-mapreduce-client-core
  • hadoop-mapreduce-client-jobclient
  • hadoop-mapreduce-client-nativetask
  • hadoop-yarn-client

环境变量

某些Hadoop组件通过环境变量接收信息。例如，HADOOP_OPTS环境变量被大多数Hadoop进程解释为要在启动新JVM时使用的附加JVM参数的字符串。在次要发布之间，Hadoop解释环境变量的方式不会以不兼容的方式更改。换句话说，将相同的值放入相同的变量中应该为同一主要版本内的所有Hadoop发布产生相同的结果。

库依赖关系

Hadoop的运行依赖于大量的第三方库。尽量隐藏这些依赖关系免受下游开发者的影响是Hadoop开发社区的目标。尽管如此，Hadoop确实会向下游开发者公开一些依赖项，特别是在Hadoop 3之前。在主要版本之间，Hadoop不会通过客户端工件引入新的依赖项。

一个常见的下游反模式是使用hadoop classpath的输出来设置下游应用程序的类路径，或者将Hadoop附带的所有第三方JAR添加到下游应用程序的类路径。这种做法会在下游应用程序和Hadoop的第三方依赖之间创建紧密耦合，导致一个难以维护的应用程序，因为Hadoop的依赖关系发生变化。强烈不推荐这种做法。

Hadoop还包括一些本地组件，包括压缩、容器执行程序二进制文件和各种本地集成。这些本地组件引入了Hadoop的一组本地依赖项。本地依赖项的集合可能在次要版本中更改，但Hadoop开发社区将尽量将任何依赖项版本更改限制为次要版本更改。

硬件和操作系统依赖关系

Hadoop目前由Hadoop开发社区在x86和AMD处理器上运行的Linux和Windows上支持。这些操作系统和处理器未来可能会继续得到支持。如果支持计划更改，将记录要删除的操作系统或处理器，至少在实际删除之前应标记为已弃用一个完整的次要版本，但理想情况下是一个完整的主要版本。Hadoop可能在其他操作系统和处理器体系结构上运行，但在出现问题时，社区可能无法提供帮助。

不能保证Hadoop守护程序所需的最低资源在发布之间，甚至在维护版本中的变化。尽管如此，Hadoop开发社区将尽量避免在次要版本中增加要求。

Hadoop支持的任何文件系统，例如通过FileSystem API，大多数情况下将在整个主要版本内继续受到支持。

唯一的情况是，在主要版本中可以在提供对替代客户端实现的干净迁移路径的情况下，支持文件系统的支持可能会被删除。

参考资料

https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/AdminCompatibilityGuide.html