编辑文章 - 博客频道 - youkuaiyun.com

1目的

本篇文档介绍Apache Hadoop项目的目标：相容性。hadoop的发布影响Hadoop的开发者，以前的项目。Hadoop的发布和最终用户之间的兼容性的不同类型是可列举的。对于每一种兼容性：描述了以前项目和最终用户的影响，在使用的情况下，呼喊在改变的不相容性在Hadoop的开发者是能够允许的的策略。

2兼容类型

2.1Java API

Hadoop的接口和类的注释描述了预期的观众和稳定性为了保持和以前版本的兼容性。看Hadoop的Interface和Classification获得更多内容。

InterfaceAudience：获得了预期的观众，值可能是Public（为最终用户和外围的项目），LimitedPrivate （为其他的Hadoop构成，和相关的项目，比如YARN,MapReduce,HBase,等)和Private（为内部构成使用）。

InterfaceStability：描述了接口改变成什么类型是允许的。可能的值是Stable,Evolving,Unstable,和Deprecated。

2.2Use Cases

1.Public-Stable API 兼容性被要求保证最终用户的项目和下游项目能够继续工作，不需要修改。

2.LimitedPrivate-Stable API兼容性被要求允许单独构件通过镜像发布可以升级。

3.Private-Stable API兼容性被要求滚动升级。

2.3Policy

1.Public-Stable APIs反对在一个重要的发布移走前至少有一个重要的发布。

2LimitedPrivate-Stable APIs 可以通过重要的发布改变，而不是在一个主要版本。

3.Public-Stable APIs可以通过重要的发布改变，而不是在一个主要的版本。

4.注意：APIs从源文件生成需要兼容滚动升级。通过wire-compatibility章节获得更多的描述。APIs和wire-communication的兼容性策略需要手牵手的去解决。

3.Semantic compatibility

 apache hadoop 努力保证APIs的行为和以前版本保持一致，虽然改变的正确性可能导致行为的改变。测试和Java文档确定了API的行为。社区在确定一些API的处理中更严谨，提高测试单元来验证规范，为行为的子集有效的创建一个正式的规范可以很容易的被测试。

Policy

API的行为可以被改变以修复错误的行为，这种变化伴随着更新现有的试验或者添加在案例中的测试这些在之前是没有变化的。

4.Wire compatibility

Wire compatibility关心数据在hadoop处理过程中通过电线被传播。对于大多数的RPC通信Hadoop使用Protocol Buffers。Preserving compatibility要求禁止就像以下的描述。Non-RPC通信也应该被考虑，比如使用HTTP传输一个HDFS图像作为简介的一部分或者传输MapTask的输出。潜在的通信可以被分为：

（1）.Client-Server：在Hadoop的客户端和服务器端的通信。

（2）.Client-Server（Admin）:分辨Client-Server 协议的子集是值得的，Client-Server协议使用单一管理命令行就像这些协议仅仅影响管理者，管理者能够忍受改变，而最终用户不会。

（3）.Server-Server：servers之间的通信。

4.2Use Cases

(1)Client-Server 兼容性被要求允许用户继续使用老的客户端即使升级了Server以后。比如，一个Hadoop 2.1.0客户端和一个Hadoop 2.3.0集群的通信。

(2)Client-Server 兼容性也被要求允许升级个人版组件而不升级其他的。比如，把HDFS从版本2.1.0升级到2.2.0而不升级MapReduce。

(3)Server-Server 兼容性被要求允许最大的版本在一个活跃的集群，所以这个集群可能被升级在回滚方法中没有停止。

4.3Policy

(1)Client-Server和Server-Server的兼容性在一个重要的版本中是被保护的。

(2)兼容性可以被损坏仅仅在一个重要的发布中，尽管破坏了兼容性甚至在重要版本有严重的后果，应该在Hadoop社区中被讨论。

(3)Hadoop协议在.proto文件中被定义。Client-Server协议和Server-Server协议 .proto文件被标记为稳定的。当一个.proto文件被标记为稳定的，它意味着改变应该在一个兼容性的版本中被制定就像以下描述：

 。。。。以下的改变是兼容的，也是在任何时间都被允许的：

。。。。。。添加一个可选字段，与预期的代码处理字段丢失，由于和老版本的代码通信。

。。。。。。添加一个新的rpc/method到服务器。

。。。。。。添加一个新的可选请求到一个Message。

。。。。。。重命名一个字段。

。。。。。。重命名一个.proto文件。

。。。。。以下的改变是不兼容的，但是可以被考虑仅仅在一个重要的发布中：

。。。。。。。改变rpc/method的名称。

。。。。。。。改变rpc/method参数类型或者返回类型。

。。。。。。。移除一个rpc/method。

。。。。。。。改变一个service的名称。

。。。。。。。改变一个Message的名称。

。。。。。。。修改一个字段的类型以一个不兼容的方法。

。。。。。。。改变一个可选的字段为必须的。

。。。。。。。添加或者删除一个必须的字段。

。。。。。。。删除一个可选的字段就像可选的字段有合理的默认的允许删除。

