README-extentions.rst

Escaping of References and Inventory Queries
============================================

Reference and inventory queries can be escaped to produce literal strings, for example:

parameters:   
  colour: Blue
  unescaped: The colour is ${colour}
  escaped: The colour is \${colour}  
  double_escaped: The colour is \\${colour}


This would produce:           

parameters:   
  colour: Blue
  unescaped: The colour is Blue   
  escaped: The colour is ${colour}   
  double_escaped: The colour is \Blue



Merging Referenced Lists and Dictionaries
=========================================

Referenced lists or dicts can now be merged:

# nodes/test.yml
classes: 
  - test1
  - test2  
parameters:
  one:  
    a: 1
    b: 2
  two:  
    c: 3
    d: 4
  three:
    e: 5

# classes/test1.yml
parameters:    
  three: ${one}

# classes/test2.yml
parameters:    
  three: ${two}

running reclass.py --nodeinfo node1 then gives:

parameters:
  one:
    a: 1
    b: 2
  three:
    a: 1
    b: 2
    c: 3
    d: 4
    e: 5
  two:
    c: 3
    d: 4

This first sets the parameter three to the value of parameter one (class test1) then merges parameter two into
parameter three (class test2) and finally merges the parameter three definition given in the node definition into



Nested References
=================

References can now be nested, for example:

# nodes/node1.yml
parameters:
  alpha:
    one: ${beta:${alpha:two}}
    two: a
  beta:
    a: 99

reclass.py --nodeinfo node1 then gives:

parameters:
  alpha:
    one: 99
    two: a
  beta:
    a: 99

The ${beta:${alpha:two}} construct first resolves the ${alpha:two} reference to the value 'a', then resolves
the reference ${beta:a} to the value 99.



Inventory Queries
=================

Inventory querying works using a new key type - exports to hold values which other node definitions can read using a $[] query, for example with:

# nodes/node1.yml
exports:
  test_zero: 0
  test_one:
    name: ${name}
    value: 6
  test_two: ${dict}

parameters:
  name: node1
  dict:
    a: 1
    b: 2
  exp_value_test: $[ exports:test_two ]
  exp_if_test0: $[ if exports:test_zero == 0 ]
  exp_if_test1: $[ exports:test_one if exports:test_one:value == 7 ]
  exp_if_test2: $[ exports:test_one if exports:test_one:name == self:name ]

# nodes/node2.yml
exports:
  test_zero: 0
  test_one:
    name: ${name}
    value: 7
  test_two: ${dict}

parameters:
  name: node2
  dict:
    a: 11
    b: 22


running reclass.py --nodeinfo node1 gives (listing only the exports and parameters):

exports:
  test_one:
    name: node1
    value: 6
  test_two:
    a: 1
    b: 2
parameters:
  dict:
    a: 1
    b: 2
  exp_if_test0:
    - node1
    - node2
  exp_if_test1:
    node2:
      name: node2
      value: 7
  exp_if_test2:
    node1:
      name: node1
      value: 6
  exp_value_test:
    node1:
      a: 1
      b: 2
    node2:
      a: 11
      b: 22
  name: node1


Exports defined for a node can be a simple value or a reference to a parameter in the node definition.
The $[] inventory queries are calculated for simple value expressions, $[ exports:key ], by returning
a dictionary with an element ({ node_name: key value }) for each node which defines 'key' in the exports
section. For tests with a preceeding value, $[ exports:key if exports:test_key == test_value ], the
element ({ node_name: key value }) is only added to the returned dictionary if the test_key defined in
the node exports section equals the test value. For tests without a preceeding value,
$[ if exports:test_key == test_value ], a list of nodes which pass the test is returned. For either test
form the test value can either be a simple value or a node parameter. And as well as an equality test
a not equals test (!=) can also be used.

**Options**

By default inventory queries only look at nodes in the same environment as the querying node. This can be
overriden using the +AllEnvs option:

  $[ +AllEnvs exports:test ]

Any errors in rendering the export parameters for a node will give an error for the inventory query as a whole.
This can be overriden using the +IgnoreErrors option:

  $[ +IgnoreErrors exports:test ]

With the +IgnoreErrors option nodes which generate an error evaluating exports:test will be ignored.

Inventory query options can be combined:

  $[ +AllEnvs +IgnoreErrors exports:test ]

**Logical operators and/or**

The logical operators and/or can be used in inventory queries:

  $[ exports:test_value if exports:test_zero == 0 and exports:test_one == self:value ]

The individual elements of the if statement are evaluated and combined with the logical operators starting from the
left and working to the right.


**Examples**

Defining a cluster of machines using an inventory query, for example to open access to a database server to a
group of nodes. Given exports/parameters for nodes of the form:

# for all nodes requiring access to the database server
exports:
  host:
    ip_address: aaa.bbb.ccc.ddd
  cluster: _some_cluster_name_

# for the database server
parameters:
  cluster_name: production-cluster
  postgresql:
    server:
      clients: $[ exports:host:ip_address if exports:cluster == self:cluster_name ]

This will generate a dictionary with an entry for node where the export:cluster key for a node is equal to the
parameter:cluster_name key of the node on which the inventory query is run on. Each entry in the generated dictionary
will contain the value of the exports:host:ip_address key. The output dictionary (depending on node definitions)
would look like:

node1:
  ip_address: aaa.bbb.ccc.ddd
node2:
  ip_address: www.xxx.yyy.zzz

For nodes where exports:cluster key is not defined or where the key is not equal to self:cluster_name no entry is made
in the output dictionary.

In practise the exports:cluster key can be set using a parameter reference:

exports:
  cluster: ${cluster_name}

parameters:
  cluster_name: production-cluster

The above exports and parameter definitions could be put into a separate class and then included by nodes which require
access to the database and included by the database server as well.