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

Note

This filter plugin is part of the arillso.agent collection (version 2.1.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.agent.

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

New in arillso.agent 2.1.0

Synopsis

  • Picks the full apt version string for an upstream version out of apt-cache madison output.

  • apt matches an = pin against the full version string and does not expand globs in it. Grafana publishes 1.21.3-1 for alloy 1.21.3, while Tailscale and DigitalOcean publish the bare 1.104.4 and 3.18.16, so the exact string has to be looked up on the host.

  • 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.agent.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.agent.apt_version_pin(key1=value1, key2=value2, ...)

Parameter

Comments

version

string / required

The upstream version to resolve, for example 1.21.3.

Matched when it opens the string or follows an epoch colon, and is followed by the end of the string or a - or + separator. 1.21.3 therefore takes 1.21.3-1 but not 1.21.30, and 1.21 matches nothing.

~ is not a separator; in Debian ordering it sorts before the release, so 1.21.3~rc.0-1 is a pre-release of 1.21.3 and never satisfies the pin.

Examples

- name: Look up the versions the apt repository offers
  ansible.builtin.command:
      cmd: apt-cache madison alloy
  register: alloy_madison
  changed_when: false

- name: Resolve the full apt version string
  ansible.builtin.set_fact:
      alloy_apt_version: "{{ alloy_madison.stdout_lines | arillso.agent.apt_version_pin('1.21.3') }}"
  # Returns 1.21.3-1, or None when the repository no longer carries the version.

Return Value

Key

Description

Return value

string

The full apt version string, epoch and revision included.

None when no line matches the requested version.

Returned: success

Authors

  • arillso