。。。。。以下的改变是不兼容的因此从来不被允许：

。。。。。。。改变一个字段的Id。

。。。。。。。重新使用一个老的字段，这个字段是以前被删除的。

。。。。。。。字段的数值廉价的，不断变化的和重用，不是一个好的方法。

5.Java Binary Compatibility for end-user applications i.e. Apahce Hadoop ABI

就像Apache Hadoop版本升级的用户合理的认为他们的应用应该无需任何修改继续工作。这是由于支持API实现语义兼容性，兼容性和线兼容。

然而，Apache Hadoop是一个非常复杂，分布系统和服务非常广泛的使用案例。特别的，Apache Hadoop MapReduce是一个非常非常广泛的API；在某种意义上用户可以进行广泛的假设，例如，本地磁盘布局时，他们的map/reduce任务是执行的，环境变量对于他们的任务等。

5.2Use cases

（1）.已存在的MapReduce应用，包括已存在的成套的最终用户的应用和项目的jar,比如Apache Pig，Apache Hive，Cascading等，应该工作未修订当指出一个升级的Apache Hadoop集群在一个重要的版本中。

（2）已存在的YARN应用，包括已存在的成套的最终用户的应用和项目的jars，比如Apache Tez等，应该在指出一个升级的Apache Hadoop集群在一个重要的发布中工作。

（3）已存在的应用，HDFS的输入/输出数据交换，包括已存在的最终用户应用和框架的jars比如Apache Flume，在指出一个未升级的Apache Hadoop集群在一个主要的版本中工作。

5.3Policy

(1)已有的MapReduce，YARN和HDFS应用和框架应该工作在一个重要的发布版本中，i.e.Apache Hadoop ABI是支持的。

(2)一个应用非常小的一部分可能被磁盘布局的改变而影响，开发者社区努力减少这些变化并不会在他们的小版本中。在大多数极坏的情况下，我们将会考虑强还原这些变化和无效的违规发布必要的话。

(3)特别对于MapReduce应用，开发者社区将会尝试我们最大的努力支持提供二进制的兼容性通过重要的发布，e.g.应用使用org.apache.hadoop.mapred。

(4)APIs支持兼容性从Hadoop-1.x到hadoop-2.x。

6.REST APIs

 REST API兼容性符号了request和response到每一个request。Hadoop REST APIs是专门为客户在发布使用稳定，甚至主要的发行版本。下面是被暴露的REST APIs

（1）WebHDFS-稳定的(2)ResourceManager（3）NodeManager（4）MR Application Master（5）History Server

6.2Policy

APIs在上面的文本注释稳定保持在至少一个主要版本的兼容性，也许不赞成一个主要发布新版本的API。

7.Metrics/JMX

然而Metrics API兼容性是通过Java API兼容性管理的，暴露在Hadoop的实际指标需要兼容的用户能够使用它们的自动化。添加额外的度量是兼容的。修改或者移除已存在的度量打破兼容性。相似的，改变JMX MBean 对象的名称也是破坏兼容性。

7.1Policy

Metrics应该在以前的重要的发布中保护兼容性。

8.File formats 和 Metadata

用户和系统级的数据（包括元数据）存储在不同格式的文件。改变元数据或者文件格式使用存储数据/元数据可以导致版本间的不兼容性。

9.User-level file formats

改变格式最终用户用来存储他们的数据可以防止他们在以后的版本中访问数据，因此，它是高度重要的保存这些文件格式的兼容性。一个能够总是添加一个新的格式改善以前已存在的格式。这些格式的例子包括har、war、SequenceFileFormat等。

9.1Policy

Non-forward-compatible user-file 格式改变对于一个重要的发布是受限制的。当user-file 格式改变时，新的发布是被希望读取已有的格式，但是可能以这种格式写数据不兼容伴随以前的版本。同时，社区应该选择创建一个新的格式，程序必须选择在代替现有的格式制作的不兼容性的改变。

10.System-internal file formates

Hadoop 内部的数据也被存储在文件中，又改变这些格式也导致不兼容性。然而这些改变不像user-level file 格式一样有毁灭性的，一个策略时的兼容性可以打破是重要的。

11MapReduce

MapReduce 使用的格式像I-File来存储MapReduce-specific数据。

11.1Policy

MapReduce-internal格式像IFile在一个重要的发布中保存兼容性。改变这些格式能够引起in-flight工作失败，因此我们应该保证新的客户端能够从老的版本中拿取shuffle-data以一个兼容性的方式。

12.HDFS Metadata

HDFS以一个特殊的格式保持元数据。不兼容性改变了格式或者元数据阻止随后的版本从读取老的元数据。这种不兼容性的改变可能要求一个HDFS“升级”来改变元数据使它可以访问。一些改变要求更多比一个这样的“升级”。

根据变化中的不相容性的程度，以下潜在的情况下可以出现：

（1）Automatic：图片自动升级，不需要明确的“升级”。

（2）Direct：图片不升级，但是应该要求一个明确的版本“升级”。

