<ahref="http://maven.apache.org/"title="Built by Maven"class="poweredBy">
<imgalt="Built by Maven"src="../images/logos/maven-feather.png"/>
</a>
</div>
</div>
<divid="bodyColumn">
<divid="contentBox">
<!---
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. See accompanying LICENSE file.
-->
<h1>YARN Service Configurations</h1>
<p>This document describes how to configure the services to be deployed on YARN.</p>
<p>There are mainly three types of configurations:</p>
<ul>
<li>The configurations specific to the custom service running on YARN . E.g. the hbase-site.xml for a Hbase service running on YARN.
<ul>
<li>It can be specified at both global service level(<code>Service#configuration</code>) or component level(<code>Component#configuration</code>).</li>
<li>Service-level configs are considered as the default configs for all components and component-level config can override service level config.</li>
<li>All config properties that uses constant variables as described below are subject to substitutions.</li>
</ul>
</li>
<li>The configurations specific to YARN service AM. (<code>Configuration#properties</code>).
<ul>
<li>E.g. The <code>yarn.service.am-restart.max-attempts</code> which controls how many times the framework AM can be retried if it fails. These configs are mainly to control the behavior of the framework AM , rather than the custom services launched by the framework.</li>
</ul>
</li>
<li>Some constants such as <code>SERVICE_NAME</code> for referring some system properties.
<ul>
<li>They are substituted by the service AM before writing the config files.</li>
</ul>
</li>
</ul>
<p>Below describes the details for each type of configurations.</p><section>
<h2><aname="Configuration_for_custom_service"></a>Configuration for custom service</h2>
<p>Below is how a configuration object typically looks like:</p>
<divclass="source">
<divclass="source">
<pre>"configuration" : {
"properties" : {
"yarn.service.am-restart.max-attempts" : 10 // config for the service AM
},
"env" : { // The environment variables to be exported when container gets launched
"env1" : "val1"
},
"files" : [ // The list of configuration files to be mounted for the container
{
"type": "HADOOP_XML", // The format of the config file into which the "properties" are dumped
"dest_file": "/etc/hadoop/conf/core-site.xml", // The location where the config file is mounted inside the container
"properties" : { // The list of key/value pairs to be dumped into the config file
"fs.defaultFS" : "hdfs://myhdfs" // This property will be written into core-site.xml
}
},
{
"type": "HADOOP_XML", // The format of the config file.
"src_file" : ""hdfs://mycluster/tmp/conf/yarn-site.xml"" // The location of the source config file to be downloaded
"dest_file": "/etc/hadoop/conf/yarn-site.xml", // The location where the config file will be mounted inside the container/
<li>properties: the configurations for service AM. Details below.</li>
<li>env : the environment variables to be exported when container gets launched.</li>
<li>files : The list of configuration files to be mounted inside the container.
<ul>
<li>type: The format of the config file(<code>dest_file</code>) to be mounted inside the container. If <code>src_file</code> is specified, it is also the format for both <code>src_file</code> and <code>dest_file</code>.</li>
<li>HADOOP_XML : the hadoop xml format. If <code>src_file</code> is specified, the file content will be read as parsed in hadoop xml format.</li>
<li>XML : the standard xml format</li>
<li>JSON : the standard JSON format</li>
<li>YAML : the YAML format</li>
<li>PROPERTIES : the java PROPERTIES format</li>
<li>TEMPLATE : the plain text format. If <code>src_file</code> is specified, the content of the <code>src_file</code> will be written into <code>dest_file</code> post constant substitution. If <code>src_file</code> is not specified, use <code>content</code> as the key in <code>properties</code> field, and the value will be the actual content to be written in the <code>dest_file</code> post constant substitution. E.g
<p>The string <code>Hello world</code> will be written into a file located at <code>/etc/conf/hello</code> inside the container.</p></li>
<li>src_file : [optional], the source location of the config file at a network accessible location such as hdfs.</li>
<li>The format of both <code>src_file</code> and <code>dest_file</code> are defined by <code>type</code>.</li>
<li>Currently, It only works with <code>HADOOP_XML</code> and <code>TEMPLATE</code> type.</li>
<li>The <code>src_file</code> will be downloaded by YARN NodeManager and be mounted inside the container as in the location specified by <code>dest_file</code>.</li>
<li>If any properties specified in the <code>properties</code> field, they are added into (or overwriting existing properties in) the <code>src_file</code>.</li>
<li>If <code>src_file</code> is not specified, only the properties in the <code>properties</code> field will be written into the <code>dest_file</code> file.</li>
<li>dest_file : the location where the config file is mounted inside the container. The file format is defined by <code>type</code>. dest_file can be an absolute path or a relative path. If it’s a relative path, the file will be located in the <code>$PWD/conf</code> directory (where <code>$PWD</code> is the container local directory which is mounted to all docker containers launched by YARN)</li>
<li>properties : The list of key/value pair configs to be written into the <code>dest_file</code> in the format as defined in <code>type</code>. If <code>src_file</code> is specified, these properties will be added into (or overwriting existing properties in) the <code>src_file</code>.</li>
</ul>
</li>
</ul></section><section>
<h2><aname="Configuration_for_YARN_service_AM"></a>Configuration for YARN service AM</h2>
<p>This section describes the configurations for configuring the YARN service AM.</p><section>
<p>System-wide service AM properties can only be configured in the cluster <code>yarn-site.xml</code> file.</p>
<tableborder="0"class="bodyTable">
<thead>
<trclass="a">
<th> System-Level Config Name </th>
<th> Description </th></tr>
</thead><tbody>
<trclass="b">
<td>yarn.service.framework.path </td>
<td> HDFS path of the service AM dependency tarball. When no file exists at this location, AM dependencies will be uploaded by the RM the first time a service is started or launched. If the RM user does not have permission to upload the file to this location or the location is not world readable, the AM dependency jars will be uploaded each time a service is started or launched. If unspecified, value will be assumed to be /yarn-services/${hadoop.version}/service-dep.tar.gz.</td></tr>
<trclass="a">
<td>yarn.service.base.path </td>
<td> HDFS parent directory where service artifacts will be stored (default ${user_home_dir}/.yarn/).</td></tr>
<td> Retry interval in milliseconds for the service client to talk to the service AM (default 2000, i.e. 2 seconds).</td></tr>
<trclass="b">
<td>yarn.service.queue </td>
<td> Default queue to which the service will be submitted (default submits to the <code>default</code> queue). Note that queue can be specified per-service through the queue field, rather than through the service-level configuration properties.</td></tr>
<p>Service-level service AM configuration properties can be specified either in the cluster <code>yarn-site.xml</code> at the global level (effectively overriding the default values system-wide) or specified per service in the <code>properties</code> field of the <code>Configuration</code> object as in the example below:</p>
<td> Timeout in milliseconds after which a newly started service AM releases all the containers of previous AM attempts which are not yet recovered from the RM (default 120000, i.e. 2 minutes).</td></tr>
<trclass="b">
<td>yarn.service.failure-count-reset.window </td>
<td> Interval in seconds after which the container failure counts that will be evaluated for the per-component <code>yarn.service.container-failure-per-component.threshold</code> and <code>yarn.service.node-blacklist.threshold</code> are reset (default 21600, i.e. 6 hours).</td></tr>
<td> Interval in seconds between readiness checks (default 30 seconds).</td></tr>
<trclass="b">
<td>yarn.service.log.include-pattern </td>
<td> Regex expression for including log files by name when aggregating the logs after the application completes (default includes all files).</td></tr>
<trclass="a">
<td>yarn.service.log.exclude-pattern </td>
<td> Regex expression for excluding log files by name when aggregating the logs after the application completes. If the log file name matches both include and exclude pattern, this file will be excluded (default does not exclude any files).</td></tr>
<td> Regex expression for excluding log files by name when aggregating the logs while app is running. If the log file name matches both include and exclude pattern, this file will be excluded.</td></tr>
<trclass="b">
<td>yarn.service.classpath </td>
<td> Comma separated extra class path parameters for yarn services AM. These path elements will be appended to the end of the YARN service AM classpath. </td></tr>
<trclass="a">
<td>yarn.service.am.client.port-range </td>
<td> Range of ports that the Yarn Service AM can use when binding. Leave blank if you want all possible ports. For example 50000-50050,50100-50200. </td></tr>
<p>Component-level service AM configuration properties can be specified either in the cluster <code>yarn-site.xml</code> at the global level (effectively overriding the default values system-wide), specified per service in the <code>properties</code> field of the <code>Configuration</code> object, or specified per component in the <code>properties</code> field of the component’s <code>Configuration</code> object.</p>
<td> Failure validity interval in milliseconds. When set to a value greater than 0, the container retry policy will not take the failures that happened outside of this interval into the failure count (default -1, which means that all the failures so far will be included in the failure count).</td></tr>
<td> The container health threshold percent when explicitly set for a specific component or globally for all components, will schedule a health check monitor to periodically check for the percentage of healthy containers. A container is healthy if it is in READY state. It runs the check at a specified/default poll frequency. It allows a component to be below the health threshold for a specified/default window after which it considers the service to be unhealthy and triggers a service stop. When health threshold percent is enabled, yarn.service.container-failure-per-component.threshold is ignored.</td></tr>
<td> Health check monitor poll frequency. It is an advanced setting and does not need to be set unless the service owner understands the implication and does not want the default. The default is 10 secs.</td></tr>
<td> The amount of time the health check monitor allows a specific component to be below the health threshold after which it considers the service to be unhealthy. The default is 600 secs (10 mins).</td></tr>
<td> The amount of initial time the health check monitor waits before the first check kicks in. It gives a lead time for the service containers to come up for the first time. The default is 600 secs (10 mins).</td></tr>
<td> The boolean flag indicates that if this component is finished, the service is also terminated. The default is false.</td></tr>
</tbody>
</table>
<p>There is one component-level configuration property that is set differently in the <code>yarn-site.xml</code> file than it is in the service specification. To select the docker network type that will be used for docker containers, <code>docker.network</code> may be set in the service <code>Configuration</code><code>properties</code> or the component <code>Configuration</code><code>properties</code>. The system-wide default for the docker network type (for both YARN service containers and all other application containers) is set via the <code>yarn.nodemanager.runtime.linux.docker.default-container-network</code> property in the <code>yarn-site.xml</code> file.</p></section><section>
<p>The AM can be configured to perform readiness checks for containers through the <code>Component</code> field <code>readiness_check</code>. A container will not reach the <code>READY</code> state until its readiness check succeeds. If no readiness check is specified, the default readiness check is performed unless it is disabled through the <code>yarn.service.default-readiness-check.enabled</code> component-level configuration property.</p>
<p>The default readiness check succeeds when an IP becomes available for a container. There are also optional properties that configure a DNS check in addition to the IP check. DNS checking ensures that a DNS lookup succeeds for the container hostname before the container is considered ready. For example, DNS checking can be enabled for the default readiness check as follows:</p>
<divclass="source">
<divclass="source">
<pre>"readiness_check": {
"type": "DEFAULT",
"properties": {
"dns.check.enabled": "true"
}
},
</pre></div></div>
<p>Here is a full list of configurable properties for readiness checks that can be performed by the AM.</p>
<tableborder="0"class="bodyTable">
<thead>
<trclass="a">
<th> Readiness Check </th>
<th> Configurable Property </th>
<th> Description </th></tr>
</thead><tbody>
<trclass="b">
<td>DEFAULT, HTTP, PORT</td>
<td> dns.check.enabled </td>
<td> true if DNS check should be performed (default false)</td></tr>
<trclass="a">
<td>DEFAULT, HTTP, PORT</td>
<td> dns.address </td>
<td> optional IP:port address of DNS server to use for DNS check</td></tr>
<trclass="b">
<td>HTTP</td>
<td> url </td>
<td> required URL for HTTP response check, e.g. <aclass="externalLink"href="http://${THIS_HOST}:8080">http://${THIS_HOST}:8080</a></td></tr>
<trclass="a">
<td>HTTP</td>
<td> timeout </td>
<td> connection timeout (default 1000)</td></tr>
<trclass="b">
<td>HTTP</td>
<td> min.success </td>
<td> minimum response code considered successful (default 200)</td></tr>
<trclass="a">
<td>HTTP</td>
<td> max.success </td>
<td> maximum response code considered successful (default 299)</td></tr>
<trclass="b">
<td>PORT</td>
<td> port </td>
<td> required port for socket connection</td></tr>
<h4><aname="Warning_on_configuring_readiness_checks_with_host_network_for_docker_containers"></a>Warning on configuring readiness checks with <code>host</code> network for docker containers</h4>
<p>When the <code>host</code> docker network is configured for a component that has more than one container and the containers are binding to a specific port, there will be a port collision if the containers happen to be allocated on the same host. HTTP and PORT readiness checks will not be valid in this situation. In particular, both containers (the one that successfully binds to the port and the one that does not) may have their HTTP or PORT readiness check succeed since the checks are being performed against the same IP (the host’s IP). A valid configuration for such a service could use the anti-affinity placement policy, ensuring that containers will be assigned on different hosts so that port collisions will not occur.</p></section></section></section><section>
<h2><aname="Constant_variables_for_custom_service"></a>Constant variables for custom service</h2>
<p>The service framework provides some constant variables for user to configure their services. These variables are either dynamically generated by the system or are static ones such as service name defined by the user. User can use these constants in their configurations to be dynamically substituted by the service AM. E.g.</p>
<p>Here, <code>COMPONENT_INSTANCE_NAME</code> and <code>SERVICE_NAME</code> are the constants to be substituted by the system.</p>
<p>Suppose the <code>COMPONENT_INSTANCE_NAME</code> is <code>regionserver-0</code> and <code>SERVICE_NAME</code> is defined by user as <code>hbase</code>, user name is <code>devuser</code> and domain name is <code>dev.test</code>. Then, the config will be substituted by the service AM and written in the config file <code>/etc/hadoop/hbase-site.xml</code> inside the container as below:</p>
<td> name of the service defined by the user</td></tr>
<trclass="a">
<td> USER </td>
<td> user who submits the service. Note that user name which has “_” will be converted to use “-”, to conform with DNS hostname RFC format which doesn’t allow “_”, and all characters will be lowercased E.g. “Bob_dev” will be converted to “bob-dev”</td></tr>
<trclass="b">
<td> DOMAIN </td>
<td> the domain name for the cluster </td></tr>
<trclass="a">
<td> COMPONENT_NAME </td>
<td> the name for a given component </td></tr>
<trclass="b">
<td> COMPONENT_INSTANCE_NAME </td>
<td> the name for a given component instance (i.e. container) </td></tr>
<trclass="a">
<td> COMPONENT_ID </td>
<td> the monotonically increasing integer for a given component</td></tr>
<trclass="b">
<td> CONTAINER_ID </td>
<td> the YARN container Id for a given container </td></tr>
<trclass="a">
<td> ${COMPONENT_INSTANCE_NAME}_HOST </td>
<td> the hostname for a component instance (i.e. container), e.g. REGIONSERVER-0_HOST will be substituted by the actual hostname of the component instance. Note all characters must be uppercase. </td></tr>
<trclass="b">
<td> ${COMPONENT_INSTANCE_NAME}_IP </td>
<td> the ip for a component instance (i.e. container), e.g. REGIONSERVER-0_IP will be substituted by the actual IP address of the component instance. Note all characters must be uppercase. </td></tr>
