Open discussion: the use and necessity of the 'bool' filter in our Ansible codebase

[vitabaks]

It's important to have a clear understanding and consensus on our code practices.

The bool filter in Ansible is used to convert a value into a boolean. This can be quite useful when dealing with values that might be represented as strings or other data types in variables but need to be treated as booleans for the purposes of conditionals, comparisons, etc.

On the other hand, excessive use of the bool filter when not required could potentially lead to confusion and might not adhere to the best practices or readability and simplicity.

We should consider several aspects:

1. The specific cases in our codebase where the bool filter is currently being used. Are these instances where the bool filter is necessary and adds clarity, or could they be handled differently?
2. The potential impact on our codebase if we were to stop using the bool filter. Would this lead to more readable and maintainable code, or could it introduce potential errors and ambiguity?
3. Are there guidelines or best practices in the Ansible community that we should consider regarding the use of the bool filter?

Let's explore these questions in this discussion thread.

the first discussion started here #413

[vitabaks]

cc @pa-decarvalho @ThomasSanson

[ThomasSanson]

@vitabaks @pa-decarvalho

In the context of our work with Ansible and Jinja2, converting values to booleans, while convenient in some scenarios, is not a universal rule to be applied. It is a decision that must be made based on the context and specific requirements of our code.

The | bool operator is particularly useful when dealing with values that are not inherently boolean, such as values from environment variables or user inputs. These values are often strings, and using | bool allows us to manipulate them as booleans, which can facilitate controlling the flow of our code.

However, we need to be aware of cases where this conversion may not be ideal. For example, if we are dealing with a value that can be null (or None), using | bool will convert that value to False, which could mask the null state and potentially introduce errors in our logic.

Fictional Example (just for illustration)

Let's assume we have a variable database_connection that can have three possible values: "true", "false", and "null". "true" means the database connection is active, "false" means it is inactive, and "null" means it has not been configured yet.

- name: Check database connection
  command: check_database_connection
  register: database_connection

- name: Handle database connection
  command: handle_database_connection
  when: database_connection.stdout | bool

In this case, we might be tempted to use | bool to convert the output of check_database_connection to a boolean. However, this could be problematic if the output is "null". In fact, "null" would be converted to false, which could be interpreted as meaning that the database connection is inactive. However, in reality, the database connection has not been configured yet.

In this case, a better approach might be to explicitly handle the "null" case instead of converting the output to a boolean. For example:

- name: Handle database connection
  command: handle_database_connection
  when: database_connection.stdout == 'true'

This would ensure that handle_database_connection is only executed when the database connection is active and would avoid potential issues caused by converting "null" to false.

In summary, converting to a boolean is a valuable tool, but like any tool, its usage should be tailored to the situation.

However, the safest and most reliable approach is to have test scenarios. They are the only guarantee of reproducibility and the expected result.

[vitabaks]

I just had an example if a variable is passed through --extra-vars in this form firewall_enabled_at_boot='false', then without the bool filter, the condition not works.

[ThomasSanson]

@vitabaks

Indeed, there is a distinction between firewall_enabled_at_boot='false' and firewall_enabled_at_boot=false.

The act of enforcing a boolean type is and remains a good practice. However, it is equally important that users correctly variabilise on their end.

To this end, the use of pre-checks (with asserts) is also a good practice. Essentially, we verify the expected format.

Here is an example of variable asserts that we will implement:

    # ==============================================================================
    # ext_matomo_site_url
    # ==============================================================================
    # Test for the variable ext_matomo_site_url
    - name: Playbook asserts | test ext_matomo_site_url is set correctly
      block:
        # Test if ext_matomo_site_url is defined
        - name: Playbook asserts | test ext_matomo_site_url is defined
          ansible.builtin.assert:
            that:
              - ext_matomo_site_url is defined
            fail_msg:
              - You must provide this variable
              - ""
              - 'ext_matomo_site_url: "https://example.com/qualif/"'
        # Test if ext_matomo_site_url is a string
        - name: Playbook asserts | test ext_matomo_site_url is string
          ansible.builtin.assert:
            that:
              - ext_matomo_site_url is string
            fail_msg:
              - The content of the variable must be a string
              - ""
              - 'ext_matomo_site_url: "https://example.com/qualif/"'
        # Test if ext_matomo_site_url is a url
        - name: Playbook asserts | test ext_matomo_site_url match url regex
          ansible.builtin.assert:
            that:
              - ext_matomo_site_url is match("^(?:http(s)?:\/\/)?[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=.]+$")
            fail_msg:
              - This variable must match the url regex https://www.regextester.com/94502
              - ""
              - 'ext_matomo_site_url: "https://example.com/qualif/"'

[vitabaks]

you and I understand that putting false in quotes means translating a boolean into a string.

My task is to make the code work in different cases, even when the user mistakenly indicated in quotation marks. That's why I like to use the bool filter.

Anyone can be a user, not even a developer ;) even the one who doesn't know what ansible is.

[ThomasSanson]

Yes, quite right. I hope there is no misinterpretation because we are on the same wavelength

And I completely agree with you on the point that everyone can be a user, but not everyone can be a developer

Hence my example with the assert, in order to guide people

[ThomasSanson]

In our Ansible collections, what we do first is to verify, using asserts, that the variables are properly filled and adhere to conventions. We provide clear messages to guide people (as shown in the example)

This way, we already ensure the correct population of the inventory and variables

Next, we run pre-checks (network access, disk space, system compatibility, etc.)

After that, we execute the playbook (install, update, etc.)

All of this can be done in the --check --diff mode to avoid making any modifications but anticipate the actions that will be taken

Finally, a set of health checks is performed to ensure smooth operation, providing an overall summary

(This is partly what is already being done there)

All in all, yes, using | bool is a good practice, but it requires careful attention (without pressure) as it can have unintended effects (as explained in my example above). It is rare, but not entirely improbable either

Hence, my thought is that we should also strengthen the testing process

[ThomasSanson]

I am in favor of generalizing the | bool, but with the addition of an assert statement for variables that can be provided by users 😇