This page adds to the over all guide How-To Define Stacks and Services and focuses on various aspects of adding a config property.

A config property is generally added to a Service and is associated with a config type.

For example, 


 zookeeper.znode.parent is a config property associated with hbase-site in HBase.


While adding config properties there are a few scenarios to keep in mind. Go through them to see what is applicable for the specific set of config changes you are doing.

Where should the property be added?

Identify the service version that the property is valid for. Ensure that the version is already defined in common-services. If not, then add a new version to the common-service. Do not add config properties directly in the stack versions unless the config property is only valid for a specific stack (e.g. HDP-2.4)

E.g added to KAFKA/0.9.0 and not KAFKA/0.8.1. KAFKA in HDP-2.3 derives from KAFKA/0.9.0

If the property is no longer supported starting a Service version then ensure that the property is deleted starting that specific Service version. E.g.

Note: It is not standard to delete config properties from a released stack definition. If you absolutely must then ensure that there is corresponding Ambari upgrade code to remove the config property as well.

What should the property value be

Within the stack definition only a default value can be provided. There are several choices:

What should happen on Ambari upgrade

The typical behavior is that Ambari upgrade must not modify stack configurations. It is critical for deployed stack to not take an outage (e.g. restart services) after performing an Ambari upgrade. It is ensured by specifying <on-ambari-upgrade add="false"/> to the config property. Due to historical reasons this is not the default behavior. Earlier versions of Ambari added any missing properties on upgrade. So several existing python scripts assume the existence of the properties.

So unless absolutely required, do not specify a config property to be added by default during Ambari upgrade.

If its needed that a property must be added/updated during Ambari upgrade, there are two choices:

Note: As Ambari upgrade does not add new config properties by default ensure that you have appropriate defaults while reading the configs. E.g.

What should happen on Stack upgrade

In contrast, Stack upgrade is a good time to update configs as needed. During stack upgrade all services go through restarts so new config values can easily take effect. By default, stack upgrade will add all new config properties that are missing in the stored configs. In addition, conditional update or deletion of config properties can be achieved through custom declarartive upgrade packs. E.g. deletes a property, modifies the value. 

Display characteristics of the config property

See - Enhanced Configs

Misc best-practices

  • Prefer setting config property values using stack-advisor (its common across all deployment mechanism, UI, blueprint)
  • Avoid inclusion of new config properties or modification of config properties in the configure() implantation of the component. This is not visible to the user and thus results in configs on disk not being the same as the config accessible via API/UI
  • Do add description for all config properties
  • Add dependencies to other config properties as needed. Dependencies are required to ensure that stack advisor is called when dependencies change in value or are deleted (e.g. service delete)


  • No labels