The package module and the portability trap · Ansible

ansible.builtin.package looks like the answer to running one patching role across a mixed fleet. It selects apt on Debian-family hosts and dnf on RHEL-family ones, so the role stops needing a when: ansible_facts.os_family == 'Debian' on every task.

It does exactly that, and it does only that. The documentation says so in a sentence that is easy to skim past:

Package names also vary with package manager; this module will not “translate” them per distribution. For example libyaml-dev, libyaml-devel.

The manager is abstracted. The names are not. Half a problem solved is still half a problem, and the half that remains is the half that fails in production rather than at parse time.

What it actually abstracts

Read-only / Safethe module's complete parameter list— Read-only. Three parameters. That brevity is the point: the module documents only the minimum intersection of arguments that every packaging module supports.

$ ansible-doc ansible.builtin.package

   name    Package name, or package specifier with version.
         Syntax varies with package manager. For example `name-1.0'
         or `name=1.0'.
         Package names also vary with package manager; this module
         will not "translate" them per distribution.

 state   Whether to install (`present'), or remove (`absent') a
         package.
         You can use other states like `latest' ONLY if they are
         supported by the underlying package module(s) executed.

 use     The required package manager module to use (`dnf', `apt',
         and so on). The default `auto' will use existing facts or
         try to auto-detect it.
      default: auto

Three parameters, and the documentation is explicit about why: “This documentation only covers the minimum intersection of module arguments that all packaging modules support.”

Everything from the previous two lessons is outside that intersection. cache_valid_time, dpkg_options, lock_timeout, only_upgrade, security, update_only, download_only, allowerasing — none of them are package parameters.

The documentation does say “all arguments will be passed to the underlying module”, so an extra argument is not silently dropped. It is passed through, and it fails on any host whose selected manager does not accept it. A package task carrying security: true works on your RHEL-family hosts and fails on your Debian-family ones — which is to say, the abstraction stops abstracting at exactly the point where you needed it to.

The name problem, and the shape that solves it

libyaml-dev on Debian and Ubuntu. libyaml-devel on RHEL, Rocky and Alma. The module will not bridge that, so you bridge it in variables.

Configuration changea role vars/ split keyed on os_family— Installs packages. The names come from a per-family vars file loaded by fact, so the task itself stays free of conditionals.

# roles/appdeps/vars/Debian.yml
app_packages:
- libyaml-dev
- libssl-dev
- python3-dev

# roles/appdeps/vars/RedHat.yml
app_packages:
- libyaml-devel
- openssl-devel
- python3-devel

# roles/appdeps/tasks/main.yml
- name: Load the package names for this distribution family
ansible.builtin.include_vars: '{{ ansible_facts.os_family }}.yml'

- name: Install the application build dependencies
ansible.builtin.package:
  name: '{{ app_packages }}'
  state: present

This is the shape worth internalising, because it puts the variability where it belongs. The task expresses the intent once. The vars files carry the per-family facts, and a reviewer can see the whole distribution difference by opening two short files rather than reading every task in the role.

include_vars on a fact fails loudly, and that is the good case

include_vars: '{{ ansible_facts.os_family }}.yml' fails on any host whose os_family you have not written a file for. On a fleet that acquires an Alpine or a SUSE host, that failure is the first thing you learn about it.

That is the outcome you want, and it is worth protecting. The tempting softener is ignore_errors: true or a with_first_found fallback to a default.yml, and both convert a loud “you have an unhandled distribution” into a quiet “the package list was empty and the role did nothing”.

If you do want a fallback, make it fail on the thing that matters:

- name: Refuse to run against an unhandled distribution family
  ansible.builtin.fail:
    msg: >-
      No package name mapping exists for os_family
      {{ ansible_facts.os_family }} on {{ inventory_hostname }}.
      Add roles/appdeps/vars/{{ ansible_facts.os_family }}.yml.
  when: ansible_facts.os_family not in ['Debian', 'RedHat']

ansible_facts.os_family is the right key for this, not ansible_facts.distribution. os_family groups Rocky, Alma, RHEL, CentOS and Fedora as RedHat, and Debian and Ubuntu as Debian, which is the granularity package names actually vary at. Keying on distribution gives you five near-identical files that drift apart.

`use` and `ansible_package_use`

The default auto selects the manager from facts — ansible_facts.pkg_mgr is the fact that carries it. Two overrides exist.

use is the task parameter. ansible_package_use is a variable, available since ansible-core 2.17, which can be set in inventory or group vars. The documentation states the precedence directly: the variable is available “but this option still takes precedence” — so use on the task wins over ansible_package_use.

Read-only / Safesetting the manager where the exception lives— Read-only: a variable assignment, not a task. Putting the override in inventory keeps the exception visible next to the hosts it applies to.

# host_vars/build07.example.com.yml
# This host runs a dnf-4 stack that auto-detection gets wrong after the
# in-place upgrade. Owner: platform. Remove once the host is rebuilt.
ansible_package_use: dnf

The order to reach for these: fix the facts, then set the variable in inventory, and only put use on a task when the task genuinely must pin a manager regardless of the host. A use: hard-coded in a shared role is an assumption about every host the role will ever run against.

Check mode is where the abstraction leaks most

Every other module in this part declares a definite check-mode capability. apt is check_mode: full. dnf and dnf5 are check_mode: full.

package declares check_mode: N/A, with the detail “support depends on the underlying plugin invoked”.

A --check run through package does not carry a uniform guarantee

This matters because check mode is how a patch change gets reviewed before it is applied, and how the CI gate in Part XXXVIII decides whether a change is safe.

Through apt or dnf directly, --check resolves a real transaction and reports what would change. Through package, what you get depends on which plugin was dispatched on that host — which depends on facts, which depend on the host. A check run across a mixed fleet can carry strong guarantees on some hosts and weaker ones on others, and nothing in the output distinguishes them.

For a fleet-wide patch review, use the specific module. The reviewer is reading the check output as evidence, and evidence whose strength varies by host without saying so is worse than no evidence.

The same caveat applies to diff_mode, documented identically as depending on the dispatched plugin.

When `package` is genuinely the right call

The abstraction earns its place when three things are true at once:

The package name is the same everywhere. curl, git, rsync, jq, tmux, chrony. Development headers and library packages almost never qualify.
You need only present or absent. These are the two states the module documents; anything else is conditional on the dispatched plugin.
No manager-specific option is required. No cache handling, no lock timeout, no security filter, no repository scoping.

Configuration changethe case package was written for— Installs a small set of universally-named tools. Runs identically on Debian-family and RHEL-family hosts with no conditional and no vars file.

- name: Ensure the standard operator toolset is present
ansible.builtin.package:
  name:
    - curl
    - git
    - rsync
    - tmux
  state: present

That task is better than the two-conditional version it replaces. It is shorter, it has one failure mode instead of two, and it does not go stale when someone adds a third distribution family.

The judgement is not “abstract or do not abstract”. It is knowing that this particular abstraction covers the manager and not the vocabulary, and putting it where that is enough.

Under the hood

package is an action plugin that runs a redirection on the controller before any module ships to the host.

The dispatch chain: the action plugin reads ansible_facts.pkg_mgr. If facts have not been gathered, it runs ansible.builtin.setup itself to obtain them — the documentation states this explicitly, and it is why a package task works in a play with gather_facts: false while costing a hidden fact-gathering round trip on the first such task.

It then resolves the fact to a module name, merges the task arguments, and executes that module. apt on Debian-family, dnf on RHEL-family with dnf-4, and so on.

Two consequences follow from it being a redirection rather than a wrapper.

The parameters are not validated against package’s three-parameter schema. They are passed to the resolved module and validated there. That is why security: true on a package task is a RHEL-family success and a Debian-family argument error rather than a parse failure on the controller.

The attributes you read on package are not the attributes that execute. check_mode: N/A on package is the honest statement that the real answer is on whichever module ran. The reverse also holds and is useful: ansible.builtin.dnf documents its own action attribute as partial, noting that two action plugins use it under the hood — ansible.builtin.dnf and ansible.builtin.package — so a package task on a RHEL-family host reaches exactly the same code as a dnf task.

For diagnosis: when a package task fails, the error text names the resolved module, not package. That name is the first useful piece of information in the traceback, because it tells you which branch of the dispatch you are debugging.

What happens if you use package to record what is installed across a mixed fleet?

You reach for the wrong module. package installs and removes; it does not report.

The module for the question is ansible.builtin.package_facts, and it handles the mixed fleet properly: its manager parameter defaults to ['auto'] and its strategy parameter defaults to first, meaning it reports from the first supported package manager it finds. Setting strategy: all makes it report from every manager present, which is the setting you want on a host that has both a system package manager and something like pip or snap you also care about.

- name: Collect the installed package inventory
  ansible.builtin.package_facts:
    manager: auto
    strategy: all

It populates ansible_facts.packages as a dictionary keyed by package name, where each value is a list — because a host can legitimately have two versions of the same package installed, which is exactly the case a kernel fleet is full of.

That list-valued structure is what makes package_facts the right tool for the next lesson’s running-versus-installed kernel comparison, and the reason a naive ansible_facts.packages['kernel'].version raises an error: there is no single version, there is a list of them.

The one cost worth knowing: on a large host this is not a cheap fact call. It enumerates the whole RPM or dpkg database. Gather it where you need it rather than in every play.

Knowledge check

Why this matters

Abstractions in configuration management are judged by what they cover and, more importantly, by whether you know where they stop.

ansible.builtin.package covers the manager. It does not cover the package names, the states beyond present and absent, any manager-specific option, or a uniform check-mode guarantee. None of that is hidden — all four are in the module documentation, in plain language, in about six lines.

The failure mode is not that people read those lines and disagree. It is that the module looks like it solves the cross-distribution problem, so nobody reads them, and the gap is discovered by a task that worked in staging on Ubuntu and failed at 02:00 on Rocky.

Which is the same lesson as every other module in this part, arriving from a different direction: the sixty seconds spent in ansible-doc before the task is written is the cheapest verification available in this entire course.