rougail/docs/vac.rst

Variables as Code
==================


Definition
--------------

.. glossary::

   VaC

       VaC stands for **Variables as Code**, it is the practice of managing configuration variables the same way you treat source code.

It is a concept that extends the Infrastructure as Code (IaC) philosophy to the management of configuration variables, secrets, and environment-specific settings.
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
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
------------------------------------

A typical example is the management of Ansible collections.

Currently, when you distribute an Ansible collection, you distribute the recipes that allow you to deploy a component, the default values ​​for certain variables, and possibly variable validation.

However, you don't share the variable declarations. Therefore, each user would have to rewrite the user documentation, define the global context themselves, and so on. It is therefore the user's responsibility to maintain the consistency of the variables with these given problems.
With Rougail, the collection maintainer can do this work himself and everyone will benefit.

And we're not even talking about managing variables in a multi-project context.
It is often necessary to recreate the same variables with the same constraints over and over again between different projects.

Variables as Code with Rougail
-----------------------------------

For this, we thought of a solution and came up with a concept of managing all our variables as a code called :term:`VaC (Variables as Code) <VaC>`.

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.
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.
It can be said that Rougail allows you to use variables not only between projects but also between tools.

To do this, we need typed variable definitions with defaults and validation.

Once defined, variables must be able to:

- provide useful information to the operator to make their choices
- load user values from differents sources
- validate the context
- 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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `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 <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`
     - It's my variable.

       **Default**: :strike:`old_value` :underline:`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

    <pre>
    ╭─────── Caption ────────╮
    │ Variable <span style="color: #ff7300">Default value</span> │
    ╰────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 It's my variable: <span style="color: #ff7300">my_value</span>
    </pre>

Now change the value with differents user data:

.. raw:: html
   :class: output

    <pre>
    ╭────────────── Caption ───────────────╮
    │ Variable <span style="color: #00aa00">Modified value</span>              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    ╭──────────── Layers ─────────────╮
    │ • the YAML file "user_data.yml" │
    │ • environment variable          │
    │ • Questionary                   │
    ╰─────────────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 It's my variable: <span style="color: #00aa00">I am right about the value</span> ◀ loaded from questionary <br/>(⏳ I define the value! ◀ loaded from environment variable <br/>⏳ no it's my value ◀ loaded from the YAML file "user_data.yml" <br/>⏳ my_value)
    </pre>