Ansible Resource Reporting: Standardized Taxonomy for Collection Developers

What is Resource Reporting?

Ansible resource reporting is a new feature that lets collections declare structured metadata about the external resources their modules manage. It creates a unified, machine-readable picture of automation activity across different vendors and platforms.

Proposed by Steve Fulmer (Red Hat Product Manager for Ansible), this feature maps module return values to a standardized taxonomy using lightweight jq expressions.

See also: New Ansible Content Collections 2026: Cloud, Networking, Security, Observability, and Windows

Why Resource Reporting?

Ansible modules interact with external systems (clouds, hypervisors, network controllers) to manage resources that aren't in your inventory. Until now, there was no standard way for collections to expose structured metadata about what they're touching.

Benefits:

• Machine-readable documentation of managed resources
• Consistent resource identification across vendors (a VMware VM and an AWS EC2 instance are both virtual_machine)
• Unified visibility into off-inventory resources
• Foundation for compliance, auditing, and resource tracking

How It Works

1. Check the Taxonomy

Map your resources to standard device_type values:

Compute:

2. Add a Query File

Create extensions/audit/event_query.yml in your collection:

# extensions/audit/event_query.yml
my_namespace.my_collection.my_module:
  query: >-
    {
      name: .result.name,
      canonical_facts: {
        uuid: .result.uuid
      },
      facts: {
        device_type: "virtual_machine"
      }
    }

3. Write jq Expressions

Each expression outputs a JSON object with three fields:

• name (required) — Human-readable resource name
• canonical_facts (required) — Stable, unique identifiers for deduplication (UUIDs, serial numbers)
• facts (optional) — Categorization metadata including device_type

Vendor-Specific Examples

VMware (Flat Structure)

community.vmware.vmware_guest:
  query: >-
    {
      name: .instance.hw_name,
      canonical_facts: {
        host_name: .instance.hw_name,
        uuid: .instance.hw_product_uuid
      },
      facts: {
        device_type: "virtual_machine",
        guest_id: .instance.hw_guest_id
      }
    }

AWS (Lists with Implied Types)

amazon.aws.ec2_instance_info:
  query: >-
    .instances[] | {
      name: (.tags.Name // .instance_id),
      canonical_facts: {
        instance_id: .instance_id
      },
      facts: {
        device_type: "virtual_machine",
        status: .state.name
      }
    }

Azure (Hierarchical with Regex)

azure.azcollection.azure_rm_virtualmachine:
  query: >-
    {
      name: .name,
      canonical_facts: {
        id: .id
      },
      facts: {
        device_type: "virtual_machine",
        azure_type: ((.id | capture("/providers/[Mm]icrosoft.(?<resourcetype>[^/]+)/")? | .resourcetype) | ascii_downcase)
      }
    }

Test Locally

# Capture module output
ansible-playbook get_vms.yml -v > /tmp/output.json

# Test jq expression
cat /tmp/output.json | jq '{
  name: .instance.hw_name,
  canonical_facts: { uuid: .instance.hw_uuid },
  facts: { device_type: "virtual_machine" }
}'

See also: Ansible Resource Management: The New Standardized Taxonomy for Collections

FAQ

Is resource reporting required?

No — it's entirely optional for community collections. It adds value but isn't mandatory.

Does this change how modules work?

No — resource reporting is metadata only. It reads module return values; it doesn't change module behavior.

Where can I give feedback?

On the Ansible Forum thread — the team is actively seeking input on use cases, adoption barriers, and taxonomy gaps.

Related Articles

• Ansible Collections Complete Guide
• Ansible AWX Complete Guide
• Ansible VMware Dynamic Inventory Guide