（3）Indirect：图片不升级，但是应该要求提高中间的版本。

（4）Not upgradeable：图像不升级。

12.1Policy

（1）一个版本升级必须允许一个集群可以回滚到老的版本和老的磁盘格式。回滚需要存储原来的数据，但是不要求恢复最新的数据。

（2）HDFS元数据改变必须是不升级的通过任何的升级路径-automatic, direct or indirect.

（3）更多的描述策略依靠于升级的类型是被考虑的。

13 Command Line Interface（CLI）

Hadoop命令行项目可能使用直接通过系统shell或者通过shell脚本。改变一个命令的路径，移除或者重命名一个命令行可选项，参数的顺序，或者命令返回的代码和破坏兼容性的输出和可能对用户产生不利影响。

13.1Policy

CLI命令行反对一个重要的版本在他们移除或不兼容性修改在一个随后的重要的版本之前。

14.Web UI

Web UI,特别的内容和web页面的布局，改变能改潜在的干涉尝试擦了web页面的信息。

14.1Policy

Web pages是注定不会被刮，因此不兼容的改变在任何时间是被允许的。用户希望使用REST APIs来获得任何信息。

15Hadoop Configuration Files

用户使用（1）Hadoop-defined 属性来配置和给Hadoop提供提示，（2）惯有的属性通过对于jobs的信息。因此，配置属性的兼容性有两方面：

（1）修改键的名称，值的单元，和Hadoop-defined属性默认值。

（2）自定义配置属性键不应该与Hadoop定义的命名空间冲突。典型的，用户应该避免使用Hadoop前缀：hadoop,io,ipc,fs,net,file,ftp,s3,kfs,ha,file,dfs,mapred,mapreduce,yarn。

15.1Policy

（1）Hadoop自定义属性被反对在被移除前至少有一个重要的版本，修改已存在的属性是不允许的。

（2）Hadoop-defined属性默认值能够通过minor/major版本改变，但仍将是相同的点在一个小发布版本。

（3）目前，没有明确的政策关于当新前缀被添加/删除，和前缀的列表从自定义的配置属性中拒绝。然而，应该注意上面的，用户应该避免使用Hadoop前缀，比如：hadoop,io,ipc,fs,net,file,ftp,s3,kfs,ha,file,dfs,mapred,mapreduce,yarn.

16Directory Structure

源代码，文物（源代码和测试），用户日志，配置文件，输出和作业历史都存储在磁盘上的本地文件系统或HDFS。改变这些目录结构，用户访问文件破坏陪兼容性，甚至在这些情况下，源始路径通过典型的连接被保护。

16.1Policy

（1）源代码的布局和建设的文物随时可以改变，特别是在主要的版本。在一个主要的版本，开发者将尝试目录结构的保护；然而，单独的文件能够被添加、移动、删除。确保补丁停留在与代码同步的最好方式就是让他们致力于Apache源树。

（2）配置文件的目录结构，用户日志，和作业历史将被保护通过少数的和要点版本在一个重要的版本中。

17Java Classpath

用户应用在建立Hadoop之前应该添加所有的Hadoop的Jars（包括Hadoop依赖的库文件）到应用程序的路径。添加新的依赖或者更新已存在的依赖的版本可能干涉在应用程序路径中的。

17.1Policy

目前，没有策略当Hadoop依赖的可以改变。

18Environment variables

用户和相关的项目经常使用输出环境变量，因此移动或者重命名环境变量是不兼容的。

18Build artifacts

Hadoop使用maven来管理项目和不断变化的工件可以影响现有用户的工作流程。

18.1Policy

（1）Test artifacts:产生的测试进行严格的内部使用都是可望不可及的Hadoop使用外，类似的API注释的@Private,@Unstable。

（2）Built artifacts：Hadoop的客户端的artifact(maven groupid:artifactId)在一个重要的版本中保持兼容性，然而其他的构件可以在不兼容的方式改变。

19.Hardware/Software Requirements

为了跟上最新的硬件，操作系统，JVMs，和其他的软件，新Hadoop版本或者它的功能需要高版本的。对于一个特定的环境，提示Hadoop可能需要升级其他相关的软件组成。

19.1Policy

（1）硬件：

。。。。。Architecture，社区没有计划限制Hadoop特定的架构，但是可以有家庭特定的优化。

。。。。。Minimum resources：然而这里没有担保在最小资源要求通过Hadoop守护进程，社区尝试不增加需求在一个重要的版本。

（2）操作系统：社区将尝试保持相同操作系统的必需条件在一个小的版本中，目前，GNU/Linux和Microsoft Windows操作系统是微软的官方支持的社区而Apache Hadoop是已知的合理工作以及在其他的操作凶，如苹果MacOSX，Solaris等。

（3）虚拟机要求不会改变整个点发布在同一个小的版本，除非在问题变得不支持JVM版本。Minor/major版本要求后续的JVM版本对于一些/所有的JVM版本支持的操作系统。

（4）其他软件：社区尝试维持其他软件的最小版本通过Hadoop要求。例如，ssh,kerberos等。