|
|
@@ -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.
|
Nate Cole