diff --git a/docs/conf.py b/docs/conf.py index d29edbe2c..56e54a5e6 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,7 @@ release = '1.0' extensions = [ 'sphinx.ext.extlinks', 'sphinx_lesson', 'sphinx.ext.todo', - 'ext.xref', 'ext.extinclude' + 'ext.xref', 'ext.extinclude', 'sphinxnotes.strike', ] #---- disable highlight warnings with yaml new version ---- diff --git a/docs/readme.txt b/docs/readme.txt index 2f6c263c1..928648cee 100644 --- a/docs/readme.txt +++ b/docs/readme.txt @@ -14,6 +14,7 @@ Then install the sphinx libraries:: ./.venv/bin/pip3 install sphinx ./.venv/bin/pip3 install sphinx_rtd_theme ./.venv/bin/pip3 install sphinx_lesson + ./.venv/bin/pip3 install sphinxnotes The generatef html output is located in the `docs/build/html` subfolder, diff --git a/docs/vac.rst b/docs/vac.rst index 2fcf22bdc..cd70527c3 100644 --- a/docs/vac.rst +++ b/docs/vac.rst @@ -17,12 +17,21 @@ More precisely, this extends Configuration as Code (CaC) principles. The idea is to treat variables — not just infrastructure or configuration — as version-controlled, declarative, and automated code rather than manual, static, or hardcoded values. With growing complexity of the infrastructure, it is difficult to manage all the variables. -Due to more and more available variables required to set up the infrastructure, -it became quite annoying to hand the necessary variables to where they are actually used +Due to more and more available variables required to set up the infrastructure, +it became quite annoying to hand the necessary variables to where they are actually used and even more annoying to add new variables. Variables can be redundant and sometimes are defined on several places. +.. attention:: + + Many IaC projects use what could be called Values as Code (User Data as Code with the Rougail terminology). + Values are placed in a versioned and structured repositories. + But we don't share the variable itself (apart from its name). + We are thinking of its type, its scope, its purpose, etc. + + Variables as Code is not only the values. + Reusable and shareable variables ------------------------------------ @@ -43,7 +52,7 @@ For this, we thought of a solution and came up with a concept of managing all ou Often when we talk about :term:`VaC` (or CaC) we think of the different environments (Development, Staging, Production). -With Rougail, this question does not arise. Essentially, Rougail manages this with user data. +With Rougail, this question does not arise. Essentially, Rougail manages this with user data. Here we're talking about sharing variables between projects. Furthermore, using a tool like Rougail allows you to use variables with different IaC deployment solutions without having to redefine those variables. @@ -59,4 +68,139 @@ Once defined, variables must be able to: - display and archive the final values in a readable format - allow other applications to use these variables +Variables as Code with Rougail by example +------------------------------------------- +There's nothing better than a simple example to illustrate everything that's just been presented. + +Structured file +~~~~~~~~~~~~~~~~~~ + +Let's start by creating a file in Rougail format. + +This isn't the time to explain the format. + +But we'll create a quick file here to create the "my_variable" variable: + +.. code-block:: yaml + + %YAML 1.2 + --- + version: 1.1 + + my_variable: my_value # It's my variable + ... + +Let's document it +'''''''''''''''''''' + +We can start by generating the variable's documentation from this file: + +.. list-table:: + + * - Variable + - Description + + * - **my_variable** + + `string `__ `mandatory` + - It's my variable. + + **Default**: my_value + +Or an example user data file in YAML format: + +**Example with all variables modifiable:** + +.. code-block:: yaml + + --- + my_variable: my_value + +Regarding documentation, it's even possible to generate a changelog view for users. + +Let's imagine that the default value was originally `old_value` and is now `my_value`: + +.. list-table:: + + * - Variable + - Description + + * - **my_variable** + + `string `__ `mandatory` + - It's my variable. + + **Default**: :strike:`old_value` **myvalue** + +Now it's time to export +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In simple JSON format: + +.. code-block:: json + + { + "my_variable": "my_value" + } + +Or in advanced Ansible format: + +.. code-block:: json + + { + "_meta": { + "hostvars": { + "host1.net": { + "ansible_host": "host1.net", + "inventory": { + "my_variable": "my_value" + } + } + } + }, + "app1": { + "hosts": [ + "host1.net" + ] + } + } + +Or display it +~~~~~~~~~~~~~~~~ + +Displaying informations is an important step in the VaC approach. In a complex environment where variables are defined in multiple places, not to mention their values located elsewhere, maintaining good traceability of variables and their values becomes difficult. + +Managing variables like code also means `compiling` the informations. + +Here display our examples: + +.. raw:: html + :class: output + + 
+    ╭─────── Caption ────────╮
+    │ Variable Default value │
+    ╰────────────────────────╯
+    Variables:
+    ┗━━ 📓 It's my variable: my_value
+
+ +Now change the value with differents user data: + +.. raw:: html + :class: output + + 
+    ╭────────────── Caption ───────────────╮
+    │ Variable Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    ╭──────────── Layers ─────────────╮
+    │ • the YAML file "user_data.yml" │
+    │ • environment variable          │
+    │ • Questionary                   │
+    ╰─────────────────────────────────╯
+    Variables:
+    ┗━━ 📓 It's my variable: I am right about the value ◀ loaded from questionary 
(⏳ I define the value! ◀ loaded from environment variable 
⏳ no it's my value ◀ loaded from the YAML file "user_data.yml" 
⏳ my_value)
+