概述

本文基于 Apache hadoop 3.1.1 版本对Capacity Scheduler队列属性进行说明介绍。队列的部分属性对应于Yarn web中展示的队列信息。下表是Yarn web中的队列信息示例，在后面的队列属性介绍中，会指出属性对应于队列信息的哪个指标（如果有的话）。


Queue State:	RUNNING
Used Capacity:	<memory:0, vCores:0> (0.0%)
Configured Capacity:	<memory:0, vCores:0>
Configured Max Capacity:	unlimited
Effective Capacity:	<memory:755735, vCores:92> (15.0%)
Effective Max Capacity:	<memory:2519118, vCores:308> (50.0%)
Absolute Used Capacity:	0.0%
Absolute Configured Capacity:	15.0%
Absolute Configured Max Capacity:	50.0%
Used Resources:	<memory:
Configured Max Application Master Limit: 50.0
Max Application Master Resources:	<memory:1261568, vCores:1>
Used Application Master Resources:	<memory:0, vCores:0>
Max Application Master Resources Per User:	<memory:1261568, vCores:1>
Num Schedulable Applications:	0
Num Non-Schedulable Applications:	0
Num Containers:	0
Max Applications:	20000
Max Applications Per User:	2000
Configured Minimum User Limit Percent:	20%
Configured User Limit Factor:	0.5
Accessible Node Labels:	*
Ordering Policy:	FifoOrderingPolicy
Preemption:	disabled
Intra-queue Preemption:	disabled
Default Node Label Expression:	<DEFAULT_PARTITION>
Default Application Priority:	0

资源分配

yarn.scheduler.capacity.<queue-path>.capacity：队列资源容量的百分比，用浮点数表示(如12.5)或者是作为绝对资源队列的最小容量。在各层级上所有队列的百分比之和必须等于100。但是，如果配置的是绝对资源值，则子队列的绝对资源之和可能小于其父队列的绝对资源容量。在有空闲资源的情况，队列中的应用程序可能会消耗比队列容量更多的资源，这样可以使得队列具有弹性。这个参数对应 Yarn web页面中队列信息的 Absolute Configured Capacity。
yarn.scheduler.capacity.<queue-path>.maximum-capacity：队列最大资源容量的百分比，用浮点数表示或者是作为绝对资源队列的最大容量。限制队列中应用程序的弹性（由于资源共享，一个队列使用的资源量可能超过其容量，但最多使用资源量不能超过该资源量）。1) 如果表示百分比，则值介于 0 和 100之间；2）管理员需要确保每个队列的最大绝对资源容量>=绝对资源容量。此外，将此值设置为-1表示将最大容量设置为100%。这个参数对应 Yarn web页面中队列信息的 Absolute Configured Max Capacity。
yarn.scheduler.capacity.<queue-path>.minimum-user-limit-percent：对用户使用队列的最小资源比例进行限制，或者说是对每个用户最低使用资源的保障（百分比）。任何时刻，一个队列中每个用户可使用的资源量均有一定的限制。当一个队列中同时有多个用户提交应用程序时，每个用户的使用资源量会在一个最小值和最大值之间浮动，其中，最小值就是该参数指定的值，而最大值取决于提交应用程序的用户数。比如，假设minimum-user-limit-percent为25。当两个用户向该队列提交应用程序时，每个用户可使用资源量不能超过50%，如果三个用户提交应用程序，则每个用户可使用资源量不能超多33%，如果四个或者更多用户提交应用程序，则每个用户可用资源量不能超过25%。默认值是100，表示的是对用户使用的最小资源比例不进行限制。这个参数对应 Yarn web页面中队列信息的 Configured Minimum User Limit Percent。在实际使用中，一直没有明白该参数是怎么发挥作用的，只知道该参数会对Yarn web页面中队列信息的 Max Applications Per User 的值产生影响。
yarn.scheduler.capacity.<queue-path>.user-limit-factor：这个参数配置为允许单个用户最多能获取的队列资源（即yarn.scheduler.capacity.<queue-path>.capacity的值）的倍数，值是一个浮点值。也就是说如果把这个参数设置为大于1时，用户使用的资源可以超过队列资源。比如，假设该值为0.5，则任何时刻，单个用户使用的资源量不能超过该队列容量的50%；如果该值为2.0，则单个用户使用的最多资源量可以是该队列容量的200%，但无论配置为多大都不能超过队列的最大资源（即yarn.scheduler.capacity.<queue-path>.maximum-capacity的值）。默认值为1，确保单个用户无论集群有多空闲，永远不会占用超过队列配置的资源量。这个参数对应 Yarn web页面中队列信息的 Configured User Limit Factor 。
yarn.scheduler.capacity.<queue-path>.maximum-allocation-mb: 向ResourceManager请求分配给队列中container内存资源时的最大值。这个配置覆盖集群配置项 yarn.scheduler.maximum-allocation-mb。这个值必须小于等于集群的最大值。这个配置可以使的不同队列的container的最大内存值可以不一样，用户可以根据生产环境中实际的需求对不同的队列设置不同的值，可以更进一步提高集群的资源使用率。
yarn.scheduler.capacity.<queue-path>.maximum-allocation-vcores: 向ResourceManager请求分配给队列中container vcore资源时的最大值。这个配置覆盖集群配置项yarn.scheduler.maximum-allocation-vcores。这个值必须小于等于集群的最大值。这个配置可以使的不同队列的container的最大内存值可以不一样，用户可以根据生产环境中实际的需求对不同的队列设置不同的值，可以更进一步提高集群的资源使用率。
yarn.scheduler.capacity.<queue-path>.user-settings.<user-name>.weight: 此浮点值用于计算队列中用户的用户限制资源值。该值将使每个用户的权重大于或小于队列中的其他用户。例如，如果用户A在队列中收到的资源比用户B和C多50%，则用户A的此属性将设置为1.5。用户B和C将设置为默认值1.0。也就说同一队列中权重越大的用户获得的资源将会越多。

