Most software allows for configuration by end users/operators. The method of configuration differs between software, such as environment variables, configuration files, command-line arguments, or runtime commands. A BOSH job template is a wrapper around the running of software and its method of configuration. All BOSH job templates are then configured in a homogeneous way: the deployment manifest provided to
You were first introduced to configuring a job template in Update Job Template Properties. We were able to provide a
max_client_connections property to the
zookeeper job template from the
zookeeper BOSH release:
instance_groups: - name: zookeeper instances: 5 jobs: - name: zookeeper release: zookeeper properties: max_client_connections: 120
This raises three excellent questions:
- What other properties are available to the
zookeeperjob template from the
- What is the default value of
max_client_connectionsif we had not explicitly provided it?
- What does each property do?
The definition of available properties for a job template is in its source repository. Each job template has a
spec file that documents the
properties that its templates can use.
For https://github.com/cppforlife/zookeeper-release we look in
git clone https://github.com/cppforlife/zookeeper-release cd zookeeper-release cat jobs/zookeeper/spec
A sample of
properties: listen_address: description: "The address to listen for client connections" default: "0.0.0.0" client_port: description: "The port to listen for client connections" default: 2181 quorum_port: description: "Apache Zookeeper Client quorum port" default: 2888 leader_election_port: description: "Apache Zookeeper Client leader election port" default: 3888 ... max_client_connections: description: "Limits the number of concurrent connections that a single client may make to a single member of the ZooKeeper ensemble" default: 60 ...
Each property should include a helpful description about the purpose of the property, and if the property is required or optional. It might also include a default value.
Default Property Values¶
The deployment manifest property
max_client_connections is one of
properties described in the BOSH release source repository above. It has a default value. This means that a deployment manifest does not need to explicitly provide the
Default values allow deployment manifests to be smaller, simpler, and easier to read. The original
spec file above has over twenty properties each with useful default values. A deployment manifest would be twenty lines longer if it were to explicitly provide each property in the deployment manifest:
instance_groups: - name: zookeeper instances: 5 jobs: - name: zookeeper release: zookeeper properties: listen_address: 0.0.0.0 client_port: 2181 quorum_port: 2888 leader_election_port: 3888 max_client_connections: 60 ...
Be Wary of Changing Default Values¶
A potential downside of default property values is that they may change between BOSH release versions. If the previous release version had default
max_client_connections: 120, but was changed to
max_client_connections: 5 in the latest version, then our system's behaviour and performance might be negatively affected if we do not realise and explicit override the property to a higher value.
Changes to default property values are not displayed when running
Ideally, the BOSH release developers will discuss any changes to property default values in their release notes. And that you will read those release notes.
You can also use
git diff to inspect any changes to
spec files between versions. Try either of the following to view changes to one or all
spec files, respectively:
git diff v0.0.3..v0.0.6 -- jobs/zookeeper/spec git diff v0.0.3..v0.0.6 -- jobs/*/spec
We can see that two properties from
zookeeper have been removed, one new property added, and fortunately no properties have had their default values changed:
- user: - description: "User which will own the Apache ZooKeeper services" - default: "zookeeper" - group: - description: "Group which will own the Apache ZooKeeper services" - default: "vcap" ... + force_sync: + description: "Requires updates to be synced to media of the transaction log before finishing processing the update. Setting to 'no' improves performance dramatically at the cost of losing recent commits if all nodes crash at the same time" + default: "yes"
What Does Each Property Do?¶
Obviously, a property declared in a
spec file is only useful if it is used in a template to ultimately setup/change/control the behaviour of processes that are run on BOSH instances.
To use a property within a template we use the Ruby programming language ERb template system, and the
<%= p('some-property') %>
bosh deploy this entire snippet will be replaced by the
properties.some-property value from the deployment manifest, or the property's default value in the
If a configuration item is optional then a template can use the
<% if_p('some-property') do |value| %> optional-config-item: <%= value %> <% end %>
We will revisit the Ruby ERb template syntax later when we look at creating our own BOSH releases.
Discovery of Properties in Templates¶
deployment manifest -> job template <- upstream configuration files/documentation
It is ultimately a great idea to read through the entire job template and all its template files to fully understand how each property is used.
zookeeper job template, the template file
spec properties are being used:
... autopurge.purgeInterval=<%= p('autopurge_purge_interval') %> autopurge.snapRetainCount=<%= p('autopurge_snap_retain_count') %> clientPortAddress=<%= p('listen_address') %> ... maxClientCnxns=<%= p('max_client_connections') %> ...