Revision 8f775bdf
Added by Jonathan CLARKE over 7 years ago
4_advanced_usage/45_node_properties_in_directives.txt | ||
---|---|---|
=== Node properties expansion in directives
|
||
|
||
It is possible to use properties defined on nodes to build Directive values. The
|
||
resulting values will be computed during policy generation, and can therefore
|
||
provide unique values for each node or be used in JavaScript expressions.
|
||
|
||
Properties on nodes are defined using Rudder's REST API, with the 'Update Node properties' API call.
|
||
More details in our http://www.rudder-project.org/rudder-api-doc[API documentation].
|
||
|
||
==== Feature availability
|
||
|
||
This feature was introduced in Rudder 3.1.14, Rudder 3.2.7 and Rudder 4.0.0.
|
||
|
||
If you upgraded to 3.1.14 (or a later 3.1.x version) or 3.2.7 (or a later 3.2.x
|
||
version) from a previous Rudder version, this feature is disabled by default
|
||
in order to mitigate any risk of undesired side effects on existing
|
||
installations. You can enable it in the Administration/Settings page, using the
|
||
*Enable node properties expansion in Directives* switch.
|
||
|
||
Rudder installations from 4.0.0 onwards have this feature enabled by default.
|
||
|
||
==== Usage
|
||
|
||
In any directive text field, you can access properties defined on nodes using the following syntax:
|
||
|
||
----
|
||
|
||
${node.properties[key_one][key_two]}
|
||
|
||
----
|
||
|
||
|
||
where:
|
||
|
||
- `property_name` is the name of the property defined via the API
|
||
- `key_one` and `key_two` are keys in the JSON structure
|
||
- the value obtained is the string representation, in compact mode, of the entire node property or sub-structure of the JSON value
|
||
- if the key is not found, an error will be raised that will stop policy generation
|
||
- spaces are authorized around separators ([,],|,}..)
|
||
|
||
===== Providing a default value
|
||
|
||
Most of the time, you will need to provide a default value to node properties expansion to avoid a policy generation
|
||
error due to missing node properties.
|
||
This is also a good case to allow a simple override mechanism for a parameter where only some nodes have a specific value.
|
||
|
||
You can also use other node properties, or other Rudder parameters as defaults, using the same syntax as above.
|
||
|
||
Some examples:
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id] | "LON2" }
|
||
${node.properties[datacenter][name] | """Co-location with "Hosting Company" in Paris (allows quotes)""" }
|
||
${node.properties[datacenter][id] | ${rudder.param.default_datacenter} }
|
||
${node.properties[netbios_name] | ${rudder.node.hostname} }
|
||
${node.properties[dns_suffix] | ${node.properties[datacenter][dns_suffix] | "${rudder.node.hostname}.example.com" }
|
||
|
||
----
|
||
|
||
===== Forcing expansion on the node
|
||
|
||
In some cases, you will want to use a `${node.properties[key]}` in a directive parameter, but you don't want to expand it during
|
||
policy generation on the Rudder server, but instead let the value be expanded during the agent run on the node. Typically if the value is to be used by a templating
|
||
tool, or if the value is known only on the node.
|
||
|
||
For these cases, you can add the "node" option to the property expression:
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id] | node }
|
||
|
||
----
|
||
|
||
This will be rewritten during policy generation into::
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id]}
|
||
|
||
----
|
||
|
||
Which will be considered as a standard variable by the agent, which will replaced this expression by its value if it's defined, or kept as is if it's unknown.
|
||
|
||
The variable is content is read from /var/rudder/cfengine-community/inputs/properties.d/properties.json.
|
||
You can find more information on node properties in <<_node_properties>>.
|
||
|
4_advanced_usage/55_node_properties_in_directives.txt | ||
---|---|---|
=== Node properties expansion in directives
|
||
|
||
It is possible to use properties defined on nodes to build Directive values. The
|
||
resulting values will be computed during policy generation, and can therefore
|
||
provide unique values for each node or be used in JavaScript expressions.
|
||
|
||
Properties on nodes are defined using Rudder's REST API, with the 'Update Node properties' API call.
|
||
More details in our http://www.rudder-project.org/rudder-api-doc[API documentation].
|
||
|
||
==== Feature availability
|
||
|
||
This feature was introduced in Rudder 3.1.14, Rudder 3.2.7 and Rudder 4.0.0.
|
||
|
||
If you upgraded to 3.1.14 (or a later 3.1.x version) or 3.2.7 (or a later 3.2.x
|
||
version) from a previous Rudder version, this feature is disabled by default
|
||
in order to mitigate any risk of undesired side effects on existing
|
||
installations. You can enable it in the Administration/Settings page, using the
|
||
*Enable node properties expansion in Directives* switch.
|
||
|
||
Rudder installations from 4.0.0 onwards have this feature enabled by default.
|
||
|
||
==== Usage
|
||
|
||
In any directive text field, you can access properties defined on nodes using the following syntax:
|
||
|
||
----
|
||
|
||
${node.properties[key_one][key_two]}
|
||
|
||
----
|
||
|
||
|
||
where:
|
||
|
||
- `property_name` is the name of the property defined via the API
|
||
- `key_one` and `key_two` are keys in the JSON structure
|
||
- the value obtained is the string representation, in compact mode, of the entire node property or sub-structure of the JSON value
|
||
- if the key is not found, an error will be raised that will stop policy generation
|
||
- spaces are authorized around separators ([,],|,}..)
|
||
|
||
===== Providing a default value
|
||
|
||
Most of the time, you will need to provide a default value to node properties expansion to avoid a policy generation
|
||
error due to missing node properties.
|
||
This is also a good case to allow a simple override mechanism for a parameter where only some nodes have a specific value.
|
||
|
||
You can also use other node properties, or other Rudder parameters as defaults, using the same syntax as above.
|
||
|
||
Some examples:
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id] | "LON2" }
|
||
${node.properties[datacenter][name] | """Co-location with "Hosting Company" in Paris (allows quotes)""" }
|
||
${node.properties[datacenter][id] | ${rudder.param.default_datacenter} }
|
||
${node.properties[netbios_name] | ${rudder.node.hostname} }
|
||
${node.properties[dns_suffix] | ${node.properties[datacenter][dns_suffix] | "${rudder.node.hostname}.example.com" }
|
||
|
||
----
|
||
|
||
===== Forcing expansion on the node
|
||
|
||
In some cases, you will want to use a `${node.properties[key]}` in a directive parameter, but you don't want to expand it during
|
||
policy generation on the Rudder server, but instead let the value be expanded during the agent run on the node. Typically if the value is to be used by a templating
|
||
tool, or if the value is known only on the node.
|
||
|
||
For these cases, you can add the "node" option to the property expression:
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id] | node }
|
||
|
||
----
|
||
|
||
This will be rewritten during policy generation into::
|
||
|
||
----
|
||
|
||
${node.properties[datacenter][id]}
|
||
|
||
----
|
||
|
||
Which will be considered as a standard variable by the agent, which will replaced this expression by its value if it's defined, or kept as is if it's unknown.
|
||
|
||
The variable is content is read from /var/rudder/cfengine-community/inputs/properties.d/properties.json.
|
||
You can find more information on node properties in <<_node_properties>>.
|
||
|
Also available in: Unified diff
Fixes #9253: Cleanup node properties documentation