Ansible Network Reports

About

• The Ansible Network Reports Collection provides a platform-agnostic way to gather, generate, persist, and visualize network resource reports. This collection enables users to collect network facts, convert them into structured formats (YAML, JSON), and visualize them as HTML reports using Jinja2 templates.

• This collection includes the following roles:

• gather: Collect comprehensive network device facts for specified resources, including hardware details, using native parsers.

• generate_report: Generate structured HTML reports from previously gathered network facts for visualization and analysis.

• persist: Store gathered network facts in YAML format to local directories or remote SCM repositories, establishing a source of truth (SOT).

• This collection can be used by network administrators, system operators, and IT professionals looking to monitor and manage their network infrastructure through automated reporting.

Included content

Click on the name of a role to view its documentation:

Roles

Name	Description
network.reports.gather	Collect comprehensive network device facts using native parsers.
network.reports.generate_report	Generate structured HTML reports from gathered network facts.
network.reports.persist	Store gathered network facts to local or remote repositories (SCM).

Requirements

• Requires Ansible
• Requires Content Collections
• Testing Requirements
• Users also need to include platform collections as per their requirements. The supported platform collections are:
  • arista.eos >= v11.0.0
  • cisco.ios >= v10.0.0
  • cisco.iosxr >= v11.0.0
  • cisco.nxos >= v10.0.0

Installation

To consume this Validated Content from Automation Hub, the following needs to be added to ansible.cfg:

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/validated/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<SuperSecretToken>

Utilize the current Token, and if the token has expired, obtain the necessary token from the Automation Hub Web UI.

With this configured, simply run the following commands:

ansible-galaxy collection install network.base
ansible-galaxy collection install network.reports

Use Cases

This collection enables users to perform the following reporting tasks:

Gather Network Resource Reports

• The gather role enables users to collect comprehensive network device facts for specified resources (like interfaces, BGP configurations, etc.), including hardware details, using native parsers. These facts form the basis for reports and persisted data.

Generate HTML Reports from Network Facts

• The generate_report role allows users to convert previously gathered network facts into structured HTML reports using Jinja2 templates, providing a visual representation of the network state.

• After the facts have been gathered, the next task is to generate the web report. This task runs locally on the localhost. The output of the network.reports.generate_report task will produce an HTML file summarizing the gathered facts.

Persist Network Data as Source of Truth (SOT)

• The persist role enables users to store gathered network facts (not just reports) in YAML format to local directories or remote SCM (like GitHub/GitLab) repositories. This establishes a version-controlled source of truth for network configuration data, useful for backup, audit, or driving configuration deployment.

Multi-Host Reporting Scenario

This collection is designed to efficiently handle inventories with multiple network devices, even across different network operating systems. The gather role collects facts individually from each targeted host, and the generate_report role consolidates these facts into a single, unified HTML report.

Example Playbook:

1. Example Inventory (inventory.ini)

Define your network devices in an Ansible inventory file. Ensure you specify the correct ansible_network_os for each device, along with connection details.

[network_devices]
ios_router ansible_host=192.168.1.10 ansible_user=cisco ansible_ssh_pass=your_password ansible_connection=ansible.netcommon.network_cli ansible_network_os=cisco.ios.ios
nxos_switch ansible_host=192.168.1.20 ansible_user=admin ansible_ssh_pass=your_password ansible_connection=ansible.netcommon.network_cli ansible_network_os=cisco.nxos.nxos

[network_devices:vars]
 ansible-1 ansible_host=54.190.208.146 ansible_ssh_port=2088 ansible_user=cisco ansible_ssh_password=cisco ansible_connection=ansible.netcommon.network_cli ansible_network_os=cisco.ios.ios
 ansible-2 ansible_host=54.190.208.146 ansible_ssh_port=2024 ansible_user=cisco ansible_ssh_password=cisco ansible_connection=ansible.netcommon.network_cli ansible_network_os=cisco.nxos.nxos

Resulting Report:

The generated HTML report will contain sections or tables summarizing the gathered information (interfaces, L2 interfaces) for both ios_router and nxos_switch. We will be able to see the data from all targeted devices consolidated within that single report file.

Testing

The project uses tox to run ansible-lint and ansible-test sanity. Assuming this repository is checked out in the proper structure, e.g., collections_root/ansible_collections/network/reports, run:

  tox -e ansible-lint
  tox -e py39-sanity

To run integration tests, ensure that your inventory has a network_reports group.

[network_devices]
ios
junos

[ios:vars]
< enter inventory details for IOS devices >

[junos:vars]
< enter inventory details for Junos devices >

  ansible-test network-integration -i /path/to/inventory --python 3.9 [target]

Contributing

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against this repository.

Don't know how to start? Refer to the Ansible community guide!

Want to submit code changes? Take a look at the Quick-start development guide.

We also use the following guidelines:

• Collection review checklist
• Ansible development guide
• Ansible collection development guide

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Release Notes

Release notes are available here.

Related Information

• Developing network resource modules
• Ansible Networking docs
• Ansible Collection Overview
• Ansible Roles overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community Code of Conduct

Licensing

GNU General Public License v3.0 or later.

See LICENSE to see the full text.