ramondevprivate.common.fleet_report filter – Merge fleet snapshots into the data for the Markdown pages

Note

This filter plugin is part of the ramondevprivate.common collection (version 1.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 ramondevprivate.common.

To use it in a playbook, specify: ramondevprivate.common.fleet_report.

New in ramondevprivate.common 1.0.0

Synopsis

  • Merges stored snapshots with the snapshots of the current run (current ones win), marks hosts that were targeted but not collected (not reachable, or a task failed), and computes fleet statistics and formatted values.

  • Snapshots with another schema version are ignored.

Input

This describes the input of the filter, the value before | ramondevprivate.common.fleet_report.

Parameter

Comments

Input

list / elements=dictionary / required

Snapshots collected in this run.

Positional parameters

This describes positional parameters of the filter. These are the values positional1, positional2 and so on in the following example: input | ramondevprivate.common.fleet_report(positional1, positional2, ...)

Parameter

Comments

stored

list / elements=dictionary / required

Snapshots read from the data directory.

unreachable

list / elements=string / required

Hosts targeted in this run whose snapshot could not be collected.

options

dictionary

Settings of the role. Missing keys use the defaults.

Unknown keys and invalid values are an error, so a typo can’t silently switch something off.

Default: {}

inactive_days

integer

A last login older than this many days (at collection time) marks a user inactive.

Default: 365

stopped_containers

boolean

List containers that are not running. If false, only running containers are shown and counted.

Choices:

  • false

  • true ← (default)

update_max_age_days

integer

Auto-updates without a successful run for this many days need attention.

Default: 7

Examples

- name: Build report
  ansible.builtin.set_fact:
    report: >-
      {{ current | ramondevprivate.common.fleet_report(stored, ansible_play_hosts_all | difference(ansible_play_hosts)) }}

- name: Build report with a stricter auto-update threshold
  ansible.builtin.set_fact:
    report: >-
      {{ current | ramondevprivate.common.fleet_report(stored, [], {'update_max_age_days': 3}) }}

Return Value

Key

Description

Return value

dictionary

Input for the overview and the server pages.

Returned: success

attention

list / elements=dictionary

Needs-attention findings, grouped by host in host order.

Returned: success

detail

string

What the finding is about, e.g. the UFW state, the port, or the account and key fingerprint.

Returned: success

finding

string

Short text of the finding.

Returned: success

host

string

Inventory name of the host.

Returned: success

rule

string

Rule id.

Returned: success

Can only return:

  • "ufw_off"

  • "fail2ban_public"

  • "auto_updates"

  • "sudo_full_nopasswd"

  • "key_without_comment"

charts

dictionary

Raw numbers for the Mermaid charts, in host order.

Returned: success

cores

list / elements=integer

Cores per host.

Returned: success

disk_gib

list / elements=float

Disk capacity per host in GiB, one decimal.

Returned: success

height

integer

Chart height in pixels for horizontal bars, growing with the number of hosts.

Returned: success

labels

list / elements=string

Host names without the domain labels all hosts share.

Returned: success

ram_gib

list / elements=float

RAM per host in GiB, one decimal.

Returned: success

containers

integer

Number of containers on the pages (without stopped ones if options.stopped_containers=false).

Returned: success

hosts

list / elements=dictionary

One entry per host, sorted by name, with the formatted values the role’s templates print.

Its keys follow the templates and are not a stable interface; the JSON snapshots are.

Returned: success

internal

integer

Number of hosts whose exposure is internal.

Returned: success

last_updated

string

Newest collection date of all snapshots (YYYY-MM-DD); empty without snapshots.

Returned: success

metrics

list / elements=dictionary

Cores, RAM and disk across the fleet.

Returned: success

average

string

Formatted average; empty without hosts.

Returned: success

label

string

Cores, RAM or Disk.

Returned: success

maximum

string

Formatted largest value; empty without hosts.

Returned: success

minimum

string

Formatted smallest value; empty without hosts.

Returned: success

total

string

Formatted sum (RAM and disk with binary units); empty without hosts.

Returned: success

os_counts

list / elements=dictionary

Number of servers per OS major version (Debian 13.1 and 13.3 count as Debian 13), sorted by OS.

Returned: success

os

string

OS name and major version, for example Debian 13.

Returned: success

servers

integer

Number of servers running it.

Returned: success

public

integer

Number of hosts whose exposure is public.

Returned: success

servers

integer

Number of hosts in the report.

Returned: success

totals

dictionary

Totals row of the hardware table.

Returned: success

cores

integer

Sum of all cores.

Returned: success

disk

string

Formatted sum of all disk capacity.

Returned: success

ram

string

Formatted sum of all RAM.

Returned: success

unreachable

integer

Number of hosts not collected in this run (not reachable, or a task failed) or marked unreached_since by an earlier run.

Returned: success

Authors

  • Ramon (@RamonDevPrivate)