diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-common/src/main/resources/yarn-default.xml b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-common/src/main/resources/yarn-default.xml index 13059f4..f2339fd 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-common/src/main/resources/yarn-default.xml +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-common/src/main/resources/yarn-default.xml @@ -1412,6 +1412,7 @@ + The root zookeeper node for the registry hadoop.registry.zk.root /registry @@ -1427,7 +1428,7 @@ - Zookeeper session timeout in milliseconds + Zookeeper connection timeout in milliseconds hadoop.registry.zk.connection.timeout.ms 15000 diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/index.md b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/index.md index a9ea24f..3a648b6 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/index.md +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/index.md @@ -24,5 +24,6 @@ and use the binding information to connect with the services's network-accessibl endpoints, be they REST, IPC, Web UI, Zookeeper quorum+path or some other protocol. * [Architecture](yarn-registry.html) +* [Configuration](registry-configuration.html) * [Using the YARN Service registry](using-the-yarn-service-registry.html) * [Security](registry-security.html) diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-configuration.md b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-configuration.md new file mode 100644 index 0000000..b9e6b6a --- /dev/null +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-configuration.md @@ -0,0 +1,377 @@ + + +# Registry Configuration + +## Core Settings + + +### Enabling the Registry in the Resource Manager + +The Resource Manager manages user directory creation and record cleanup +on YARN container/application attempt/application completion. + +``` + + + Is the registry enabled: does the RM start it up, + create the user and system paths, and purge + service records when containers, application attempts + and applications complete + + hadoop.registry.rm.enabled + false + +``` + +### Setting the Zookeeper Quorum: `hadoop.registry.zk.quorum` + +This is an essential setting: it identifies the lists of zookeeper hosts +and the ports on which the ZK services are listening. + + +``` + + + List of hostname:port pairs defining the + zookeeper quorum binding for the registry + + hadoop.registry.zk.quorum + localhost:2181 + +``` + +It takes a comma-separated list, such as `zk1:2181,zk2:2181,zk3:2181` + +### Setting the Zookeeper Registry Base path: `hadoop.registry.zk.root` + +This path sets the base zookeeper node for the registry + +``` + + + The root zookeeper node for the registry + + hadoop.registry.zk.root + /registry + +``` + +The default value is normally sufficient. + +## Security Options + +Registry security is enabled when the property `hadoop.registry.secure` +is set to `true`. Once set, nodes are created with permissions, so that +only a specific user *and the configured cluster "superuser" accounts* +can write under their home path of `${hadoop.registry.zk.root}/users`. Only the superuser accounts +will be able to manipulate the root path, including `${hadoop.registry.zk.root}/services` +and `${hadoop.registry.zk.root}/users`. + +All write operations on the registry (including deleting entries and paths) +must be authenticated. Read operations are still permitted by unauthenticated +callers. + +The key settings for secure registry support are: + +* enabling the secure mode: `hadoop.registry.secure` +* listing the superuser zookeeper ACLs: `hadoop.registry.system.acls` +* listing the kerberos realm for the principals: `hadoop.registry.kerberos.realm` +* identifying the JAAS context within the JAAS configuration which defines +the user: `hadoop.registry.jaas.context` + + +### Enabling security + +``` + + + Key to set if the registry is secure. Turning it on + changes the permissions policy from "open access" + to restrictions on kerberos with the option of + a user adding one or more auth key pairs down their + own tree. + + hadoop.registry.secure + false + +``` + +### Identifying the client JAAS context + +The registry clients must identify the JAAS context which they use +to authenticate to the registry. + +``` + + + Key to define the JAAS context. Used in secure mode + + hadoop.registry.jaas.context + Client + +``` + +*Note* as the Resource Manager is simply another client of the registry, it +too must have this context defined. + + +### Identifying the system accounts `hadoop.registry.system.acls` + +These are the the accounts which are given full access to the base of the +registry. The Resource Manager needs this option to create the root paths. + +Clients also need this option so that the registry client can give those +same accounts access to the nodes it creates. (This is a requirement of the +ZK security model) + +1. The property `hadoop.registry.system.acls` takes a comma separate list +of zookeeper `ACLs` which are given full access to created nodes; the permissions +`READ | WRITE | CREATE | DELETE | ADMIN`. +2. Any zookeeper ACL scheme may be added to this, such as the `digest:` scheme. +3. The SASL scheme, `sasl:`, is used to identify which callers identified +by sasl have full access. These are the superuser accounts. +4. They may be identified by elements such as `sasl:yarn@REALM.COM`. +5. To aid portability the setting, any sasl entry without the realm value —that +is, any entry that terminates in the "@" symbol— has the current realm appended +to it. +6. This realm is set to that of the current user. +7. It may be overridden by the property `hadoop.registry.kerberos.realm`. + + +``` + + + A comma separated list of Zookeeper ACL identifiers with + system access to the registry in a secure cluster. + + These are given full access to all entries. + + If there is an "@" at the end of a SASL entry it + instructs the registry client to append the default kerberos domain. + + hadoop.registry.system.acls + sasl:yarn@, sasl:mapred@, sasl:mapred@hdfs@ + + + + + The kerberos realm: used to set the realm of + system principals which do not declare their realm, + and any other accounts that need the value. + + If empty, the default realm of the running process + is used. + + If neither are known and the realm is needed, then the registry + service/client will fail. + + hadoop.registry.kerberos.realm + + +``` + +## Zookeeper connection management options + +Some low level options manage the ZK connection —more specifically, its failure +handling. + +The Zookeeper registry clients use Apache Curator to connect to Zookeeper, +a library which detects timeouts and attempts to reconnect to one of the +servers which forms the zookeeper quorum. It is only after a timeout is detected +that a retry is triggered. + +``` + + + Zookeeper session timeout in milliseconds + + hadoop.registry.zk.session.timeout.ms + 60000 + + + + + Zookeeper connection timeout in milliseconds + + hadoop.registry.zk.connection.timeout.ms + 15000 + + + + + Zookeeper connection retry count before failing + + hadoop.registry.zk.retry.times + 5 + + + + + + hadoop.registry.zk.retry.interval.ms + 1000 + + + + + Zookeeper retry limit in milliseconds, during + exponential backoff: {@value} + + This places a limit even + if the retry times and interval limit, combined + with the backoff policy, result in a long retry + period + + hadoop.registry.zk.retry.ceiling.ms + 60000 + +``` + +The retry strategy used in the registry client is +[`BoundedExponentialBackoffRetry`](https://curator.apache.org/apidocs/org/apache/curator/retry/BoundedExponentialBackoffRetry.html): +This backs off exponentially on connection failures before eventually +concluding that the quorum is unreachable and failing. + +## Complete Set of Configuration Options + +``` + + + + + Is the registry enabled: does the RM start it up, + create the user and system paths, and purge + service records when containers, application attempts + and applications complete + + hadoop.registry.rm.enabled + false + + + + + List of hostname:port pairs defining the + zookeeper quorum binding for the registry + + hadoop.registry.zk.quorum + localhost:2181 + + + + + The root zookeeper node for the registry + + hadoop.registry.zk.root + /registry + + + + + + Key to set if the registry is secure. Turning it on + changes the permissions policy from "open access" + to restrictions on kerberos with the option of + a user adding one or more auth key pairs down their + own tree. + + hadoop.registry.secure + false + + + + + A comma separated list of Zookeeper ACL identifiers with + system access to the registry in a secure cluster. + + These are given full access to all entries. + + If there is an "@" at the end of a SASL entry it + instructs the registry client to append the default kerberos domain. + + hadoop.registry.system.acls + sasl:yarn@, sasl:mapred@, sasl:mapred@hdfs@ + + + + + The kerberos realm: used to set the realm of + system principals which do not declare their realm, + and any other accounts that need the value. + + If empty, the default realm of the running process + is used. + + If neither are known and the realm is needed, then the registry + service/client will fail. + + hadoop.registry.kerberos.realm + + + + + + Key to define the JAAS context. Used in secure + mode + + hadoop.registry.jaas.context + Client + + + + + + Zookeeper session timeout in milliseconds + + hadoop.registry.zk.session.timeout.ms + 60000 + + + + + Zookeeper session timeout in milliseconds + + hadoop.registry.zk.connection.timeout.ms + 15000 + + + + + Zookeeper connection retry count before failing + + hadoop.registry.zk.retry.times + 5 + + + + + + hadoop.registry.zk.retry.interval.ms + 1000 + + + + + Zookeeper retry limit in milliseconds, during + exponential backoff: {@value} + + This places a limit even + if the retry times and interval limit, combined + with the backoff policy, result in a long retry + period + + hadoop.registry.zk.retry.ceiling.ms + 60000 + +``` diff --git a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-security.md b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-security.md index 7278534..6317681 100644 --- a/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-security.md +++ b/hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/markdown/registry/registry-security.md @@ -24,8 +24,8 @@ This document is therefore relevant only to secure clusters. ## Security Model The security model of the registry is designed to meet the following goals -a secur -1. Deliver functional security on e ZK installation. +a secure registry: +1. Deliver functional security on a secure ZK installation. 1. Allow the RM to create per-user regions of the registration space 1. Allow applications belonging to a user to write registry entries into their part of the space. These may be short-lived or long-lived