arillso.container.apt_version_pin filter – Resolve an apt version pin from apt-cache madison output

Note

This filter plugin is part of the arillso.container collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install arillso.container.

To use it in a playbook, specify: arillso.container.apt_version_pin.

New in arillso.container 2.0.0

Synopsis

  • Picks the full apt version string for a marketing version out of apt-cache madison output.

  • apt matches an = pin against the full version string, which carries an optional epoch and a distro release suffix, and it does not expand globs in that pin.

  • A bare pin such as docker-ce=29.7.2 therefore never resolves, and neither does docker-ce=*29.7.2-*; only the string madison prints does.

  • Returns None when the version is not in the repository, so the calling task can fail with a readable message instead of a Python traceback.

Input

This describes the input of the filter, the value before | arillso.container.apt_version_pin.

Parameter

Comments

Input

list / elements=string / required

Lines of apt-cache madison <package> output, typically stdout_lines of the command.

Each line looks like <package> | <version> | <repository>; only the middle field is read.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | arillso.container.apt_version_pin(key1=value1, key2=value2, ...)

Parameter

Comments

version

string / required

The marketing version to resolve, for example 29.7.2 or 5.4.0.

Matched on (^|:<version>-) so the version either opens the string or follows the epoch colon, and the trailing hyphen keeps 29.7.1 from taking 29.7.10 and rejects a bare prefix like 29.7.

Dots are matched literally, so 5.4.0 does not also match a 5X4X0 build.

Notes

Note

  • The filter never raises on a missing version; the readable error belongs in an ansible.builtin.fail task.

Examples

# Resolve the exact apt version string before pinning it
- name: Resolve the apt version string for the pin
  ansible.builtin.command:
      cmd: apt-cache madison docker-compose-plugin
  register: compose_madison
  changed_when: false

- name: Set the resolved apt version string
  ansible.builtin.set_fact:
      docker_compose_v2_apt_version: >-
          {{ compose_madison.stdout_lines
             | arillso.container.apt_version_pin(docker_compose_v2_version) }}
  # Returns e.g. 5.4.0-1~ubuntu.24.04~noble, or None when the repository
  # no longer carries the version.

Return Value

Key

Description

Return value

string

The full apt version string, epoch and distro suffix included.

None when no line matches the requested version.

Returned: success

Authors

  • arillso