documentation updates from salt-formulas/reclass
diff --git a/README-extentions.rst b/README-extentions.rst
index 8c7c35c..31458b6 100644
--- a/README-extentions.rst
+++ b/README-extentions.rst
@@ -1,170 +1,203 @@
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}
+.. code-block:: yaml
+
+ parameters:
+ colour: Blue
+ unescaped: The colour is ${colour}
+ escaped: The colour is \${colour}
+ double_escaped: The colour is \\${colour}
-This would produce:
+This would produce:
-parameters:
- colour: Blue
- unescaped: The colour is Blue
- escaped: The colour is ${colour}
- double_escaped: The colour is \Blue
+.. code-block:: yaml
+
+ parameters:
+ colour: Blue
+ unescaped: The colour is Blue
+ escaped: The colour is ${colour}
+ double_escaped: The colour is \Blue
+
+
+
+Ignore class not found
+----------------------
+
+At some cases (bootstrapping, development) it can be convenient to ignore some missing classes.
+To control the feature there are two options available:
+
+.. code-block:: yaml
+
+ ignore_class_notfound: False
+ ignore_class_regexp: ['*']
+
+If you set regexp pattern to ``service.*`` all missing classes starting 'service.' will be logged with warning, but will not
+fail to return rendered reclass. Assuming all parameter interpolation passes.
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
+.. code-block:: yaml
-# classes/test1.yml
-parameters:
- three: ${one}
+ # nodes/test.yml
+ classes:
+ - test1
+ - test2
+ parameters:
+ one:
+ a: 1
+ b: 2
+ two:
+ c: 3
+ d: 4
+ three:
+ e: 5
-# classes/test2.yml
-parameters:
- three: ${two}
+ # classes/test1.yml
+ parameters:
+ three: ${one}
-running reclass.py --nodeinfo node1 then gives:
+ # classes/test2.yml
+ parameters:
+ three: ${two}
-parameters:
- one:
- a: 1
- b: 2
- three:
- a: 1
- b: 2
- c: 3
- d: 4
- e: 5
- two:
- c: 3
- d: 4
+``running reclass.py --nodeinfo node1`` then gives:
+
+.. code-block:: yaml
+
+ 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
+the final value.
Nested References
-=================
+-----------------
References can now be nested, for example:
-# nodes/node1.yml
-parameters:
- alpha:
- one: ${beta:${alpha:two}}
- two: a
- beta:
- a: 99
+.. code-block:: yaml
-reclass.py --nodeinfo node1 then gives:
+ # nodes/node1.yml
+ parameters:
+ alpha:
+ one: ${beta:${alpha:two}}
+ two: a
+ beta:
+ a: 99
-parameters:
- alpha:
- one: 99
- two: a
- beta:
- a: 99
+``reclass.py --nodeinfo node1`` then gives:
-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.
+.. code-block:: yaml
+
+ 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}
+.. code-block:: yaml
-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
+ # nodes/node1.yml
+ exports:
+ test_zero: 0
+ test_one:
+ name: ${name}
value: 6
- exp_value_test:
- node1:
+ test_two: ${dict}
+
+ parameters:
+ name: node1
+ dict:
a: 1
b: 2
- node2:
+ 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
- name: node1
+
+
+``running reclass.py --nodeinfo node1`` gives (listing only the exports and parameters):
+
+.. code-block:: yaml
+
+ 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.
@@ -177,7 +210,8 @@
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**
+
+**Inventory query 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:
@@ -205,17 +239,21 @@
left and working to the right.
-**Examples**
+**Inventory query example**
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:
+.. code-block:: yaml
+
# for all nodes requiring access to the database server
exports:
host:
ip_address: aaa.bbb.ccc.ddd
cluster: _some_cluster_name_
+.. code-block:: yaml
+
# for the database server
parameters:
cluster_name: production-cluster
@@ -228,6 +266,8 @@
will contain the value of the exports:host:ip_address key. The output dictionary (depending on node definitions)
would look like:
+.. code-block:: yaml
+
node1:
ip_address: aaa.bbb.ccc.ddd
node2:
@@ -238,9 +278,10 @@
In practise the exports:cluster key can be set using a parameter reference:
+.. code-block:: yaml
+
exports:
cluster: ${cluster_name}
-
parameters:
cluster_name: production-cluster
diff --git a/README.rst b/README.rst
index fc5757c..f606cdb 100644
--- a/README.rst
+++ b/README.rst
@@ -1,27 +1,22 @@
-reclass (extended) README
+Reclass README
=========================
-This is an extended version of **reclass** available at:
-https://github.com/AndrewPickford/reclass
-
-The original **reclass** is available at:
+This is the fork of original **reclass** that is available at:
https://github.com/madduck/reclass
-
Extentions
==========
-Escaping of References and Inventory Queries
-Merging Referenced Lists and Dictionaries
-Nested References
-Inventory Queries
+List of the core features:
+
+* Escaping of References and Inventory Queries
+* Merging Referenced Lists and Dictionaries
+* Nested References
+* Inventory Queries
+* Ignore class notfound/regexp option
-Changes
-=======
-
-The escaping of references changes how the constructs '\${xxx}' and '\\${xxx}'
-are rendered.
+.. include:: ../../README.extensions.rst
Documentation
diff --git a/releasenotes/config.yaml b/releasenotes/config.yaml
new file mode 100644
index 0000000..6a6923d
--- /dev/null
+++ b/releasenotes/config.yaml
@@ -0,0 +1,66 @@
+---
+# Usage:
+#
+# reno -qd .releasenotes list
+# reno -qd .releasenotes new slug-title --edit
+# reno -qd .releasenotes report --no-show-source
+
+# Change prelude_section_name to 'summary' from default value prelude
+prelude_section_name: summary
+show_source: False
+sections:
+ - [summary, Summary]
+ - [features, New features]
+ - [fixes, Bug fixes]
+ - [others, Other notes]
+template: |
+ ---
+ # Author the following sections or remove the section if it is not related.
+ # Use one release note per a feature.
+ #
+ # If you miss a section from the list below, please first submit a review
+ # adding it to .releasenotes/config.yaml.
+ #
+ # Format content with reStructuredText (RST).
+ # **Formatting examples:**
+ # - |
+ # This is a brief description of the feature. It may include a
+ # number of components:
+ #
+ # * List item 1
+ # * List item 2.
+ # This code block below will appear as part of the list item 2:
+ #
+ # .. code-block:: yaml
+ #
+ # classes:
+ # - system.class.to.load
+ #
+ # The code block below will appear on the same level as the feature
+ # description:
+ #
+ # .. code-block:: text
+ #
+ # provide model/formula pillar snippets
+
+
+ summary: >
+ This section is not mandatory. Use it to highlight the change.
+
+ features:
+ - Use the list to record summary of **NEW** features
+ - Provide detailed description of the feature indicating the use cases
+ when users benefit from using it
+ - Provide steps to deploy the feature (if the procedure is complicated
+ indicate during what stage of the deployment workflow it should be
+ deployed).
+ - Provide troubleshooting information, if any.
+
+ fixes:
+ - Use the list to record summary of a bug fix for blocker, critical.
+ - Provide a brief summary of what has been fixed.
+
+ others:
+ - Author any additional notes. Use this section if note is not related to
+ any of the common sections above.
+
diff --git a/releasenotes/notes/escaping-references-e76699d8ca010013.yaml b/releasenotes/notes/escaping-references-e76699d8ca010013.yaml
new file mode 100644
index 0000000..41845ee
--- /dev/null
+++ b/releasenotes/notes/escaping-references-e76699d8ca010013.yaml
@@ -0,0 +1,3 @@
+---
+others:
+ - The escaping of references changes how the constructs '\${xxx}' and '\\${xxx}' are rendered.