# paloaltonetworks/pan-os-ansible architecture

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

- Interactive diagram: https://gitdiagram.com/paloaltonetworks/pan-os-ansible
- Repository: https://github.com/paloaltonetworks/pan-os-ansible

## Overview

##### Project type and purpose
- This is an Ansible Collection (“paloaltonetworks.panos”)—a plug-in library for Ansible that automates configuration and operational tasks against Palo Alto Networks PAN-OS firewalls (physical or virtual) via the PAN-OS REST/API.
- The README confirms it’s a community/open-source tool packaged as an Ansible Collection (Python 3.9+, Apache-2.0 licensed), tested on Ansible ≥2.15, published to Galaxy and Automation Hub.

##### File structure
Top-level:
- plugins/        ← Ansible plug-ins shipped (modules, httpapi, module_utils, doc_fragments)
- extensions/     ← Extra event-driven automation (EDA) plug-ins & rulebooks
- meta/           ← Collection metadata (galaxy.yml, dependencies, runtime)
- docs/           ← Sphinx-based user/developer documentation sources & templates
- tests/          ← Sanity, unit, integration test suites & fixtures
- .github/        ← CI/CD workflows, release scripts, linting, dependency automation
- pyproject.toml, requirements.txt, Makefile ← Build/test/install configuration

Key patterns:
- Plugin-architecture: modules invoke module_utils; httpapi plugin for persistent API connection; extensions for EDA.
- Separation of concerns: code (plugins/extensions), metadata (meta/galaxy.yml), docs (docs/), tests (/tests), CI (/.github).

##### Additional insights from README
- Core functionality: ~200 panos_* modules, panos_op (generic “op”), panos_facts, panos_commit, etc.
- Uses FQCNs to reference modules.
- Publishing to Ansible Galaxy & Automation Hub, semantic versioning, auto-generated changelog.

##### Essential elements to capture
- All four plugin types (modules, httpapi, module_utils, doc_fragments)
- The extensions/EDA rule engine path
- Metadata/packaging (meta/galaxy.yml) and publishing targets
- Testing workflows and environments
- Documentation generation pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Layer"
        U["Ansible CLI & User"]:::ansible
    end

    subgraph "Orchestration Layer"
        Core["Ansible Engine (Core)"]:::ansible
    end

    U -->|"invokes ansible-playbook"| Core

    subgraph "Collection: paloaltonetworks.panos"
        direction TB
        Loader["Collection Loader"]:::collection
        Modules["Modules"]:::collection
        HTTPAPI["HTTPAPI Plugin"]:::collection
        Utils["Module Utils"]:::collection
        Frags["Doc Fragments"]:::collection
        ExtensionsSub["Extensions / EDA"]:::collection
    end

    Core -->|"loads"| Loader
    Loader --> Modules
    Loader --> HTTPAPI
    Modules --> Utils
    Modules --> Frags
    Loader --> ExtensionsSub
    HTTPAPI -->|"uses utils"| Utils
    Utils --> HTTPAPI

    subgraph "Extensions / EDA"
        direction TB
        EventSrc["Event Sources"]:::collection
        Rulebooks["Rulebooks"]:::collection
        EventSrc --> Rulebooks
        Rulebooks --> Modules
    end

    ExtensionsSub --> EventSrc
    ExtensionsSub --> Rulebooks

    subgraph "External PAN-OS API"
        Firewall["Firewall / Panorama (PAN-OS API)"]:::external
    end

    HTTPAPI -->|"API calls"| Firewall
    Modules -->|"direct XML/REST"| Firewall

    subgraph "Packaging & Metadata"
        GalaxyMeta["galaxy.yml"]:::support
        RuntimeMeta["runtime.yml"]:::support
        ExtMeta["extensions.yml"]:::support
    end

    Loader --> GalaxyMeta
    Loader --> RuntimeMeta
    Loader --> ExtMeta

    subgraph "CI/CD & Docs"
        direction TB
        CI["GitHub Actions CI"]:::support
        Release["Release Scripts"]:::support
        subgraph "Testing"
            HTTPTests["Unit Tests - HTTPAPI"]:::support
            ModuleUtilsTests["Unit Tests - Module Utils"]:::support
            ModuleTests["Unit Tests - Modules"]:::support
            Sanity["Sanity Tests"]:::support
            Integration["Integration Tests"]:::support
        end
        Docs["Sphinx Docs"]:::support
        BuildConfig["Build & Test Config"]:::support
    end

    CI --> Release
    CI --> HTTPTests
    CI --> ModuleUtilsTests
    CI --> ModuleTests
    CI --> Sanity
    CI --> Integration
    CI --> Docs
    CI --> BuildConfig

    click Modules "https://github.com/paloaltonetworks/pan-os-ansible/tree/develop/plugins/modules/"
    click HTTPAPI "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/plugins/httpapi/panos.py"
    click Utils "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/plugins/module_utils/panos.py"
    click Frags "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/plugins/doc_fragments/fragments.py"
    click EventSrc "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/extensions/eda/plugins/event_source/logs.py"
    click Rulebooks "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/extensions/eda/rulebooks/decryption.yaml"
    click GalaxyMeta "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/meta/galaxy.yml"
    click RuntimeMeta "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/meta/runtime.yml"
    click ExtMeta "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/meta/extensions.yml"
    click Docs "https://github.com/paloaltonetworks/pan-os-ansible/tree/develop/docs/source/"
    click CI "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/.github/workflows/ci.yml"
    click Release "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/.github/actions/discover_python_version/action.yml"
    click HTTPTests "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/tests/unit/httpapi/test_panos.py"
    click ModuleUtilsTests "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/tests/unit/plugins/module_utils/test_panos.py"
    click ModuleTests "https://github.com/paloaltonetworks/pan-os-ansible/tree/develop/tests/unit/plugins/modules/"
    click Integration "https://github.com/paloaltonetworks/pan-os-ansible/tree/develop/tests/integration/"
    click Sanity "https://github.com/paloaltonetworks/pan-os-ansible/tree/develop/tests/sanity/"
    click BuildConfig "https://github.com/paloaltonetworks/pan-os-ansible/blob/develop/pyproject.toml, requirements.txt, Makefile"

    classDef ansible fill:#D0E6FF,stroke:#000
    classDef collection fill:#DFFFE0,stroke:#000
    classDef external fill:#FFE0B2,stroke:#000
    classDef support fill:#EEEEEE,stroke:#000
```
