You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ambari.apache.org by nc...@apache.org on 2013/04/12 20:45:29 UTC
svn commit: r1467408 - in /incubator/ambari/trunk: CHANGES.txt
ambari-server/docs/api/v1/configuration.md ambari-server/docs/api/v1/index.md
Author: ncole
Date: Fri Apr 12 18:45:29 2013
New Revision: 1467408
URL: http://svn.apache.org/r1467408
Log:
AMBARI-1889. Added documentation for configuration
Added:
incubator/ambari/trunk/ambari-server/docs/api/v1/configuration.md
Modified:
incubator/ambari/trunk/CHANGES.txt
incubator/ambari/trunk/ambari-server/docs/api/v1/index.md
Modified: incubator/ambari/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/CHANGES.txt?rev=1467408&r1=1467407&r2=1467408&view=diff
==============================================================================
--- incubator/ambari/trunk/CHANGES.txt (original)
+++ incubator/ambari/trunk/CHANGES.txt Fri Apr 12 18:45:29 2013
@@ -702,6 +702,8 @@ Trunk (unreleased changes):
BUG FIXES
+ AMBARI-1889. Added documentation for configuration (ncole)
+
AMBARI-1912: HBase master doesn't come up after disabling security. (jaimin)
AMBARI-1902: RegionServer does not start in secure cluster. (jaimin)
Added: incubator/ambari/trunk/ambari-server/docs/api/v1/configuration.md
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/docs/api/v1/configuration.md?rev=1467408&view=auto
==============================================================================
--- incubator/ambari/trunk/ambari-server/docs/api/v1/configuration.md (added)
+++ incubator/ambari/trunk/ambari-server/docs/api/v1/configuration.md Fri Apr 12 18:45:29 2013
@@ -0,0 +1,229 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You 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.
+-->
+
+# Configuration
+A configuration is a set of key/value pairs that is persisted on Ambari server. A cluster has many configuration sets, each of which can be applied to a particular piece of functionality. A configuration consists of a type, a tag, and properties that define them. For example:
+
+ {
+ "type": "core-site",
+ "tag": "version1",
+ "properties": {
+ "fs.default.name": "hdfs://h0:8020"
+ // ...
+ }
+ }
+
+The `type` represents the semantic meaning of the configuration, while the `tag` identifies the revision of that `type`. In Ambari, the combination of `type` and `tag` is unique. However, multiple configurations of the same `type` having different `tag`s can exist. You cannot have two `core-site/version1`, nor is it supported to change the properties of an already defined property set.
+
+## Property Sets
+To list all the configurations defined in a cluster:
+
+ GET /api/v1/clusters/c1/configurations
+ {
+ "items" : [
+ {
+ "tag" : "version1",
+ "type" : "global",
+ "Config" : {
+ "cluster_name" : "c1"
+ }
+ },
+ /* etc */
+ }
+To view the real set of key/value pairs, use the `type` and `tag` as request parameters:
+
+ GET /api/v1/clusters/c1/configurations?type=global&tag=version1
+ {
+ "items" : [
+ {
+ "tag" : "version1",
+ "type" : "global",
+ "Config" : {
+ "cluster_name" : "c1"
+ },
+ "properties" : {
+ "hdfs_enable_shortcircuit_skipchecksum" : "false",
+ "hive_lib" : "/usr/lib/hive/lib/",
+ /* etc */
+ }
+ }
+ }
+
+To create a new configuration, the below call can be made. Creating a configuration is different than applying a configuration.
+
+ POST /api/v1/clusters/c1/configurations
+ {
+ "tag" : "version2",
+ "type" : "global",
+ "Config" : {
+ "cluster_name" : "c2"
+ }
+ }
+
+
+## Overrides
+Configurations are used by individual components on a host. The design is to define and apply configuration at the cluster level, with optional overrides per host. The order of application is as follows:
+
+1. Set a configuration to the cluster.
+3. Set optional configuration overrides to a host.
+
+The optional host overrides contain only the properties which need to be changed on a host
+from the cluster level configuration. Be aware you cannot create ONLY an override and expect
+it to be applied. There must always be a cluster-level configuration of the same type.
+
+## Desired Configuration
+Desired configurations is the set of `tag`s that defines what you desire the cluster to have. It
+is possible to save configurations, even if they are not applied. You can define `tag`s having
+the same type, but tag must be unique and only one of them is active for the cluster at any
+time.
+
+### Cluster
+There are two ways to apply a configuration to a cluster.
+
+One way is to create a configuration independently as described in *Property Sets* section above,
+and then apply it to the cluster:
+
+ PUT /api/v1/clusters/c1
+ {
+ "Clusters": {
+ "desired_config": {
+ "type": "core-site",
+ "tag": "version2",
+ }
+ }
+
+The other, more efficient way is to create and apply a configuration on a cluster, in one call:
+
+ PUT /api/v1/clusters/c1
+ {
+ "Clusters": {
+ "desired_config": {
+ "type": "core-site",
+ "tag": "version2",
+ "properties": {
+ "a": "b",
+ /* etc */
+ }
+ }
+ }
+
+The properties object is optional to avoid making two calls to create a configuration. If you provide them, the backend will first make the config instance, then apply it. Omit them, and it will apply the `type`/`tag` pair to the cluster as the default.
+
+The list of all desired configs is reported in a GET call:
+
+ GET /api/v1/clusters/c1
+ {
+ "Clusters" : {
+ "cluster_name" : "c1",
+ "cluster_id" : 2,
+ "desired_configs" : {
+ "global" : {
+ "tag" : "version1"
+ },
+ "hdfs-site" : {
+ "tag" : "version1"
+ },
+ "core-site": {
+ "tag": "version1",
+ "host_overrides": [
+ {
+ "host_name": "h0",
+ "tag": "version2"
+ },
+ {
+ "host_name": "h1",
+ "tag": "version3"
+ }
+ ]
+ },
+ /* etc */
+ }
+ }
+ }
+Notice that a configuration type that is overridden shows the host name and override tag.
+
+### Host
+Host overrides are set the same way as clusters:
+
+ PUT /api/v1/clusters/c1/hosts/h0
+ {
+ "Hosts": {
+ "desired_config": {
+ "type": "core-site",
+ "tag": "version2",
+ "properties": { "a": "b" }
+ }
+ }
+ }
+Again, if you supply properties, the configuration is created, then assigned. Otherwise, the configuration pair is simply assigned.
+
+To list the desired configs for a host:
+
+ GET /api/v1/clusters/c1/hosts/h0
+ {
+ "Hosts" : {
+ "cluster_name" : "c1",
+ "host_name" : "h0",
+ "desired_configs" : {
+ "global" : {
+ "tag" : "version3"
+ },
+ /* etc */
+ }
+ }
+ }
+
+##Actual Configuration
+Actual configuration represents the set of `tag`s that identify the cluster's current configuration. When configurations are changed, they are saved into the backing database, even if the host has not yet received the change. When a
+host receives the desired configuration changes AND applies them, it will respond with the applied tags. This is called the actual configuration.
+
+The most common use-case for actual configuration is knowing when a service or component restart is required. Consider the following query (response abbreviated for readability):
+
+ GET /api/v1/clusters/c1/services?fields=components/host_components/HostRoles/actual_configs/*
+ {
+ "items" : [
+ {
+ "ServiceInfo" : {
+ "cluster_name" : "c1",
+ "service_name" : "OOZIE"
+ },
+ "components" : [
+ {
+ "ServiceComponentInfo" : {
+ "cluster_name" : "c1",
+ "component_name" : "OOZIE_SERVER",
+ "service_name" : "OOZIE"
+ },
+ "host_components" : [
+ {
+ "HostRoles" : {
+ "cluster_name" : "c1",
+ "component_name" : "OOZIE_SERVER",
+ "host_name" : "h0",
+ "actual_configs" : {
+ "oozie-site" : {
+ "tag" : "version1"
+ }
+ }
+ }
+ }
+ ]
+ },
+ /* etc */
+ ]
+ }
+The actual configurations are used at the host_component level to indicate which services are different from the desired configurations. Any differences requires a restart of the component (or the entire service, if needed). This is because components of the the same service may be on different hosts.
Modified: incubator/ambari/trunk/ambari-server/docs/api/v1/index.md
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/docs/api/v1/index.md?rev=1467408&r1=1467407&r2=1467408&view=diff
==============================================================================
--- incubator/ambari/trunk/ambari-server/docs/api/v1/index.md (original)
+++ incubator/ambari/trunk/ambari-server/docs/api/v1/index.md Fri Apr 12 18:45:29 2013
@@ -78,6 +78,9 @@ There are 2 types of resources in the Am
- [List host components](host-components.md)
- [View host component information](host-component.md)
+### configurations
+- [Configuration](configuration.md)
+
Partial Response
----