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.
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" } }
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:
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 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.
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 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.