# zjleblanc/ansible-network-mgmt architecture

> Architecture diagram of the GitHub repository zjleblanc/ansible-network-mgmt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zjleblanc/ansible-network-mgmt
- Repository: https://github.com/zjleblanc/ansible-network-mgmt

## Overview

##### Project type and purpose
- This is an open‐source network automation tool built with Ansible.
- Its purpose is to manage/configure network devices, generate reports, and integrate with external services (AWS, Dynatrace SNMP, ServiceNow CMDB, Slack).

##### File structure
- Top‐level “playbooks”: core orchestration scripts (compliance reports, interactive reports, Dynatrace→SNOW, configs).
- “collections” & “roles”: reusable code units (modules, tasks, defaults, meta, filters).
- “demos”, “workshop-addons”, “summit-connect”: specialized examples, labs, and network-as-code patterns.
- “inventories”: static & dynamic host definitions (AWS EC2 dynamic inventory plugin).
- “filter_plugins”: Python logic for custom data transformations.
- “vars”, “templates”, “tasks”: variable files and Jinja2 templates used by playbooks and roles.

##### README for insights
- Confirms major playbooks and their use cases.
- Mentions external integrations: Dynatrace SNMP, ServiceNow CMDB, AWS EC2 inventory.
- Notes troubleshooting hints around SSH (Paramiko) and device authentication.

##### Main components
a. Control Plane (Ansible Engine running on a Control Node)
– Playbooks directory
– Roles & Collections (with tasks, defaults, meta)
– Filter_plugins & custom modules
– Templates & variable files
– Dynamic/Static Inventories
b. External Systems & Services
– Network Devices (routers, switches, firewalls) accessed via SSH/Paramiko
– AWS EC2 API for dynamic inventory
– Dynatrace SNMP feed
– ServiceNow CMDB REST API
– Slack Webhook for notifications
c. Optional Workshop & Demo Layers
– Demos (panos examples)
– Workshop-addons (e.g. EVE-NG integrations)
– Summit-connect (network-as-code definitions & playbooks)

##### Relationships and interactions
- The Control Plane reads inventories and playbooks →
triggers connection plugins →
pushes modules & templates via SSH to Network Devices.
- When running Dynatrace→SNOW playbooks, Ansible fetches SNMP data, transforms it, then calls ServiceNow API to populate CMDB.
- The AWS EC2 dynamic inventory plugin queries AWS API at runtime to discover hosts.
- Slack notifications are sent via HTTP to Slack Webhooks at the end of playbook runs.

##### Architectural patterns & design principles
- Separation of concerns: playbooks orchestrate, roles/collections encapsulate reusable logic, filter_plugins handle data transformation.
- Declarative, idempotent tasks (Ansible’s core principle).
- Modular inventory (static files under “inventories” + dynamic AWS plugin).
- Extensibility: new devices or services can be added by dropping in new roles/collections or filter_plugins.

##### Technologies & frameworks
- Ansible (Engine, CLI, YAML playbooks)
- Python (filter_plugins, modules)
- Jinja2 (templates)
- SSH/Paramiko (connections)
- REST APIs (ServiceNow, Slack, AWS)
- SNMP (Dynatrace integration)

##### Essential elements checklist
[ ] Ansible Control Node with sub‐components (playbooks, roles, collections, filters, inventory)
[ ] Static Inventory files & AWS dynamic inventory plugin
[ ] Connection path to Network Devices via SSH/Paramiko
[ ] Integration paths to Dynatrace SNMP, ServiceNow API, Slack Webhook
[ ] Demo/workshop layers (optional, can be collapsed under “Examples”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Ansible Control Node" 
        direction TB
        CP["Ansible Control Plane"]:::control
        subgraph "Playbooks" 
            direction TB
            PB1["compliance-report.yml"]:::code
            PB2["interactive_report.yml"]:::code
            PB3["dynatrace_snow_cmdb.yml"]:::code
            PB4["network_config.yml"]:::code
            PB5["configs/"]:::code
        end
        subgraph "Roles & Collections"
            direction TB
            R1["roles/"]:::code
            R2["collections/mgmt/snow_configuration/"]:::code
        end
        subgraph "Filter Plugins"
            direction TB
            F1["playbooks/filter_plugins/demo.py"]:::code
            F2["demos/panos/filter_plugins/common.py"]:::code
        end
        subgraph "Templates & Vars"
            direction TB
            T1["templates/compliance_report.html.j2"]:::code
            T2["templates/interactive_report.html.j2"]:::code
            V1["vars/cisco_facts.json"]:::code
            V2["vars/mock_network_data.yml"]:::code
            T3["roles/git/templates/CHANGELOG.md.j2"]:::code
        end
        subgraph "Inventory"
            direction TB
            I1["inventories/example-inventory/hosts"]:::code
            I2["demos/panos/inventory/amazon.aws.aws_ec2.yml"]:::code
            I3["demos/panos/inventory/group_vars/"]:::code
        end
        CP --> PB1
        CP --> PB2
        CP --> PB3
        CP --> PB4
        CP --> PB5
        CP --> R1
        CP --> R2
        CP --> F1
        CP --> F2
        CP --> T1
        CP --> T2
        CP --> V1
        CP --> V2
        CP --> T3
        CP --> I1
        CP --> I2
        CP --> I3
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ND["Network Devices (SSH/Paramiko)"]:::device
        AWS["AWS EC2 API"]:::external
        DT["Dynatrace SNMP"]:::external
        SNOW["ServiceNow CMDB API"]:::external
        SLACK["Slack Webhook"]:::external
    end

    %% Flows
    CP -->|"SSH/Paramiko"| ND
    CP -->|"inventory lookup"| AWS
    CP -->|"SNMP poll"| DT
    CP -->|"REST call"| SNOW
    CP -->|"HTTP notify"| SLACK

    %% Examples Layer
    subgraph "Examples & Workshops"
        direction TB
        EX1["demos/panos/"]:::example
        EX2["workshop-addons/"]:::example
        EX3["summit-connect/"]:::example
    end
    CP --> EX1
    CP --> EX2
    CP --> EX3

    %% Click Events
    click PB1 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/compliance-report.yml"
    click PB2 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/interactive_report.yml"
    click PB3 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/dynatrace_snow_cmdb.yml"
    click PB4 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/network_config.yml"
    click PB5 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/playbooks/configs/"
    click R1 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/roles/"
    click R2 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/collections/ansible_collections/mgmt/snow_configuration/"
    click F1 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/filter_plugins/demo.py"
    click F2 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/demos/panos/filter_plugins/common.py"
    click T1 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/templates/compliance_report.html.j2"
    click T2 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/playbooks/templates/interactive_report.html.j2"
    click V1 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/vars/cisco_facts.json"
    click V2 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/vars/mock_network_data.yml"
    click T3 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/roles/git/templates/CHANGELOG.md.j2"
    click I1 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/inventories/example-inventory/hosts"
    click I2 "https://github.com/zjleblanc/ansible-network-mgmt/blob/master/demos/panos/inventory/amazon.aws.aws_ec2.yml"
    click I3 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/demos/panos/inventory/group_vars/"
    click EX1 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/demos/panos/"
    click EX2 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/workshop-addons/"
    click EX3 "https://github.com/zjleblanc/ansible-network-mgmt/tree/master/summit-connect/"

    %% Styles
    classDef control fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef code fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef device fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef example fill:#E1F5FE,stroke:#0288D1,color:#01579B;
```
