The ansible_lsb.codename variable is not a native fact in modern Ansible releases, causing lookup errors when referenced directly. To resolve this, you must explicitly load the lsb_release facts using the setup module with the filter parameter set to *lsb*. This ensures the distribution codename data is available for your playbooks.
Understanding the Missing Fact
Ansible gathers system information through a process called fact gathering, which runs by default at the start of every playbook execution. Historically, certain platform-specific details were included in the standard fact set, but recent versions have optimized this process by reducing the number of facts collected by default. The ansible_lsb dictionary, which contains Linux Standard Base (LSB) information such as the distributor ID, description, release number, and codename, is one of these excluded facts.
When a playbook attempts to access ansible_lsb.codename without first ensuring those facts are loaded, Ansible returns an undefined variable error or a lookup failure. This is particularly common when migrating older playbooks to newer Ansible control nodes or when working in environments where minimal fact gathering is preferred for performance reasons. The error typically manifests as a fatal error during the task execution phase, preventing subsequent tasks from running.
Why It Was Removed
The removal of LSB facts from the default set was a deliberate design choice to improve playbook execution speed. Collecting LSB information requires executing external commands on the target host, which adds latency to every run. By excluding it by default, Ansible reduces overhead for users who do not need distribution-specific details. However, this change breaks backward compatibility for scripts that relied on the implicit availability of these variables.
Solution: Explicitly Loading LSB Facts
The most robust way to fix this issue is to explicitly request the LSB facts within your playbook. You can achieve this by adding a dedicated task that uses the setup module with a filter. This approach is cleaner than modifying global configuration files and allows you to control exactly when and where the facts are gathered.
- name: Gather LSB facts
ansible.builtin.setup:
filter: "*lsb*"
This task should be placed early in your playbook, before any tasks that reference ansible_lsb.codename. Once executed, the fact becomes available for use in templates, conditionals, and other tasks. The filter syntax uses wildcards to match all facts containing "lsb" in their key names, ensuring that ansible_lsb.distrib_id, ansible_lsb.release, and ansible_lsb.codename are all populated.
Alternative: Using the lsb_release Module
If you prefer not to use the setup module, you can alternatively use the community.general.lsb_info module. This module is specifically designed to gather LSB information and stores the results in variables prefixed with lsb_ rather than ansible_lsb_. Note that this changes the variable name you must use in your playbook from ansible_lsb.codename to lsb.codename.
- name: Get LSB info
community.general.lsb_info:
register: lsb_result
- name: Display codename
debug:
msg: "The codename is {{ lsb_result.codename }}"
This method is useful if you only need LSB data and want to avoid the broader scope of the setup module. However, it requires the community.general collection to be installed on the control node. For most users, the setup module approach is simpler because it relies on built-in functionality.
Global Configuration Approach
If you frequently encounter this issue across many playbooks, you might consider configuring Ansible to always include LSB facts. This can be done by modifying the ansible.cfg file on your control node. Add the following line under the [defaults] section:
fact_caching_connection = /tmp/ansible_fact_cache
fact_filter = *lsb*
However, this is generally discouraged because it forces LSB fact collection for every single task, even those that do not need it. It also affects performance globally. A better practice is to handle fact gathering locally within specific plays where the data is required, keeping your playbooks modular and efficient.
Debugging Undefined Variables
If you are still experiencing issues after implementing the fix, verify that the facts are actually present. Use the debug module to print the entire ansible_lsb dictionary. This helps confirm whether the filter worked correctly and whether the target host supports LSB reporting. Some minimal container images or custom Linux distributions may not provide LSB information at all, in which case the variable will remain empty even after explicit gathering.
For more complex scripting challenges involving variable expansion and shell interactions, you may find our guide on troubleshooting bash script quoting issues helpful, as improper handling of these variables can lead to similar errors in shell tasks. See Troubleshooting Bash Script with Suspected Issues of Spaces, Dashes, Filenames and Quoting for related context.
Best Practices for Distribution Detection
While fixing the immediate error is important, consider whether relying on ansible_lsb.codename is the best long-term strategy. Distribution codenames can vary between major versions of the same OS family. For example, Ubuntu 20.04 is "focal" and Ubuntu 22.04 is "jammy". If your playbook needs to handle multiple versions, hardcoding checks against specific codenames can become brittle.
Instead, consider using higher-level abstractions provided by Ansible. The ansible_distribution and ansible_distribution_version facts are more stable and widely supported. You can combine these with conditional logic to apply different configurations based on major version numbers rather than codenames. This makes your playbooks more resilient to minor updates and point releases.
Additionally, if you are managing RHEL-based systems, note that they often use different identification methods compared to Debian-based systems. Understanding these differences is crucial for writing cross-platform playbooks. Our article on troubleshooting RHEL 7 Ansible execution provides deeper insights into platform-specific behaviors. Read Troubleshooting Linux RHEL 7 to understand how fact gathering differs across distributions.
Frequently Asked Questions
What happens if I don't specify the filter?
If you do not specify the filter, Ansible will only gather the default set of facts, which excludes LSB information. Consequently, any attempt to access ansible_lsb.codename will result in an undefined variable error. You must explicitly request these facts to make them available.
Can I enable LSB facts globally for all hosts?
Yes, you can set fact_filter = *lsb* in your ansible.cfg file. However, this is not recommended because it increases execution time for every task on every host, even those that do not need LSB data. Localized gathering is more efficient.
Does this error occur on Windows hosts?
No, the ansible_lsb facts are specific to Linux systems. On Windows, Ansible gathers different facts related to the operating system, such as ansible_os_family and ansible_windows_system32_path. LSB facts are irrelevant for Windows targets.
How do I check if LSB facts are already loaded?
You can run a simple playbook task with the debug module to print {{ ansible_lsb }}. If the output shows a dictionary with keys like distrib_id and codename, the facts are loaded. If it prints nothing or an error, they are not available.
Is there a performance penalty for gathering LSB facts?
There is a small performance penalty because Ansible must execute the lsb_release command on the target host. However, this cost is negligible for most environments. The benefit of having accurate distribution information outweighs the minor increase in runtime.
What if my host doesn't support lsb_release?
If the target host does not have the lsb-release package installed or lacks LSB support, the fact gathering will fail or return empty values. In such cases, you may need to install the necessary packages or use alternative methods to identify the distribution, such as checking /etc/os-release directly.