使用绝对值配置资源

从Apache hadoop 3.1.0开始 CapacityScheduler支持配置绝对值格式的资源量。上面的 yarn.scheduler.capacity.<queue-path>.capacity 和 yarn.scheduler.capacity.<queue-path>.max-capacity 配置项，可以指定一个绝对资源量如 [memory=10240,vcores=12]。这表示为队列配置10GB的内存和12个Vcore。使用绝对值资源配置时，这2个参数分别对应Yarn web页面中队列信息的__Configured Capacity__和__Configured Max Capacity__。

配置示例如下：

  <property>
    <name>yarn.scheduler.capacity.root.default.capacity</name>
    <value>[memory=16000,vcores=4]</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.maximum-capacity</name>
    <value>[memory=48000,vcores=12]</value>
  </property>

并且不同的队列同时可以使用不同的资源配置格式，也就是说有些队列可以使用百分比格式，有些可以使用绝对值格式，而且实际使用时发现在这种混合配置中，各层级上所有队列的百分比之和必须等于100的约束将不再有效。如下：

 <property>
    <name>yarn.scheduler.capacity.root.queue1.capacity</name>
    <value>[memory=160000,vcores=40]</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.maximum-capacity</name>
    <value>[memory=480000,vcores=2000]</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue2.capacity</name>
    <value>30.0</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue2.maximum-capacity</name>
    <value>50.0</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.queue3.capacity</name>
    <value>80.0</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue3.maximum-capacity</name>
    <value>-1</value>
  </property>

上述配置中，queue2和queue3的容量之和为110已经超出了100，但是依然有效。

应用程序数目限制

