DOCSEARCHbyAlgolia
Submit Docs

Infrahub Documentation

repository·stable·Indexed 19 days ago

https://github.com/opsmill/infrahub

Infrahub is a data foundation for modern infrastructure automation that unifies fragmented data into a validated, version-controlled graph. It provides a datastore to organize and control infrastructure data through schema-enforced workflows. The ecosystem includes the infrahub-server, a Python SDK, VS Code extension, Helm charts for Kubernetes deployment, and integrations for Ansible and Nornir.

Tokens
475.1K
Snippets
1.1K
Records
2K
Agent score
64%

What's inside Infrahub

  1. What is Infrahub

    stable

    Infrahub is a graph-based infrastructure data management platform designed for network, data center, and cloud automation. It unifies infrastructure data with business logic, providing built-in version control (branching, diffing, merging), CI workflows, peer review, and API access.

    Core pillars include:

    • A Flexible Schema: An extensible model of infrastructure objects and their relationships.
    • Version Control: Native integration within the graph database for data branching and merging.
    • Unified Storage: Combines a graph database with Git to manage both data and code.

  2. Overview of Log Forwarding

    stable

    Log forwarding is an Enterprise Edition feature that streams audit events and application logs to external systems using the syslog protocol. It is designed for compliance (SOC 2, PCI-DSS), security monitoring (SIEM integration), and operational visibility.

    Key Distinctions

    • vs. Activity Log: The activity log is for in-app browsing; log forwarding is for external long-term retention and alerting.
    • vs. Webhooks: Webhooks use HTTP callbacks for custom payloads; log forwarding uses the syslog protocol for standardized ingestion.
    • vs. Community Edition: In the Community Edition, log forwarding is a no-op implementation that does not transmit messages.

  3. Overview of the Infrahub testing framework

    stable

    Infrahub provides a YAML-based testing framework to ensure that Transformations and checks work as intended and remain consistent across version updates. While the framework is powered by pytest, users do not need to write any Python code; instead, they define tests in YAML files.

    Test Types

    • Smoke tests: Validate that resources are defined appropriately, can be parsed, and are free of syntax errors.
    • Unit tests: Validate that resources can be rendered or run, often using specific input and output values to assert expected results.
    • Integration tests: Validate that resources work as intended by testing them against a live Infrahub instance.

  5. Understand the Graph Traversal Package Structure

    stable

    Graph traversal functionality has been moved from infrahub.core.query to a dedicated top-level package: infrahub.graph_traversal.

    Key components of this package include:

    • Queries: PathTraversalQuery (for finding paths) and ReachableNodesQuery (for finding reachable nodes).
    • Results: Public dataclasses PathData, PathHopData, and PathNodeData used to represent traversal results.
    • Planning: An internal planning/ sub-package containing the SchemaPlanner, which generates a Plan based on the schema without generating Cypher directly.
    • GraphQL Resolvers: Located in backend/infrahub/graphql/queries/, these orchestrate the process by using the SchemaPlanner to build a plan and then instantiating the appropriate Query class.

    Note: The old paths infrahub.core.query.path and infrahub.core.query.reachable have been deleted. All imports must be updated to use infrahub.graph_traversal.

    # Correct import pattern
