408 lines
10 KiB
ReStructuredText
408 lines
10 KiB
ReStructuredText
Abstract presentation
|
||
=========================
|
||
|
||
Rougail is a robust and powerful, free/open-source configuration manager.
|
||
|
||
Rougail is:
|
||
|
||
- a CLI (command line interface) utility
|
||
- a `Python <https://www.python.org/>`_ library
|
||
- a YAML based description language
|
||
|
||
The language combines declaration, data validation, and templating in a single, declarative syntax.
|
||
|
||
It will be useful to:
|
||
|
||
- define variables (the structure) easily and their constraints
|
||
- loads those variables
|
||
- generate variables documentation
|
||
- loads variables' values
|
||
- validate the variables and the overall consistency handling system
|
||
- generate custom table views
|
||
- export to different common format (YAML, Ansible, ...)
|
||
- ...
|
||
|
||
Why another configuration manager?
|
||
-------------------------------------
|
||
|
||
Using Rougail tansforms end user consumer defined consistency rules into highly consistent business objects.
|
||
It's a configuration language designed to simplify and unify the way you define,
|
||
validate and generate configuration datas.
|
||
|
||
In other word, making it easier to manage complex configurations across multiple environments.
|
||
|
||
You might tell me that other configuration management tools do the same thing. And that's partly true.
|
||
|
||
But Rougail adds interesting features in variable management that other projects don't have.
|
||
I am of course referring to the documentation management included directly in the configuration manager.
|
||
|
||
Your configuration is therefore consistent, easily accessible, and modifiable.
|
||
|
||
Not to mention the always up-to-date documentation and the information you provide to your users regarding changes to variables.
|
||
|
||
What kind of configuration manager?
|
||
---------------------------------------------
|
||
|
||
At the time of the design of Rougail, there were structuring choices
|
||
that defined the functioning of the tool.
|
||
|
||
The steps in Rougail can be explained as follows:
|
||
|
||
- loading the variable's structured data
|
||
- loading the user data
|
||
- reading, validating, exporting, documenting (and so on...) the data
|
||
|
||
Structured data
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
Structured data is also called the Rougail format.
|
||
|
||
.. glossary::
|
||
|
||
structured data
|
||
|
||
A configuration-first DSL (domain-specific language) designed for describing variables, consistency
|
||
and describe the relationships between variables in a declarative style.
|
||
|
||
The language is a mix of YAML ans Jinja Templating.
|
||
|
||
It goes beyond traditional schema languages (like JSON Schema, OpenAPI, Cuelang)
|
||
by combinig type systems, powerful validation, consistency of the configuration and documentation.
|
||
|
||
Structured data are commonly placed in :term:`structure files <structure file>`.
|
||
|
||
User data
|
||
~~~~~~~~~~
|
||
|
||
.. glossary::
|
||
|
||
user data
|
||
|
||
User datas, as opposed to structured data, are datas that only concern the assignment of values
|
||
and not the consistency of the variables between them.
|
||
|
||
The variable's values are also called **user values**.
|
||
|
||
The consistency field is outside of the user data scope.
|
||
The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
|
||
|
||
Here a some user data examples:
|
||
|
||
- configuration files
|
||
- environment variables
|
||
- external sources
|
||
- command-line options
|
||
- a form
|
||
|
||
Output
|
||
~~~~~~~
|
||
|
||
Structured and user data form a coherent configuration useful for different purposes.
|
||
|
||
Output is here to define what kind of data we want.
|
||
|
||
Here are some output examples:
|
||
|
||
- :term:`Tiramisu` object
|
||
- JSON extraction
|
||
- Ansible inventory extraction
|
||
- documentation
|
||
- custom table views
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
|
||
* - **Structured data**
|
||
|
||
* - **User data**
|
||
|
||
* - **Output**
|
||
|
||
What kind of actor?
|
||
---------------------
|
||
|
||
It's clear that Rougail can be used in many contexts.
|
||
|
||
Here we'll define actor names. Obviously, these aren't the only possible actors.
|
||
|
||
We're just defining the actors within the Rougail context.
|
||
Choice your own actor name if you wish to personnalize in your specific context.
|
||
|
||
.. glossary::
|
||
|
||
integrator
|
||
|
||
An integrator in the Rougail field is the person who writes the :term:`structured <structured data>`\ .
|
||
He has the responsibility of the integration process, that is,
|
||
he defines the variables and the relationship between them, the variables that are allowed
|
||
(or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
|
||
of the organisation of the variables between them.
|
||
|
||
.. glossary::
|
||
|
||
operator
|
||
|
||
An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables,
|
||
his responsabilities are to set variable values correctly.
|
||
|
||
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated.
|
||
The type validation is driven by the definitions in the :term:`structure file <structure file>`.
|
||
|
||
Here is a reminder of the different steps:
|
||
|
||
- the integrator defines the structure
|
||
- the operator sets the value
|
||
- the integrator and/or the operator use the output
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
- Actor
|
||
|
||
* - **Structured data**
|
||
- Integrator
|
||
|
||
* - **User data**
|
||
- Operator
|
||
|
||
* - **Output**
|
||
- - Operator
|
||
- Integrator
|
||
|
||
Variable lifetime
|
||
----------------------
|
||
|
||
Rougail's a configuration language and data validation tool is designed
|
||
to simplify defining, validating, and generating structured configuration and data.
|
||
|
||
Rougail aims at defining variables.
|
||
|
||
Here we are talking about the variable lifetime.
|
||
|
||
The variable’s lifetime is the period between its creation and its destruction.
|
||
|
||
The lifecycle of a variable includes the generic stages (like, in the C language):
|
||
|
||
- Creation: variables are assigned a name and a type
|
||
- Initialization: they are assigned their first value
|
||
- Assignment: the variable's value is modified
|
||
- Reading: the variable's value is used
|
||
- Destruction: the variable terminates upon the destruction of the object
|
||
|
||
But other concepts are included in the lifecycle:
|
||
|
||
- Permission: properties describe access constraints
|
||
- Documentation: informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
|
||
- Specialization: define usage, selection,...
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
- Actor
|
||
- Lifetime
|
||
|
||
* - **Structured data**
|
||
- Integrator
|
||
- - Creation
|
||
- Initialization
|
||
|
||
* - **User data**
|
||
- Operator
|
||
- - Assignment
|
||
- Permission
|
||
|
||
* - **Output**
|
||
- - Operator
|
||
- Integrator
|
||
- - Reading
|
||
- Permission
|
||
- Documentation
|
||
- Specialization
|
||
|
||
Variable mutability
|
||
---------------------
|
||
|
||
Structured data
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
When the integrator defines the structure, variables are mutable.
|
||
|
||
Even if the default behavior is inconsistent, like when there is a conflict between multiple declarations for the same variable,
|
||
|
||
it's possible to explicitly allow to unify (combine) multiple variables declarations.
|
||
|
||
User data
|
||
~~~~~~~~~~
|
||
|
||
At the user data level, it's no more possible to modify any variable definition.
|
||
Here we are just talking about variable's values.
|
||
|
||
Output
|
||
~~~~~~~
|
||
|
||
Variable definition settings are immutable.
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
- Actor
|
||
- Lifetime
|
||
- Mutability
|
||
|
||
* - **Structured data**
|
||
- Integrator
|
||
- - Creation
|
||
- Initialization
|
||
- Mutable
|
||
|
||
* - **User data**
|
||
- Operator
|
||
- - Assignment
|
||
- Permission
|
||
- Immutable
|
||
|
||
* - **Output**
|
||
- - Operator
|
||
- Integrator
|
||
- - Reading
|
||
- Permission
|
||
- Documentation
|
||
- Specialization
|
||
- Immutable
|
||
|
||
Value access
|
||
-------------
|
||
|
||
In the :term:`structured data` step, there is no value, strictly speaking.
|
||
The values set are default values.
|
||
Like other parameters, the default value is explicitly mutable.
|
||
|
||
In the `user data` step, we can modify the values. That's precisely the purpose of this step.
|
||
The configuration is said to be in :term:`read write mode`.
|
||
|
||
But at the `output` step, it is obviously no longer possible to modify the value.
|
||
The configuration is said to be in :term:`read only mode`.
|
||
|
||
.. attention::
|
||
It is important not to confuse `value` and `calculated value`.
|
||
The result of a calculation can change over time.
|
||
In this case, the value does indeed correspond to the result of the calculation.
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
- Actor
|
||
- Lifetime
|
||
- Mutability
|
||
- Value
|
||
|
||
* - **Structured data**
|
||
- Integrator
|
||
- - Creation
|
||
- Initialization
|
||
- Mutable
|
||
- Mutable default value
|
||
|
||
* - **User data**
|
||
- Operator
|
||
- - Assignment
|
||
- Permission
|
||
- Immutable
|
||
- Read write
|
||
|
||
* - **Output**
|
||
- - Operator
|
||
- Integrator
|
||
- - Reading
|
||
- Permission
|
||
- Documentation
|
||
- Specialization
|
||
- Immutable
|
||
- Read only
|
||
|
||
Access control
|
||
-----------------
|
||
|
||
.. FIXME: duplicate from tutorial/properties.rst
|
||
|
||
Access control is achieved through `properties`.
|
||
|
||
.. glossary::
|
||
|
||
property
|
||
|
||
A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
|
||
of a family or a variable.
|
||
These properties change the usual behavior of a variable or family.
|
||
|
||
The properties can be defined permanently or according to the result of a calculation.
|
||
|
||
There is two main properties.
|
||
|
||
Hidden variable
|
||
~~~~~~~~~~~~~~~
|
||
|
||
A `hidden` variable is a variable whose value cannot be modified by the operator.
|
||
|
||
This could be an internal variable used by the integrator that is not supposed to change.
|
||
|
||
Or a variable that only makes sense in a particular context. Therefore, this variable can be hidden and then unhidden depending on the context.
|
||
|
||
Disabled variable
|
||
~~~~~~~~~~~~~~~~~
|
||
|
||
A `disabled` variable is a variable that will not be accessible to any of the actors (integrator and operator).
|
||
|
||
This property is generally used dynamically to remove access to the variable depending on the context.
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Step**
|
||
- Actor
|
||
- Lifetime
|
||
- Mutability
|
||
- Value
|
||
- Access control
|
||
|
||
* - **Structured data**
|
||
- Integrator
|
||
- - Creation
|
||
- Initialization
|
||
- Mutable
|
||
- Mutable default value
|
||
- N/A
|
||
|
||
* - **User data**
|
||
- Operator
|
||
- - Assignment
|
||
- Permission
|
||
- Immutable
|
||
- Read write
|
||
- - hidden
|
||
- disabled
|
||
|
||
* - **Output**
|
||
- - Operator
|
||
- Integrator
|
||
- - Reading
|
||
- Permission
|
||
- Documentation
|
||
- Specialization
|
||
- Immutable
|
||
- Read only
|
||
- - disabled
|
||
- mandatory
|
||
|
||
The lifespan of the variables
|
||
------------------------------
|
||
|
||
A picture is worth a thousand words:
|
||
|
||
.. image:: images/dessin.png
|