yarn.scheduler.capacity.maximum-applications / yarn.scheduler.capacity.<queue-path>.maximum-applications ：集群或者队列中同时处于running和pending状态的应用程序数目上限，这是一个强限制，一旦集群中应用程序数目超过该上限，后续提交的应用程序将被拒绝，默认值为10000。整个root队列的数目上限可通过参数yarn.scheduler.capacity.maximum-applications设置（可看做默认值），单个队列可通过参数 yarn.scheduler.capacity.<queue-path>.maximum-applications 单独设置自己的值。如果不单独设置，那么对应队列的maximum-applications会按照资源占比计算。如某个队列的资源占比是15%，那么它的maximum-applications就是10000 * 15 % = 1500。在实际使用中发现，如果队列使用了绝对资源格式配置，则单独指定的方式不会生效，只会根据队列资源占比来计算。这个参数对应 Yarn web页面中队列信息的__Max Applications__。
yarn.scheduler.capacity.maximum-am-resource-percent / yarn.scheduler.capacity.<queue-path>.maximum-am-resource-percent：集群中用于运行应用程序ApplicationMaster的资源比例上限，该参数通常用于限制处于活动状态的应用程序数目。该参数类型为浮点型，默认是0.1，表示10%。所有队列的ApplicationMaster资源比例上限可通过参数yarn.scheduler.capacity. maximum-am-resource-percent设置（可看做默认值），单个队列可通过参数__yarn.scheduler.capacity.<queue-path>. maximum-am-resource-percent__ 单独设置自己的值。如果不单独设置，那么就使用 yarn.scheduler.capacity.maximum-am-resource-percent 的值。这个参数对应 Yarn web页面中队列信息的__Configured Max Application Master Limit__。

队列权限管理

yarn.scheduler.capacity.<queue-path>.state ：队列状态可以为STOPPED或者RUNNING，如果一个队列处于STOPPED状态，用户不可以将应用程序提交到该队列或者它的子队列中，类似的，如果ROOT队列处于STOPPED状态，用户不可以向集群中提交应用程序，但正在运行的应用程序仍可以正常运行结束，以便队列可以优雅地退出。这个参数对应 Yarn web页面中队列信息的 Queue State。
yarn.scheduler.capacity.root.<queue-path>.acl_submit_applications：限定哪些Linux用户/用户组可向给定队列中提交应用程序。需要注意的是，该属性具有继承性，即如果一个用户可以向某个队列中提交应用程序，则它可以向它的所有子队列中提交应用程序。配置该属性时，用户之间或组之间用“，”分割，用户和用户组之间用空格分割，比如“user1,user2 group1,group2”。
yarn.scheduler.capacity.root.<queue-path>.acl_administer_queue：为队列指定一个管理员，该管理员可控制该队列的所有应用程序，比如杀死任意一个应用程序等。如果该属性的ACL未指定则从其父队列继承。

基于用户或组的队列映射

多租户场景下，不同的用户需要使用不同的队列，通过队列映射特性可以使的不同用户提交的作业运作到指定的队列中。

yarn.scheduler.capacity.queue-mappings：该配置可以将用户或组映射到指定的队列。用户可以映射一个单独的用户或者一个用户列表到队列。语法为：[u or g]:[name]:[queue_name][,next_mapping]*。这里，u或者g表是映射是针对用户还是组。u表示用户，g表示组。name 表示用户名或者组名。要指定提交应用程序的用户，可以用%user表示。queue_name表示应用程序映射的队列名称。如果要指定队列名称与用户名称相同，可以用%user表示。如果要指定队列名称与用户所属的primary组名相同，可以用%primary_group表示。
yarn.scheduler.capacity.queue-mappings-override.enable：指定用户指定的队列是否可以被覆盖。布尔值，默认为false。

示例：

<property>
   <name>yarn.scheduler.capacity.queue-mappings</name>
   <value>u:user1:queue1,g:group1:queue2,u:%user:%user,u:user2:%primary_group</value>
 </property>