from infrahub.graph_traversal.path import PathTraversalQuery
from infrahub.graph_traversal.results import PathData
from infrahub.graph_traversal.planning import SchemaPlanner

  6. Project Structure for the GraphQL Error Catalogue feature

    stable

    The GraphQL Error Catalogue feature is implemented across the backend, frontend, and documentation layers.

    Backend (backend/infrahub/)

    • errors/: A new package containing the error registry (catalogue.py), Pydantic payload models (payloads.py), catalogue-aware exceptions (exceptions.py), and the JSON Schema exporter (export.py).
    • api/exception_handlers.py: Modified to emit GraphQL-shaped errors for /graphql routes.
    • graphql/: Includes a new error_formatter.py which wraps graphql-core to populate extensions.{code, http_status, data} in responses.
    • log_forwarding/: Passes catalogue codes through structured logs.

    Frontend (frontend/app/src/)

    • shared/api/errors/: Contains catalogue.generated.ts (generated TypeScript types from catalogue.json) and index.ts (hand-written re-exports).
    • shared/api/graphql/graphqlClientApollo.tsx: Modified to switch logic based on the error string code.

    Tooling and Artifacts

    • schema/error-catalogue.json: The committed machine-readable schema used as the cross-repo contract.
    • tasks/: New Invoke tasks for regenerate-error-bindings and check-error-bindings (frontend) and export-error-catalogue (backend).
    • docs/reference/error-catalogue/: Automatically generated documentation page.

  7. Using Infrahub: Schemas, Git, and Resource Management

    stable

    Infrahub provides several core workflows for managing infrastructure data:

    • Load Schemas: Manage and load schemas into the system.
    • Git Repository Integration: Connect your Git repositories to Infrahub to synchronize data.
    • Resource Manager: Organize and handle resources within the Infrahub environment.

  8. Compare Infrahub Community vs Enterprise editions

    stable

    Infrahub uses an open-core model with two editions: Community Edition (open source under Apache 2.0) and Enterprise Edition (commercial license with extended capabilities). Both editions share identical core infrastructure data management features, including schema modeling, version control, and artifact generation. The primary differences lie in scalability, advanced security/authentication, and support models.

    Core Feature Parity

    Both editions support:

    • Schema and Data Modeling: Custom schema creation, flexible relationships, schema versioning, and data validation.
    • Version Control and Branching: Git-like branching, peer review workflows, conflict resolution, and immutable audit trails.
    • Artifact Generation: Template-based configuration using Jinja2 or Python Transformations, and extensible Generators.

    Key Differences

    FeatureCommunity EditionEnterprise Edition
    Scale CapacityUp to ~1,000 devices10,000+ devices
    Database ConcurrencySingle-core Neo4j (limited by single-core performance)Multi-core Neo4j (parallel query/merge execution)
    ScalingVertical scalingHorizontal scaling & High Availability (clustering)
    AuthenticationLocal accounts, SSO (OAuth2, OIDC)LDAP (AD/OpenLDAP) with nested-group support
    AuthorizationBasic RBACAdvanced workflow-based approvals & change management
    ObservabilityStandard logsLog forwarding to SIEM via syslog
    SupportCommunity (Discord/GitHub), no SLASLA-backed professional support, 24/7 options

    Choosing an Edition

    • Choose Community if: You are a small-to-medium organization (<1,000 devices), running PoCs, or require full source code transparency under Apache 2.0.
    • Choose Enterprise if: You manage large-scale (10,000+ devices) or mission-critical infrastructure, require LDAP/AD integration, need guaranteed SLAs, or require high-availability clustering.

  9. Choose an authentication method for Infrahub

    stable

    Infrahub supports several authentication methods depending on your environment and organizational needs:

    • Local User Store: Built-in user management where accounts are created and managed directly within Infrahub. Best for standalone deployments or testing/development environments.
    • Single Sign-On (SSO): Integrates with external identity providers (e.g., Microsoft Entra ID, Okta, Google Workspace) using OAuth 2.0 or OpenID Connect (OIDC). Users are automatically provisioned in the local store upon first sign-in. OIDC is recommended over OAuth 2.0 for SSO as it provides standardized identity claims.
    • LDAP (Enterprise Edition): Authenticates users against existing directories like Active Directory or OpenLDAP. Supports LDAPS and STARTTLS for encrypted connections and maps directory groups to local groups.
    • Anonymous Access: By default, Infrahub allows read-only anonymous access. This should be disabled for production environments.

  10. Explore Git integration and branching concepts

    stable

    For a deeper understanding of how Infrahub interacts with Git, refer to the following documentation areas:

    • Git Repository Architecture: Learn about repository integration concepts and how Infrahub manages external Git data.
    • Connecting Repositories: Follow the step-by-step guide to set up and connect your external Git repositories.
    • Branching Models: Understand branch isolation, hierarchy, and the specific workflows supported by Infrahub.
    • Configuration Reference: Access the complete list of configuration options, including detailed Git settings and synchronization parameters.

  11. Understand the Infrahub Backend Tech Stack

    stable

    The Infrahub backend is built on an async-first architecture designed for high-performance graph operations and versioned data management. The core stack includes:

    • Framework: FastAPI (async-first)
    • Database: Neo4j (graph database)
    • API: GraphQL (primary interface) and REST
    • Language/Validation: Python 3 with Pydantic

  12. Explore the Infrahub ecosystem

    stable

    OpsMill provides several officially supported projects to help you develop, run, and integrate Infrahub into your automation stack.

    Development Tools

    • infrahub-sdk-python: Provides the Python SDK and the infrahubctl CLI for building integrations and managing Infrahub via code.
    • infrahub-vscode: A VS Code extension featuring schema validation, GraphQL query support, and schema visualization.
    • schema-library: A collection of reusable schemas for common infrastructure patterns.
    • infrahub-mcp: An MCP server that exposes Infrahub data to AI agents like Claude and Cursor.
    • infrahub-skills: AI skills that provide coding assistants with knowledge of Infrahub conventions and data models.

    Production & Operations

    • infrahub-helm: Helm charts for deploying Infrahub on Kubernetes.
    • infrahub-backup: A CLI tool for backing up and restoring Infrahub instances.

    Integrations

    • infrahub-ansible: An Ansible Collection to use Infrahub as the source of truth for playbooks.
    • nornir-infrahub: A Nornir inventory plugin for Python-based network automation.
    • infrahub-sync: A tool to federate data from external systems like Netbox, Nautobot, and IP Fabric into Infrahub.