Revision 19145305
Added by Jonathan CLARKE over 7 years ago
| 4_advanced_usage/40_node_properties.txt | ||
|---|---|---|
|
|
||
|
Node properties can be found in the "properties" tab of each node in Rudder.
|
||
|
|
||
|
Node properties can be modified using Rudder API, see http://www.rudder-project.org/rudder-api-doc/#api-Nodes-updateNodeProperties
|
||
|
Node properties can be modified using Rudder's API, see http://www.rudder-project.org/rudder-api-doc/#api-Nodes-updateNodeProperties
|
||
|
|
||
|
Properties can be seen as a list of key=value pairs.
|
||
|
Each property is a key=value pair. The value can be a string or a well-formatted JSON data structure.
|
||
|
|
||
|
The value can be a string or a well formatter JSON data structure.
|
||
|
|
||
|
Example: `datacenter=Paris`. `datacenter= { "Europe": { "France": "Paris" } }`
|
||
|
Some examples:
|
||
|
`datacenter=Paris`
|
||
|
`datacenter= { "id": "FRA1", "name": "Colo 1, Paris", "location": "Paris, France", "dns_suffix": "paris.example.com" }`
|
||
|
|
||
|
|
||
|
==== Using properties
|
||
|
|
||
|
You can use a node property almost everywhere in Rudder:
|
||
|
You can use node properties almost everywhere in Rudder:
|
||
|
|
||
|
* in directive parameters
|
||
|
* in the technique editor
|
||
|
* in your own techniques an generic methods code
|
||
|
* in your own techniques and generic methods
|
||
|
|
||
|
To use a property, simply use the variable node.properties with the variable call syntax.
|
||
|
|
||
|
Example with a string property named datacenter:
|
||
|
Example with a property named 'datacenter':
|
||
|
|
||
|
----
|
||
|
|
||
| ... | ... | |
|
|
||
|
----
|
||
|
|
||
|
WARNING: Currently node properties can not be used in JavaScript expressions (see following paragraph), since they are evaluated during policy generation and node properties are only made available in the agents. Starting with Rudder 3.1.14 and 3.2.7, you can enable a feature swith in "Administration / Setting" to allow node properties expansion in directive parameters. More details can be found at <<_node_properties_expansion_in_directives>>.
|
||
|
WARNING: Before Rudder 3.1.14 and 3.2.7, node properties could not be used in JavaScript expressions (see following section), since they are evaluated during policy generation and node properties were only made available to agents at runtime. Since Rudder 3.1.14, 3.2.7 and 4.0.0 and later, you can enable a feature switch in "Administration/Settings" to enable node properties expansion in directive parameters. More details are available at <<_node_properties_expansion_in_directives>>.
|
||
|
|
||
|
==== Under the hood
|
||
|
|
||
|
On the server, one or more properties files are written for each node in the
|
||
|
`/var/rudder/share/<uuid>/rules/cfengine-community/properties.d/` directory.
|
||
|
This directory is then synchronized by the agent with all other promise files.
|
||
|
This directory is then copied to each node by the agent with all other promise files.
|
||
|
|
||
|
In the agent, properties are made available in the `node.<namespace>` container that contains the values.
|
||
|
Those values are read from
|
||
| 4_advanced_usage/55_node_properties_in_directives.txt | ||
|---|---|---|
|
|
||
|
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 expression.
|
||
|
provide unique values for each node or be used in JavaScript expressions.
|
||
|
|
||
|
Properties on nodes are defined using Rudder REST API, using 'Update Node properties' api call.
|
||
|
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.
|
||
|
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* parameter.
|
||
|
*Enable node properties expansion in Directives* switch.
|
||
|
|
||
|
Rudder installations from 4.0 onwards have this feature enabled by default.
|
||
|
Rudder installations from 4.0.0 onwards have this feature enabled by default.
|
||
|
|
||
|
==== Usage
|
||
|
|
||
|
In any directive text field, you can access property defined on nodes, with the following format:
|
||
|
In any directive text field, you can access properties defined on nodes using the following syntax:
|
||
|
|
||
|
----
|
||
|
|
||
|
${node.properties[keyone][keytwo]}
|
||
|
${node.properties[key_one][key_two]}
|
||
|
|
||
|
----
|
||
|
|
||
|
|
||
|
where:
|
||
|
|
||
|
- keyone, keytwo are path on json values
|
||
|
- the return value is the string representation, in compact mode, of the resulting access
|
||
|
- if the key is not found, we raise an error and stop the policy generation
|
||
|
- `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 a missing node properties.
|
||
|
It's also a perfect to provide a simple specialisation of values for some nodes which have the property.
|
||
|
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 has default.
|
||
|
You can also use other node properties, or other Rudder parameters as defaults, using the same syntax as above.
|
||
|
|
||
|
Some examples:
|
||
|
|
||
|
----
|
||
|
|
||
|
${node.properties[datacenter][Europe] | "a simple value" }
|
||
|
${node.properties[datacenter][Europe] | """ a "value" with quotes""" }
|
||
|
${node.properties[datacenter][Europe] | ${rudder.param.some_value} }
|
||
|
${node.properties[datacenter][Europe] | ${rudder.node.hostname}
|
||
|
${node.properties[datacenter][Europe] | ${node.properties[other_on_node] | node }
|
||
|
${node.properties[datacenter][Europe] |${node.properties[other] | "some value ${rudder.node.id}" }
|
||
|
${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" }
|
||
|
|
||
|
----
|
||
|
|
||
|
|
||
|
===== Requesting expansion on the node
|
||
|
===== 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, and let the value expanded during the agent run on the node. Typically if the value is to be used by a templating
|
||
|
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 option "node" to the properties expression:
|
||
|
For these cases, you can add the "node" option to the property expression:
|
||
|
|
||
|
----
|
||
|
|
||
|
${node.properties[datacenter][Europe] | node }
|
||
|
${node.properties[datacenter][id] | node }
|
||
|
|
||
|
----
|
||
|
|
||
|
This will be rewritten during policy generation into:
|
||
|
This will be rewritten during policy generation into::
|
||
|
|
||
|
----
|
||
|
|
||
|
${node.properties[datacenter][Europe]}
|
||
|
${node.properties[datacenter][id]}
|
||
|
|
||
|
----
|
||
|
|
||
|
Which will be treated as a variable by the agent (replace by its value if defined, kept as is if unknown).
|
||
|
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 can be found in <<_node_properties>>.
|
||
|
You can find more information on node properties in <<_node_properties>>.
|
||
|
|
||
Also available in: Unified diff
Fixes #9253: Cleanup node properties documentation