上述配置中，用户user1映射到队列queue1，组group1映射到队列queue2，u:%user:%user，是将用户映射到与用户名同名的队列中，user2映射到与其primary group同名的队列中。映射是从左到右进行匹配的，第一个匹配的映射将会被使用。

应用程序的生存期(lifetime)

从Apache hadoop2.9.0开始， Capacity Scheduler新增支持应用程序的生存期管理特性。

yarn.scheduler.capacity.<queue-path>.maximum-application-lifetime：队列中应用程序的最大生存期（单位为秒）。任何设置为小于等于0的值，表示不启用此功能。该配置是一个硬限制，当应用程序的运行时间超出该时间后将会被kill掉，用户也可以在提交应用程序的context中指定该值，但是如果用户设置的值超出此处设置的值，那么用户指定的值将会被覆盖。该特性只适用于叶子队列。
yarn.scheduler.capacity.root.<queue-path>.default-application-lifetime：队列中应用程序的默认生存期（单位为秒）。任何设置为小于等于0的值，表示不启用此功能。当用户提交作业时不指定生存期的时候会使用该默认值，该配置不能大于最大生存期。该特性只适用于叶子队列。

一个完整的配置示例

下面的示例中同时使用了对值资源配置和百分比配置，从目前测试以及使用来看可能还存在不完善的地方。生产环境中目前还是建议统一使用百分比配置或是绝对值资源配置，不要混合配置使用，这样方便对集群资源进行管理。

<configuration>
  <property>
    <name>yarn.scheduler.capacity.maximum-applications</name>
    <value>50000</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.maximum-am-resource-percent</name>
    <value>0.1</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queues</name>
    <value>default，queue1</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.capacity</name>
    <value>10</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.default.maximum-capacity</name>
    <value>20</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.user-limit-factor</name>
    <value>1</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.default.minimum-user-limit-percent</name>
    <value>100</value>
    <description></description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.user-settings.userA.weight</name>
    <value>2</value>
    <description>userA的权重为2，相比其他用户可以获得更多的资源</description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.state</name>
    <value>RUNNING</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.acl_submit_applications</name>
    <value>*</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.acl_administer_queue</name>
    <value>hadoop</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.default.default-application-lifetime</name>
    <value>14400</value>
    <description>队列的默认应用程序生存期，4小时</description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.default.maximum-application-lifetime</name>
    <value>28800</value>
    <description>队列的最大应用程序生存期，8小时</description>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.queue1.capacity</name>
    <value>[memory=160000,vcores=40]</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.queue1.maximum-capacity</name>
    <value>[memory=9000000,vcores=2000]</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.user-limit-factor</name>
    <value>5</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.queue1.minimum-user-limit-percent</name>
    <value>100</value>
    <description></description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.state</name>
    <value>RUNNING</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.acl_submit_applications</name>
    <value>user1</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.acl_administer_queue</name>
    <value>hadoop</value>
  </property>
    <property>
    <name>yarn.scheduler.capacity.root.queue1.default-application-lifetime</name>
    <value>3600</value>
    <description>队列的默认应用程序生存期，1小时</description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.root.queue1.maximum-application-lifetime</name>
    <value>7200</value>
    <description>队列的最大应用程序生存期，2小时</description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.queue-mappings</name>
    <value>u:hadoop:default,u:user1:queue1,u:%user:%user</value>
  </property>
  <property>
    <name>yarn.scheduler.capacity.resource-calculator</name>
    <value>org.apache.hadoop.yarn.util.resource.DominantResourceCalculator</value>
    <description>使用的资源计算器是DominantResourceCalculator</description>
  </property>
  <property>
    <name>yarn.scheduler.capacity.queue-mappings-override.enable</name>
    <value>false</value>
  </property>
</configuration>

参考：https://hadoop.apache.org/docs/r3.1.1/hadoop-yarn/hadoop-yarn-site/CapacityScheduler.html#Queue_Properties