# Infrahub by OpsMill - Documentation > Infrahub by OpsMill - the modern infrastructure data management platform. Infrahub is the open-source product built by OpsMill (https://opsmill.com). - [Infrahub by OpsMill - Documentation](/index.md) ## labs Hands-on Infrahub labs on Instruqt: guided learning tracks, standalone OpsMill labs, and labs from partners and the community. - [Labs](/labs.md): Hands-on Infrahub labs on Instruqt: guided learning tracks, standalone OpsMill labs, and labs from partners and the community. ## search - [Search the documentation](/search.md) ## ansible Collection version 1.8.3 - [opsmill.infrahub Ansible collection](/ansible.md): Collection version 1.8.3 ### guides - [Manage branches in Infrahub](/ansible/guides/branch.md): Infrahub lets you manage branches directly via the opsmill.infrahub.branch module. With this module you can create, confirm, and delete branches—using the state parameter to control the desired operation. - [Use Infrahub for Ansible dynamic inventory](/ansible/guides/dynamic-inventory.md): Overview - [Install opsmill.infrahub Ansible collection](/ansible/guides/installation.md): This guide assumes you have basic knowledge of Ansible and its ecosystem. For more information on using Ansible, please refer to the official Ansible documentation. - [Create nodes in Infrahub](/ansible/guides/node.md): Overview - [Retrieve data from Infrahub](/ansible/guides/query-and-lookup.md): Overview ### references - [Modules modules](/ansible/references/plugins/artifact_fetch_module.md): Fetch the content of an artifact from Infrahub - [Modules modules](/ansible/references/plugins/artifact_generate_module.md): Trigger artifact regeneration in Infrahub - [Modules modules](/ansible/references/plugins/branch_module.md): Creates, Updates or Deletes a branch in Infrahub - [Inventory inventory](/ansible/references/plugins/inventory_inventory.md): Infrahub inventory source (using GraphQL) - [Lookup lookup](/ansible/references/plugins/lookup_lookup.md): Queries and returns elements from Infrahub (using GraphQL) - [Modules modules](/ansible/references/plugins/node_module.md): Creates, Updates or Deletes a node in Infrahub - [Modules modules](/ansible/references/plugins/object_file_fetch_module.md): Fetch file content from a CoreFileObject node in Infrahub - [Modules modules](/ansible/references/plugins/query_graphql_module.md): Queries and returns elements from Infrahub GraphQL API - [Modules modules](/ansible/references/plugins/schema_module.md): Load, check, or export schemas in Infrahub - [Overview](/ansible/references/roles/install.md): The Infrahub Installation Role in the OpsMill Infrahub Ansible Collection allows you to install and configure Infrahub using Docker and systemd. ## arista-avd A reference design that models Arista datacenter fabrics in Infrahub and generates EOS configurations via the AVD pipeline. - [Arista AVD Reference Design](/arista-avd.md): A reference design that models Arista datacenter fabrics in Infrahub and generates EOS configurations via the AVD pipeline. ### cloudvision The repository validates generated EOS configurations in CloudVision during - [CloudVision validation](/arista-avd/cloudvision.md): The repository validates generated EOS configurations in CloudVision during ### containerlab The ContainerLab Topology artifact — how a fabric becomes a containerlab topology file, and how to deploy it. - [ContainerLab](/arista-avd/containerlab.md): The ContainerLab Topology artifact — how a fabric becomes a containerlab topology file, and how to deploy it. ### developer-guide How the Infrahub Arista AVD solution is built and how to extend it. - [Developer guide](/arista-avd/developer-guide.md): How the Infrahub Arista AVD solution is built and how to extend it. - [Architecture overview](/arista-avd/developer-guide/architecture.md): System architecture and data flow for the Infrahub Arista AVD solution. - [AvdArtifact & file storage](/arista-avd/developer-guide/avd/artifacts.md): The AvdArtifact node, its child AvdHostvarFile and AvdStructuredConfigFile nodes, and the end-to-end artifact definitions. - [Debugging the pipeline](/arista-avd/developer-guide/avd/debugging.md): Inspect intermediate files, force regeneration, and isolate a single generator or transform. - [Extending the pipeline](/arista-avd/developer-guide/avd/extending.md): Worked examples for adding a device role, adding a transform output, or adding a hostvar field. - [Hostvars reference](/arista-avd/developer-guide/avd/hostvars.md): The PyAVD-compatible hostvars structure built per device role by Phase 1 of the pipeline. - [AVD pipeline overview](/arista-avd/developer-guide/avd/overview.md): The two-phase AVD generator pipeline, the PyAVD version pinned, and the shape of the data flow. - [Role mapping](/arista-avd/developer-guide/avd/role-mapping.md): Infrahub device roles mapped to PyAVD device types. - [AVD transforms](/arista-avd/developer-guide/avd/transforms.md): The three Python transforms that render EOS configs and AVD documentation from stored data. - [Checks](/arista-avd/developer-guide/checks.md): Python checks that run in the proposed-change pipeline — CloudVision configuration validation and its workspace lifecycle, and fabric pool validation. - [Concepts](/arista-avd/developer-guide/concepts.md): The core Infrahub terms this reference design relies on, for readers new to the platform. - [Generators](/arista-avd/developer-guide/generators.md): The infrastructure generators that create devices, interfaces, cabling, and AVD inputs. - [Schemas](/arista-avd/developer-guide/schemas.md): All Infrahub schema definitions in this solution. - [Transforms](/arista-avd/developer-guide/transforms.md): Data transforms and artifact generation — how Infrahub data becomes configs, docs, and CSVs. ### how-to - [Add a network segment](/arista-avd/how-to/add-network-segment.md): Create a VRF, VLAN, and SVI on a fabric using the service portal. - [Add a server](/arista-avd/how-to/add-server.md): Provision a physical server into a compute rack and trigger the AVD cascade. - [Create a tenant](/arista-avd/how-to/create-tenant.md): Create an EVPN tenant with a MAC VRF VNI base allocation for one or more fabrics. - [Migrate Semaphore storage](/arista-avd/how-to/migrate-semaphore-storage.md): Preserve Semaphore's SQLite database and configuration when moving to persistent Docker volumes. - [Regenerate a fabric](/arista-avd/how-to/regenerate-fabric.md): Use the Fabric Design page to inspect and re-run the generator chain for a fabric. - [Run ANTA after deployment](/arista-avd/how-to/run-anta-after-deployment.md): Validate one deployed fabric from its merged Infrahub ANTA catalogs by using Semaphore. - [Upgrade AVD version](/arista-avd/how-to/upgrade-avd-version.md): Move to a newer PyAVD version and validate the result on a branch before production. ### provision-first-fabric Run the generator chain end-to-end on Fabric-L3LS-MultiPod-A and reach rendered AVD artifacts. - [Provision your first fabric](/arista-avd/provision-first-fabric.md): Run the generator chain end-to-end on Fabric-L3LS-MultiPod-A and reach rendered AVD artifacts. ### quick-start Install dependencies, bring the stack up, and load seed data. - [Quick start](/arista-avd/quick-start.md): Install dependencies, bring the stack up, and load seed data. ### release-notes Releases of the Infrahub Arista AVD reference design. - [Release notes](/arista-avd/release-notes.md): Releases of the Infrahub Arista AVD reference design. ### supported-capabilities The AVD scenarios, services, artifacts, and workflows this Arista AVD reference design supports today. - [Supported capabilities](/arista-avd/supported-capabilities.md): The AVD scenarios, services, artifacts, and workflows this Arista AVD reference design supports today. ### troubleshooting Diagnose and fix the most frequent failures — stack health, generator order, seed data, artifacts. - [Common issues](/arista-avd/troubleshooting.md): Diagnose and fix the most frequent failures — stack health, generator order, seed data, artifacts. ### viewing-artifacts Find, preview, and download the AVD EOS configs and fabric/device documentation. - [Viewing artifacts](/arista-avd/viewing-artifacts.md): Find, preview, and download the AVD EOS configs and fabric/device documentation. ## backup The Infrahub Ops CLI provides command-line tools for operating and maintaining an Infrahub deployment: - [Infrahub Backup](/backup.md): The Infrahub Ops CLI provides command-line tools for operating and maintaining an Infrahub deployment: ### backup Use Infrahub Backup to create and restore verifiable recovery points for an Infrahub deployment. Run it as a CLI against Docker Compose, or as a Helm chart on Kubernetes, to capture the graph database and the task-manager database as a single archive you can restore from later. Artifact storage lives outside those databases, so you snapshot it as a separate, coordinated step to keep a recovery complete. - [Infrahub Backup](/backup/backup.md): Use Infrahub Backup to create and restore verifiable recovery points for an Infrahub deployment. Run it as a CLI against Docker Compose, or as a Helm chart on Kubernetes, to capture the graph database and the task-manager database as a single archive you can restore from later. Artifact storage lives outside those databases, so you snapshot it as a separate, coordinated step to keep a recovery complete. - [Back up your Infrahub instance](/backup/backup/create.md): Create a comprehensive backup of an Infrahub instance on Docker Compose. Follow these steps to protect your data before an upgrade or to establish a disaster-recovery routine. - [Install Infrahub Backup](/backup/backup/install.md): Install the infrahub-backup CLI on a Docker Compose or Kubernetes deployment, or build it from source. - [Back up Infrahub on Kubernetes](/backup/backup/kubernetes-backup.md): Back up an Infrahub instance running on Kubernetes with the infrahub-backup Helm chart. If you deploy Infrahub through GitOps tools like ArgoCD or Flux without direct kubectl access, manage backups declaratively through Helm values. - [Restore Infrahub on Kubernetes](/backup/backup/kubernetes-restore.md): Restore an Infrahub instance on Kubernetes from a backup stored in S3-compatible storage. The restore runs as a Kubernetes Job through the same infrahub-backup Helm chart. - [Refresh an environment on a schedule](/backup/backup/kubernetes-scheduled-restore.md): Run the restore CronJob in the infrahub-backup Helm chart to keep a staging or demo deployment on the newest backup another environment produces. Each run restores whichever archive is newest under the source bucket and prefix, so the target release never names a filename and the schedule keeps working as new backups land. - [Restore from a backup](/backup/backup/restore.md): Restore an Infrahub instance from a backup file on Docker Compose. Follow these steps to recover from data loss, roll back a change, or move to new infrastructure. - [Manage backup retention](/backup/backup/retention.md): A backup schedule that never deletes anything eventually fills its disk or its bucket, and the failure usually surfaces as a failed backup rather than as a full volume. A retention policy bounds that growth: you declare how many recovery points to keep, and infrahub-backup deletes the rest. ### collect Use Infrahub Collect to gather everything OpsMill support needs to investigate an issue — service logs, diagnostic status, configuration, and metrics — into a single local archive. Run it when support asks for logs, or to attach diagnostic data to a support request. The same command produces the same bundle on Docker Compose and Kubernetes. - [Infrahub Collect](/backup/collect.md): Use Infrahub Collect to gather everything OpsMill support needs to investigate an issue — service logs, diagnostic status, configuration, and metrics — into a single local archive. Run it when support asks for logs, or to attach diagnostic data to a support request. The same command produces the same bundle on Docker Compose and Kubernetes. - [Collect a troubleshooting bundle](/backup/collect/create.md): Collect a troubleshooting bundle from an Infrahub deployment and share it with OpsMill support. Collection is read-only and safe to run at any time, including while the instance is degraded. See Infrahub Collect for what a bundle contains and how secrets are masked. The same command produces the same bundle on Docker Compose and Kubernetes. - [Install Infrahub Collect](/backup/collect/install.md): Install the infrahub-collect CLI. One binary collects from both Docker Compose and Kubernetes deployments; on Kubernetes it runs from your workstation or a CI runner and reaches the cluster through kubectl. ### reference - [CLI command reference](/backup/reference/commands.md): Complete reference for the Infrahub Ops CLI tools (infrahub-backup, infrahub-collect), their commands, flags, and options. - [Configuration reference](/backup/reference/configuration.md): Complete reference for configuring the Infrahub Ops CLI tools through environment variables and runtime flags. ### release-notes Releases and changes to infrahub-backup. - [Release notes](/backup/release-notes.md): Releases and changes to infrahub-backup. ### self-update Update the infrahub-backup and infrahub-collect binaries to a newer release with the built-in update command. The command downloads the matching release, verifies its checksum, and replaces the binary in place. - [Update the CLI](/backup/self-update.md): Update the infrahub-backup and infrahub-collect binaries to a newer release with the built-in update command. The command downloads the matching release, verifies its checksum, and replaces the binary in place. ### tutorials - [Get started with Infrahub Backup](/backup/tutorials/getting-started.md): By the end of this tutorial you will have installed infrahub-backup, detected your deployment environment, created and verified your first backup — including a snapshot of artifact storage — and restored from it. That is the core maintenance workflow for an Infrahub instance on Docker Compose. ## demo-dc Welcome to the Infrahub demo-dc example. This repository showcases how Infrahub serves as an infrastructure data management platform for managing modern network infrastructure with design-driven automation. It demonstrates Infrahub's core capabilities including: - [Infrahub demo-dc example](/demo-dc.md): Welcome to the Infrahub demo-dc example. This repository showcases how Infrahub serves as an infrastructure data management platform for managing modern network infrastructure with design-driven automation. It demonstrates Infrahub's core capabilities including: ### cloud-management This tutorial shows an example of cloud resource management schema, which provides a vendor-agnostic way to model cloud infrastructure across AWS, GCP, and Azure. You'll load sample cloud data and explore how Infrahub can serve as a unified inventory for multi-cloud environments. - [Cloud resource management](/demo-dc/cloud-management.md): This tutorial shows an example of cloud resource management schema, which provides a vendor-agnostic way to model cloud infrastructure across AWS, GCP, and Azure. You'll load sample cloud data and explore how Infrahub can serve as a unified inventory for multi-cloud environments. ### concepts This document explains the architectural patterns, design decisions, and core Infrahub concepts demonstrated in this demo. Read this to understand the "why" behind design-driven automation, composable topologies, generators, and the overall approach to infrastructure management. - [Understanding the concepts](/demo-dc/concepts.md): This document explains the architectural patterns, design decisions, and core Infrahub concepts demonstrated in this demo. Read this to understand the "why" behind design-driven automation, composable topologies, generators, and the overall approach to infrastructure management. ### containerlab-deployment This tutorial walks you through deploying a virtual data center topology using Containerlab. You'll take the configurations generated by Infrahub and spin up a fully functional network lab with Arista cEOS virtual switches. - [Deploy a virtual lab with Containerlab](/demo-dc/containerlab-deployment.md): This tutorial walks you through deploying a virtual data center topology using Containerlab. You'll take the configurations generated by Infrahub and spin up a fully functional network lab with Arista cEOS virtual switches. ### developer-guide This guide provides a technical deep-dive into how the Infrahub demo works under the hood. Use this when you want to extend functionality, troubleshoot issues, customize the demo, or understand implementation details. - [Developer guide](/demo-dc/developer-guide.md): This guide provides a technical deep-dive into how the Infrahub demo works under the hood. Use this when you want to extend functionality, troubleshoot issues, customize the demo, or understand implementation details. ### enterprise This guide explains how to configure the demo environment to use Infrahub Enterprise edition instead of the Community edition. Enterprise edition provides additional features including increased performance, enhanced security, and enterprise support. - [Using Infrahub Enterprise](/demo-dc/enterprise.md): This guide explains how to configure the demo environment to use Infrahub Enterprise edition instead of the Community edition. Enterprise edition provides additional features including increased performance, enhanced security, and enterprise support. ### install This guide walks you through setting up the Infrahub demo environment on your local system. By the end, you'll have a fully functional Infrahub instance with pre-loaded schemas, data, and generators ready to explore. - [Installation guide](/demo-dc/install.md): This guide walks you through setting up the Infrahub demo environment on your local system. By the end, you'll have a fully functional Infrahub instance with pre-loaded schemas, data, and generators ready to explore. ### security-management This tutorial walks you through Infrahub's security management capabilities. You'll explore how security policies are modeled as structured data, how they relate to firewalls, and how Infrahub transforms security policy objects into vendor-specific firewall configurations. - [Working with security management](/demo-dc/security-management.md): This tutorial walks you through Infrahub's security management capabilities. You'll explore how security policies are modeled as structured data, how they relate to firewalls, and how Infrahub transforms security policy objects into vendor-specific firewall configurations. ### service-catalog This tutorial walks you through using Infrahub's Service Catalog web interface to manage data center and colocation center deployments. The Service Catalog provides a user-friendly web application built with Streamlit that simplifies infrastructure provisioning by automating branch creation, data loading, and generator execution. - [Using the service catalog](/demo-dc/service-catalog.md): This tutorial walks you through using Infrahub's Service Catalog web interface to manage data center and colocation center deployments. The Service Catalog provides a user-friendly web application built with Streamlit that simplifies infrastructure provisioning by automating branch creation, data loading, and generator execution. ### user-walkthrough This tutorial guides you through the complete workflow of creating a data center topology using Infrahub's design-driven automation. You'll create a new branch, load a topology design, run a generator to create infrastructure, review the changes, and merge them to the main branch. - [User walkthrough](/demo-dc/user-walkthrough.md): This tutorial guides you through the complete workflow of creating a data center topology using Infrahub's design-driven automation. You'll create a new branch, load a topology design, run a generator to create infrastructure, review the changes, and merge them to the main branch. ### virtualization This tutorial shows how the demo models a virtualization layer on top of the data center fabric: hypervisor clusters, the physical hosts that form them, and the virtual machines running on those hosts. You'll load the demo data, follow what the generators do with it, and create a VM of your own through the Service Catalog. - [Virtual machine management](/demo-dc/virtualization.md): This tutorial shows how the demo models a virtualization layer on top of the data center fabric: hypervisor clusters, the physical hosts that form them, and the virtual machines running on those hosts. You'll load the demo data, follow what the generators do with it, and create a VM of your own through the Service Catalog. ## demo-otn This demo models a European research-network optical core in Infrahub, down to - [Infrahub OTN demo](/demo-otn.md): This demo models a European research-network optical core in Infrahub, down to ### ai-payloads Distributed training traffic runs on this network in operation, so the model - [AI and HPC payloads](/demo-otn/ai-payloads.md): Distributed training traffic runs on this network in operation, so the model ### client-mapping A customer hands over an Ethernet port, an SDH circuit, a 2 Mbps tributary or an - [Client mapping](/demo-otn/client-mapping.md): A customer hands over an Ethernet port, an SDH circuit, a 2 Mbps tributary or an ### concepts The plant layer is four kinds: a fiber span, an optical multiplex section, a - [Optical plant concepts](/demo-otn/concepts.md): The plant layer is four kinds: a fiber span, an optical multiplex section, a ### demo-guide Nine scenarios against the loaded GÉANT dataset. Every number on the three - [Demo guide](/demo-otn/demo-guide.md): Nine scenarios against the loaded GÉANT dataset. Every number on the three ### developer-guide How this repository is laid out, how to change it, and how to check that you did - [Developer guide](/demo-otn/developer-guide.md): How this repository is laid out, how to change it, and how to check that you did ### installation-setup Prerequisites - [Install and load the demo](/demo-otn/installation-setup.md): Prerequisites ### link-budget A wavelength either closes or it does not. The link budget is the arithmetic - [Link budget](/demo-otn/link-budget.md): A wavelength either closes or it does not. The link budget is the arithmetic ### loadable-scenarios Three pairs of scenarios and six singles, one task each, then the runbook that - [Loadable scenarios and the runbook](/demo-otn/loadable-scenarios.md): Three pairs of scenarios and six singles, one task each, then the runbook that ### network-map The fourteen PoPs of the modelled European optical core, with the 21 multiplex sections between them coloured by OSNR margin. Paris to Madrid is red, Frankfurt to Milan carries a 4,134 GHz occupancy chip, and Vienna to Milan is marked as Raman pumped and asymmetric. - [Network map](/demo-otn/network-map.md): The fourteen PoPs of the modelled European optical core, with the 21 multiplex sections between them coloured by OSNR margin. Paris to Madrid is red, Frankfurt to Milan carries a 4,134 GHz occupancy chip, and Vienna to Milan is marked as Raman pumped and asymmetric. ### odu-map Which of the two maps you are looking at - [ODU map](/demo-otn/odu-map.md): Which of the two maps you are looking at ### provisioning-scenarios The two scenarios that write. One provisions a service and shows what the route - [Provisioning scenarios](/demo-otn/provisioning-scenarios.md): The two scenarios that write. One provisions a service and shows what the route ### quickstart Go from a fresh clone to a proposed change Infrahub will not merge. You - [Quick start](/demo-otn/quickstart.md): Go from a fresh clone to a proposed change Infrahub will not merge. You ### reporting-scenarios The six scenarios that read rather than write, and the two maps every PoP - [Reporting scenarios](/demo-otn/reporting-scenarios.md): The six scenarios that read rather than write, and the two maps every PoP ### schema-reference The OTN schema is 50 kinds across eight files in schemas/. Eight - [Schema reference](/demo-otn/schema-reference.md): The OTN schema is 50 kinds across eight files in schemas/. Eight ### spectral-model A wavelength occupies a width of spectrum, not a channel number. It is centred on - [Spectral model](/demo-otn/spectral-model.md): A wavelength occupies a width of spectrum, not a channel number. It is centred on ### what-this-shows Two readers land on this page. One is evaluating Infrahub and has no interest - [What this demo shows](/demo-otn/what-this-shows.md): Two readers land on this page. One is evaluating Infrahub and has no interest ## demo-service-catalog A proof of concept for a service catalog using Infrahub and Streamlit. - [Home](/demo-service-catalog.md): A proof of concept for a service catalog using Infrahub and Streamlit. ### business-impact - [View what each service costs to deliver](/demo-service-catalog/business-impact/cost-of-service.md): View the hardware cost (CAPEX) and the circuit cost (OPEX) each service carries, built from the devices and circuits along its paths, read the inputs and formulas, and download the figures as a CSV file that Infrahub generates. - [Find the Gold services that depend on a single device](/demo-service-catalog/business-impact/find-single-points-of-failure.md): View which Gold services have a single point of failure on the current network, and what would have no path if a switch or edge router failed now. - [Notify the Gold customers a change puts at risk](/demo-service-catalog/business-impact/notify-gold-customers.md): View the customers each maintenance change affects, with their tier and status, in an Infrahub artifact and on the Customer notification page, and send the at-risk Gold customers to a CRM with the gold-outreach webhook. - [Business impact](/demo-service-catalog/business-impact/overview.md): How the demo links customers and service tiers to devices, shows which services a planned change puts at risk or takes down, blocks a plan that leaves a Gold service without a path, notifies the Gold customers at risk, and shows what each service costs to deliver. - [Plan maintenance that keeps Gold services in service](/demo-service-catalog/business-impact/plan-maintenance.md): Plan maintenance on Paris edge router 1, view the Gold services at risk on one path and the Silver and Bronze services down, view the Gold outage guard block maintenance on Brussels switch 1, view the guard fail when a tier rule is raised above what the network provides, and view the record Infrahub keeps of each proposed change. ### getting-started - [Developer Walkthrough](/demo-service-catalog/getting-started/developer-walkthrough.md): A step-by-step guide to running the demo from a developer perspective. - [How to Install the Service Catalog Demo](/demo-service-catalog/getting-started/installation.md): Set up the Service Catalog demo environment with Infrahub and Streamlit to enable self-service network provisioning. - [How to Use the Service Catalog Demo](/demo-service-catalog/getting-started/user-walkthrough.md): Experience the complete service delivery workflow from request to provisioning using both the Service Catalog portal and Infrahub interface. ## emma Emma was always meant as a place to experiment. Most of the capabilities it tried out have since matured into proper projects in the Infrahub ecosystem, so Emma is now deprecated. OpsMill is no longer developing or supporting it, and this documentation stays online for reference only. - [Emma is deprecated](/emma.md): Emma was always meant as a place to experiment. Most of the capabilities it tried out have since matured into proper projects in the Infrahub ecosystem, so Emma is now deprecated. OpsMill is no longer developing or supporting it, and this documentation stays online for reference only. ### features - [Data Import and Export](/emma/features/data-import-export.md): Emma provides powerful tools for importing data into Infrahub from CSV files and exporting Infrahub data back to CSV format. This enables efficient migration from existing systems and data sharing between tools. - [AI Schema Builder](/emma/features/schema-builder.md): Emma's Schema Builder is an AI-powered tool that helps you create Infrahub schemas using natural language descriptions. Instead of manually writing YAML schema definitions, you can describe what you need and let Emma's AI assistant generate the appropriate schema structure. - [Schema Management](/emma/features/schema-management.md): Emma provides comprehensive tools for managing Infrahub schemas throughout their lifecycle. From loading and visualizing schemas to organizing them in libraries, Emma makes schema management accessible and efficient. ### getting-started - [Configuration](/emma/getting-started/configuration.md): Emma connects to Infrahub using standard environment variables and configuration options. This guide covers all the ways to configure Emma for your environment. - [First Steps](/emma/getting-started/first-steps.md): Welcome to Emma! This guide will walk you through your first experience using Emma to interact with Infrahub. - [Installation](/emma/getting-started/installation.md): Emma is an experimental AI-powered assistant for Infrahub that helps you manage infrastructure schemas and data through an intuitive web interface. ### guides - [Building Your First Schema](/emma/guides/building-your-first-schema.md): This guide walks you through creating your first Infrahub schema using Emma's AI Schema Builder. We'll create a practical schema for modeling network devices. ### reference - [Configuration Reference](/emma/reference/configuration.md): This reference covers all configuration options available in Emma, including environment variables, feature flags, and runtime settings. - [Feature Flags](/emma/reference/feature-flags.md): Emma uses feature flags to enable experimental and beta functionality. This allows you to try new features while maintaining stability in production environments. - [Troubleshooting](/emma/reference/troubleshooting.md): This guide covers common issues you might encounter while using Emma and how to resolve them. ## exporter Infrahub Exporter is a service that exports metrics and service discovery information from Infrahub to monitoring systems like Prometheus and OpenTelemetry. - [Infrahub Exporter](/exporter.md): Infrahub Exporter is a service that exports metrics and service discovery information from Infrahub to monitoring systems like Prometheus and OpenTelemetry. ### guides - [Configure Infrahub Exporter](/exporter/guides/configuration.md): Configuration - [Install and run Infrahub Exporter](/exporter/guides/installation.md): This guide walks you through installing and running the Infrahub Exporter on your system. ## infrahub-demo-sp Welcome to the Infrahub demo-sp example — a service-provider bundle that - [Infrahub demo-sp example](/infrahub-demo-sp.md): Welcome to the Infrahub demo-sp example — a service-provider bundle that ### architecture This page summarises the data flow and the role of each directory. - [Architecture](/infrahub-demo-sp/architecture.md): This page summarises the data flow and the role of each directory. ### backbone - [Add a PE router](/infrahub-demo-sp/backbone/add-pe.md): This page documents PE onboarding end-to-end: how an operator adds a PE ### lab - [Containerlab](/infrahub-demo-sp/lab/containerlab.md): This page covers the optional containerlab integration: what runs, which PEs ### quickstart This page gets you from clone to a running demo in about 10 minutes. For an - [Quick start](/infrahub-demo-sp/quickstart.md): This page gets you from clone to a running demo in about 10 minutes. For an ### schema-reference This page covers the SP-demo-specific schema nodes defined in schemas/sp/. - [Schema reference](/infrahub-demo-sp/schema-reference.md): This page covers the SP-demo-specific schema nodes defined in schemas/sp/. ### services - [L3VPN service](/infrahub-demo-sp/services/l3vpn.md): This page documents the L3VPN service end-to-end: how an operator creates - [SD-WAN service](/infrahub-demo-sp/services/sdwan.md): The SD-WAN service models a customer's SD-WAN overlay across one or more ### troubleshooting Common failure modes and their fixes. If your problem is not here, check - [Troubleshooting](/infrahub-demo-sp/troubleshooting.md): Common failure modes and their fixes. If your problem is not here, check ### validation - [Batfish validation](/infrahub-demo-sp/validation/batfish.md): BatfishBackboneCheck runs the Batfish query ## infrahub-solution-ai-dc ### solution-ai-dc - [Demo guide](/infrahub-solution-ai-dc/solution-ai-dc/demo-guide.md): Run the AI/DC solution end to end — from loading design data to generating a complete data center fabric. - [Design-driven automation](/infrahub-solution-ai-dc/solution-ai-dc/design-driven-automation.md): How the AI/DC solution separates design intent from infrastructure implementation using Infrahub Generators. - [EVPN/VXLAN overlay](/infrahub-solution-ai-dc/solution-ai-dc/evpn-vxlan-overlay.md): Multi-tenant EVPN/VXLAN overlay services layered on top of the AI/DC solution's OSPF-underlay Clos fabric. - [Generator patterns](/infrahub-solution-ai-dc/solution-ai-dc/generator-patterns.md): Implementation patterns used in the AI/DC solution Generators — queries, device creation, IP allocation, cabling, and checksum propagation. - [Installation & Setup](/infrahub-solution-ai-dc/solution-ai-dc/installation-setup.md): Prerequisites, environment setup, and repository structure for the AI/DC solution. - [Modular Generator architecture](/infrahub-solution-ai-dc/solution-ai-dc/modular-generator-architecture.md): How the AI/DC solution chains Generators through checksum triggers, validates parent completion, and allocates interfaces deterministically. - [Multivendor configuration](/infrahub-solution-ai-dc/solution-ai-dc/multivendor-config.md): How the AI/DC solution renders per-vendor (Cisco, Arista, Dell, Juniper) device configuration from a single design model using vendor device groups. - [AI/DC solution](/infrahub-solution-ai-dc/solution-ai-dc/overview.md): Design-driven automation for large-scale AI data center fabrics using Infrahub Generators. - [Release notes](/infrahub-solution-ai-dc/solution-ai-dc/release-notes.md): Releases of the Infrahub AI/DC solution. ## infrahubctl ### infrahubctl infrahubctl is a command line utility designed to help with the day to day management of an Infrahub installation. - [infrahubctl](/infrahubctl/infrahubctl.md): infrahubctl is a command line utility designed to help with the day to day management of an Infrahub installation. ### infrahubctl-branch Manage the branches in a remote Infrahub instance. - [infrahubctl branch](/infrahubctl/infrahubctl-branch.md): Manage the branches in a remote Infrahub instance. ### infrahubctl-check Execute user-defined checks. - [infrahubctl check](/infrahubctl/infrahubctl-check.md): Execute user-defined checks. ### infrahubctl-dump Export nodes and their relationships out of the database. - [infrahubctl dump](/infrahubctl/infrahubctl-dump.md): Export nodes and their relationships out of the database. ### infrahubctl-generator Run a generator script. - [infrahubctl generator](/infrahubctl/infrahubctl-generator.md): Run a generator script. ### infrahubctl-graphql Various GraphQL related commands. - [infrahubctl graphql](/infrahubctl/infrahubctl-graphql.md): Various GraphQL related commands. ### infrahubctl-info Display the status of the Python SDK. - [infrahubctl info](/infrahubctl/infrahubctl-info.md): Display the status of the Python SDK. ### infrahubctl-load Import nodes and their relationships into the database. - [infrahubctl load](/infrahubctl/infrahubctl-load.md): Import nodes and their relationships into the database. ### infrahubctl-marketplace Browse and download schemas from the Infrahub Marketplace. - [infrahubctl marketplace](/infrahubctl/infrahubctl-marketplace.md): Browse and download schemas from the Infrahub Marketplace. ### infrahubctl-menu Manage the menu in a remote Infrahub instance. - [infrahubctl menu](/infrahubctl/infrahubctl-menu.md): Manage the menu in a remote Infrahub instance. ### infrahubctl-object Manage objects in a remote Infrahub instance. - [infrahubctl object](/infrahubctl/infrahubctl-object.md): Manage objects in a remote Infrahub instance. ### infrahubctl-protocols Export Python protocols corresponding to a schema. - [infrahubctl protocols](/infrahubctl/infrahubctl-protocols.md): Export Python protocols corresponding to a schema. ### infrahubctl-render Render a local Jinja2 Transform for debugging purpose. - [infrahubctl render](/infrahubctl/infrahubctl-render.md): Render a local Jinja2 Transform for debugging purpose. ### infrahubctl-repository Manage the repositories in a remote Infrahub instance. - [infrahubctl repository](/infrahubctl/infrahubctl-repository.md): Manage the repositories in a remote Infrahub instance. ### infrahubctl-run Execute a script. - [infrahubctl run](/infrahubctl/infrahubctl-run.md): Execute a script. ### infrahubctl-schema Manage the schema in a remote Infrahub instance. - [infrahubctl schema](/infrahubctl/infrahubctl-schema.md): Manage the schema in a remote Infrahub instance. ### infrahubctl-task Manage Infrahub tasks. - [infrahubctl task](/infrahubctl/infrahubctl-task.md): Manage Infrahub tasks. ### infrahubctl-telemetry Usage: - [infrahubctl telemetry](/infrahubctl/infrahubctl-telemetry.md): Usage: ### infrahubctl-transform Render a local transform (TransformPython) for debugging purpose. - [infrahubctl transform](/infrahubctl/infrahubctl-transform.md): Render a local transform (TransformPython) for debugging purpose. ### infrahubctl-validate Helper to validate the format of various files. - [infrahubctl validate](/infrahubctl/infrahubctl-validate.md): Helper to validate the format of various files. ### infrahubctl-version Display the version of Python and the version of the Python SDK in use. - [infrahubctl version](/infrahubctl/infrahubctl-version.md): Display the version of Python and the version of the Python SDK in use. ## integrations Infrahub integrates with a wide range of infrastructure management and automation tools to help you synchronize data, automate workflows, and manage your infrastructure. This page provides an overview of all available integrations and their capabilities. - [Infrahub Integrations](/integrations.md): Infrahub integrates with a wide range of infrastructure management and automation tools to help you synchronize data, automate workflows, and manage your infrastructure. This page provides an overview of all available integrations and their capabilities. ## mcp Infrahub MCP Server connects AI assistants and IDE agents to Infrahub using the open Model Context Protocol standard — so agents can query, create, update, and propose changes to your infrastructure data through a consistent, audited interface. It works with any MCP-compatible client (Claude Desktop, VS Code, Cursor, CLI agents, and more) with no custom glue code required. - [Infrahub MCP Server](/mcp.md): Infrahub MCP Server connects AI assistants and IDE agents to Infrahub using the open Model Context Protocol standard — so agents can query, create, update, and propose changes to your infrastructure data through a consistent, audited interface. It works with any MCP-compatible client (Claude Desktop, VS Code, Cursor, CLI agents, and more) with no custom glue code required. ### getting-started - [Set up authentication](/mcp/getting-started/authentication.md): This guide walks through configuring each authentication mode. For a deeper explanation of how the auth architecture works — sequence diagrams, the two-layer model, audit logs, and branch-placeholder resolution — see Authentication architecture. - [Your first agent run](/mcp/getting-started/first-agent-run.md): This walkthrough connects an LLM client to your running Infrahub MCP server and asks it a read-only question. By the end you'll have confirmed the server is reachable, the agent can discover your schema, and the built-in infrahub_agent system prompt is guiding the conversation correctly. - [Install the Infrahub MCP server](/mcp/getting-started/installation.md): This guide gets you from a fresh checkout to a running Infrahub MCP server in a few minutes. Once it's running, continue with Authentication to pick a credential model, then Your first agent run to connect an LLM. - [Make a change through an agent](/mcp/getting-started/make-a-change.md): This walkthrough takes you through the full write path: ask an agent to update something in Infrahub, watch it auto-create an isolated session branch, and open a Proposed Change for human review. No data on your default branch is modified until a human approves the merge. ### guides - [Running with Docker](/mcp/guides/docker.md): This guide covers deploying the Infrahub MCP server as a container, including running it alongside Infrahub in the same Docker Compose stack. - [Docker Compose deployment](/mcp/guides/docker-compose.md): This guide covers running the Infrahub MCP server as a container — standalone for development, or as a sidecar alongside Infrahub in the same Docker Compose stack for production. - [Installing Infrahub MCP](/mcp/guides/installation.md): This guide provides step-by-step instructions for installing and configuring different MCP clients to connect to the Infrahub MCP server. ### integrations - [Claude Agent SDK](/mcp/integrations/claude-agent-sdk.md): The Claude Agent SDK is Anthropic's framework for building custom agents on top of the Claude API. It has native MCP support, so connecting to the Infrahub MCP server is a short wiring exercise. - [Claude Code](/mcp/integrations/claude-code.md): Claude Code is Anthropic's CLI/IDE agent. It auto-detects .mcp.json files at project roots and loads the servers on startup — a perfect fit for the Infrahub MCP server when you're working inside a specific Infrahub consumer repository (IaC, Ansible, Python clients, etc.). - [Claude Desktop](/mcp/integrations/claude-desktop.md): Claude Desktop is the default starting point for most users — it speaks MCP over stdio and can spawn the Infrahub MCP server locally without any infrastructure. - [Cursor](/mcp/integrations/cursor.md): Cursor supports MCP servers via its Tools & Integrations panel. This page shows the Infrahub MCP server configuration and notes specific to Cursor's tool-approval UX. - [OpenAI Agents SDK](/mcp/integrations/openai-agents-sdk.md): The OpenAI Agents SDK has first-class support for MCP servers. This page shows how to build a custom infrastructure-automation agent that talks to the Infrahub MCP server over Streamable HTTP. - [VS Code](/mcp/integrations/vscode.md): VS Code supports MCP through its extension API — the Infrahub MCP server shows up as a tool provider alongside Copilot. This page covers the code --add-mcp setup and the VS Code Copilot compatibility flag. ### references - [Authentication architecture](/mcp/references/authentication.md): For the step-by-step configuration recipes, see Set up authentication. This page explains how each mode works end-to-end. - [Configuration reference](/mcp/references/configuration.md): The Infrahub MCP server is configured entirely through environment variables. All middleware features are opt-in — the server works out of the box with only the required connection variables set. - [Infrahub MCP methods](/mcp/references/methods.md): Response formats ### release-notes - [Release Notes](/mcp/release-notes.md) - [Release 1.0.0](/mcp/release-notes/release-1_0_0.md): The first stable release — query Infrahub and propose changes for review from any MCP-compatible client. - [Release 1.0.1](/mcp/release-notes/release-1_0_1.md): Error messages now include schema hints so AI agents can correct invalid queries and retry. - [Release 1.1.1](/mcp/release-notes/release-1_1_1.md): Run the MCP server as a shared service with pass-through authentication, read-only mode, and observability. - [Release 1.1.2](/mcp/release-notes/release-1_1_2.md): Dependency and internal tooling maintenance, with no changes to tools or runtime behavior. - [Release 1.1.3](/mcp/release-notes/release-1_1_3.md): Fix startup for non-HTTP transports, plus pipeline and tooling maintenance. - [Release 1.1.4](/mcp/release-notes/release-1_1_4.md): Align with current Infrahub SDK releases, plus routine dependency maintenance. - [Release 1.1.5](/mcp/release-notes/release-1_1_5.md): Validate a session branch before reuse so an unusable branch fails with a clear reason. - [Release 1.1.6](/mcp/release-notes/release-1_1_6.md): Keep an AI conversation going after its session branch is merged or deleted, with automatic recovery and a reset tool to start the next change set. - [Release 1.1.7](/mcp/release-notes/release-1_1_7.md): Trace how two infrastructure objects are connected and find what a change could reach, with two read-only graph-traversal tools backed by Infrahub 1.10. - [Release 1.2.0](/mcp/release-notes/release-1_2_0.md): Keep Infrahub credentials in a local environment file while sharing MCP client configuration, with compatible FastMCP and MCP SDK dependencies. ### use-cases - [Brownfield network onboarding](/mcp/use-cases/brownfield-onboarding.md): Onboarding an existing ("brownfield") network into Infrahub is a long tail of small writes: one device per rack, one interface per device, one cable per interface. Agents shine here — they can read source-of-truth data from CSV exports, SNMP, LLDP neighbours, or NetBox, and turn it into idempotent Infrahub upserts on a session branch you can review all at once. - [Compliance analysis](/mcp/use-cases/compliance-analysis.md): Agents are a natural fit for ad-hoc compliance questions: "do all edge routers have dual uplinks to different spines?", "are all production VLANs documented?", "which devices are missing an owner?". This recipe shows how to run those checks as read-only agent workflows against Infrahub. - [Cross-system correlation](/mcp/use-cases/cross-system-correlation.md): Infrastructure data doesn't live in one place. A ticket in Jira mentions a device, a Git commit touches a configuration file, an Ansible run fails against a hostname. Connecting those dots — "which device is this about, what depends on it, what changed recently?" — is a natural fit for an agent that can read Infrahub through MCP and your other systems through their own tools. - [Natural language to GraphQL](/mcp/use-cases/natural-language-graphql.md): getnodes and searchnodes handle most everyday queries, but some questions need the full expressive power of GraphQL: aggregates, deep joins, multi-kind filters, and computed fields. This recipe shows how an agent goes from a free-form English question to a working query_graphql call, using the server's own schema as the grounding. - [Safe changes via branch isolation](/mcp/use-cases/safe-changes-branch-isolation.md): Branch isolation is the single most important safety property of the Infrahub MCP server: an agent can never write directly to your default branch. Every mutation lives on an ephemeral session branch that only becomes part of the default branch once a human reviews and merges a Proposed Change. This page explains the model end-to-end and shows how to tune it. - [Troubleshooting data queries](/mcp/use-cases/troubleshooting-queries.md): When an agent answers "I couldn't find that device" — it's almost always a data-query problem, not a data problem. This recipe walks through the diagnostic flow for "why is my query returning nothing?" ## nornir This integration bridges Nornir's powerful automation framework with Infrahub's next-generation infrastructure data management platform. - [Nornir Integration with Infrahub](/nornir.md): This integration bridges Nornir's powerful automation framework with Infrahub's next-generation infrastructure data management platform. ### getting-started This guide helps you set up your first integration between Nornir and Infrahub. By the end, you'll have a working automation setup that demonstrates the power of dynamic inventory management. - [Getting Started](/nornir/getting-started.md): This guide helps you set up your first integration between Nornir and Infrahub. By the end, you'll have a working automation setup that demonstrates the power of dynamic inventory management. ### guides - [How to Configure Schema Mappings](/nornir/guides/configuring-schema-mappings.md): This guide shows you how to configure schema mappings to control how Infrahub data translates into Nornir inventory properties. Schema mappings are the bridge between your Infrahub data model and Nornir's expected host attributes. - [How to Create Your First Automation Workflow](/nornir/guides/your-first-automation-workflow.md): This guide walks you through building a complete network automation workflow using Infrahub as your inventory source and artifact management system. You'll retrieve device configurations managed by Infrahub. ### references - [Artifact management plugin](/nornir/references/plugins/artifact_tasks.md): regeneratehostartifact - [CoreFileObject management tasks](/nornir/references/plugins/file_object_tasks.md): uploadfileobject - [Inventory plugin](/nornir/references/plugins/infrahub_inventory.md): InfrahubInventory ### release-notes Releases and changes to nornir-infrahub. - [Release notes](/nornir/release-notes.md): Releases and changes to nornir-infrahub. ### topics - [Understanding Artifact Lifecycle Management](/nornir/topics/artifact-lifecycle-management.md): This topic explores how Infrahub's artifact system works with Nornir to enable sophisticated configuration management workflows. Understanding artifact lifecycle management is crucial for implementing robust, auditable network automation. - [Infrahub Inventory Concepts](/nornir/topics/infrahub-inventory-concepts.md): This topic provides a deep understanding of how Infrahub's graph database model maps to Nornir's inventory concepts. Understanding these mappings is essential for designing effective automation workflows. - [Understanding the Nornir-Infrahub Integration](/nornir/topics/understanding-nornir-infrahub-integration.md): This topic explains the core concepts behind the Nornir-Infrahub integration, how it works, and why it represents a paradigm shift in network automation. ## python-sdk ### guides - [Executing queries in a batch](/python-sdk/guides/batch.md): The Python SDK client allows you to group the execution of multiple queries in a batch. - [Branch management](/python-sdk/guides/branches.md): The Python SDK provides multiple methods to manage the branches in an Infrahub instance. - [How to create and configure an Infrahub client](/python-sdk/guides/client.md): This guide shows you how to create and configure an Infrahub client using the Python SDK. You'll learn how to set up authentication, configure proxy settings, and customize client behavior for your infrastructure automation workflows. - [Create, update and deleting nodes](/python-sdk/guides/create_update_delete.md): We will be using the following schema in this guide: - [Traversing the graph](/python-sdk/guides/graph_traversal.md): Graph traversal lets you discover how nodes are connected without knowing the relationship path in advance. The SDK exposes two client methods: - [Installing infrahub-sdk](/python-sdk/guides/installation.md): The Infrahub SDK for Python is available on PyPI and can be installed using the pip package installer. It is recommended to install the SDK into a virtual environment. - [Using the object-storage](/python-sdk/guides/object-storage.md): The Python SDK can be used to interface with Infrahub's object-storageartifact-file-storage/overview). - [Overview](/python-sdk/guides/python-typing.md): Use Python's type system with the Infrahub SDK to catch schema mismatches while you write code, not when it runs. This guide shows how to type your SDK calls with Protocols, generate typed classes from your own schema, and generate Pydantic models from your GraphQL queries. - [Querying data in Infrahub](/python-sdk/guides/query_data.md): We can query data in 3 ways using the SDK: - [Using Resource Managers](/python-sdk/guides/resource-manager.md): The goal of this guide is to show you how to create a resource pool using the Python SDK, and how you can allocated resources with them. - [Using the client store](/python-sdk/guides/store.md): The client in the SDK contains a store that is used to store objects in a local cache. - [Using the client tracking mode](/python-sdk/guides/tracking.md): The Python SDK provides a feature known as Tracking Mode. This mode allows for the aggregation and tracking of operations performed during a session, enhancing efficiency and data management. ### introduction The Infrahub Python SDK is a client library for interacting with Infrahub programmatically. It handles authentication, query construction, and data serialization so you can work with infrastructure data using native Python objects instead of raw API calls. - [Infrahub Python SDK](/python-sdk/introduction.md): The Infrahub Python SDK is a client library for interacting with Infrahub programmatically. It handles authentication, query construction, and data serialization so you can work with infrastructure data using native Python objects instead of raw API calls. ### reference - [Compatibility matrix](/python-sdk/reference/compatibility.md): This page documents which versions of the Infrahub Python SDK are compatible with each version of Infrahub. - [Python SDK Configuration](/python-sdk/reference/config.md): The Python SDK (Async or Sync) client can be configured using an instance of the Config class. - [Python SDK Templating](/python-sdk/reference/templating.md): Filters can be used when defining computed attributes or Jinja2 Transforms within Infrahub. ### sdk_ref - [infrahub_sdk.client](/python-sdk/sdk_ref/infrahub_sdk/client.md): Classes - [infrahub_sdk.graph_traversal.models](/python-sdk/sdk_ref/infrahub_sdk/graph_traversal/models.md): Pydantic models for the Infrahub graph-traversal queries (Infrahub 1.10+). - [infrahub_sdk.graph_traversal.query](/python-sdk/sdk_ref/infrahub_sdk/graph_traversal/query.md): GraphQL query strings and variable builders for graph traversal (Infrahub 1.10+). - [infrahub_sdk.node.node](/python-sdk/sdk_ref/infrahub_sdk/node.md): Classes - [infrahub_sdk.node.attribute](/python-sdk/sdk_ref/infrahub_sdk/node/attribute.md): Classes - [infrahub_sdk.node.constants](/python-sdk/sdk_ref/infrahub_sdk/node/constants.md): This module is empty or contains only private/internal implementations. - [infrahub_sdk.node.metadata](/python-sdk/sdk_ref/infrahub_sdk/node/metadata.md): Classes - [infrahub_sdk.node.parsers](/python-sdk/sdk_ref/infrahub_sdk/node/parsers.md): Functions - [infrahub_sdk.node.property](/python-sdk/sdk_ref/infrahub_sdk/node/property.md): Classes - [infrahub_sdk.node.related_node](/python-sdk/sdk_ref/infrahub_sdk/node/related_node.md): Classes - [infrahub_sdk.node.relationship](/python-sdk/sdk_ref/infrahub_sdk/node/relationship.md): Classes ### topics - [Manage data with Object files](/python-sdk/topics/object_file.md): Introduction - [Understanding tracking in the Python SDK](/python-sdk/topics/tracking.md): Introduction ## schema-library Welcome to the Schema Library for Infrahub! This repository offers a collection of schemas designed to streamline and standardize infrastructure-related data structures. - [Schema library for Infrahub](/schema-library.md): Welcome to the Schema Library for Infrahub! This repository offers a collection of schemas designed to streamline and standardize infrastructure-related data structures. ### contributing We welcome contributions and feedback! Please open an issue or submit a pull request to suggest additions, improvements, or to report bugs. - [Contributing](/schema-library/contributing.md): We welcome contributions and feedback! Please open an issue or submit a pull request to suggest additions, improvements, or to report bugs. ### reference - [Azure](/schema-library/reference/azure.md): This schema extension introduces cloud support for Microsoft Azure. - [Cable](/schema-library/reference/cable.md): This schema extension contains a basic Cable model allowing you to connect two endpoints. - [Circuit](/schema-library/reference/circuit.md): This schema extension adds Circuit and Circuit Endpoint nodes and links them to your infrastructure. A circuit could be a fiber connecting two sites, with one endpoint on each site. - [Circuit Contract](/schema-library/reference/circuit_contract.md): This schema extension adds a Circuit Contract node to capture the service agreement behind a circuit with its provider. - [Circuit Service](/schema-library/reference/circuit_service.md): This schema extension contains model coming on top of circuit to capture a single service shared across multiple circuits. - [Cluster](/schema-library/reference/cluster.md): This schema extension contains the foundations to capture clusters. With this one in place you can unlock various cluster flavours (a hosting cluster able to host VMs, a firewall cluster built with specific appliances ...). - [Compute](/schema-library/reference/compute.md): This schema extension captures physical servers and virtual machines, with a generic compute unit both inherit from and a generic for anything able to host VMs. Pair it with extensions/hosting_cluster to group compute units into clusters. - [Cross-Connect](/schema-library/reference/cross_connect.md): This schema extension adds a Cross-Connect node. Think of it as a cable operated by a provider: attach it to a location, then connect endpoints to it (e.g. the rear interface of a patch panel or a circuit endpoint). - [DCIM](/schema-library/reference/dcim.md): Base DCIM schema: device types, platforms, devices, and physical and virtual interfaces, plus the endpoint and connector generics that cables, circuits and cross-connects build on. - [Device Module](/schema-library/reference/device_module.md): This schema extension lets you capture module bays on a DcimPhysicalDevice and the modules installed into them (e.g. fan trays, line cards). A device can have any number of module bays, and each bay can optionally hold one module. - [PSU Module](/schema-library/reference/device_module_psu.md): This schema extension adds a PSU (Power Supply Unit) flavour on top of the generic Module and Module Type from extensions/device_module, so you can track power supplies installed in a device's module bays with PSU-specific attributes such as wattage and hot-swap capability. - [Firewall Policer](/schema-library/reference/firewall_policer.md): This schema extension contains models for traffic policers and the classes and rules that reference them, so you can describe rate limiting alongside the interfaces it is applied to. - [Hosting Cluster](/schema-library/reference/hosting_cluster.md): A generic cluster built from compute units (e.g. servers) that can host virtual machines. - [InfiniBand Fabric Hardware](/schema-library/reference/infiniband.md): This schema extension models the hardware of an InfiniBand fabric: switches with their configuration profile (AAA, role, split-ready, SSH and CLI settings), switch and management interfaces with lane width, split and speed options, rail-optimized scalable units (RSU) and the fabric that groups them. It does not model the InfiniBand protocol itself (subnet manager, partitions, routing). - [Interface Breakout](/schema-library/reference/interface_breakout.md): This schema extension introduces relationships to support breakout interfaces, enabling you to document the breakout of a physical interface into smaller physical interfaces. - [IPAM](/schema-library/reference/ipam.md): Base IPAM schema: IP prefixes and IP addresses, plus the scope generics a prefix or a VLAN group can be attached to. - [IPAM Aggregate](/schema-library/reference/ipam_aggregate.md): This schema extension captures the top-level IPv4 and IPv6 blocks assigned by a Regional Internet Registry (RIR). It adds an Aggregate node for the block and an RIR node for the registry or private entity that manages the address space. - [LAG](/schema-library/reference/lag.md): This schema extension includes models for Link Aggregation Groups (LAGs), enabling you to link physical interfaces as building blocks of your LAG interface. It can be used in standard networking environments as well as in compute scenarios, such as capturing bond interfaces. - [Location](/schema-library/reference/location.md): Base Location schema: the generic every location tier inherits from, and the hosting generic that lets devices and other objects be placed at a location. Concrete tiers such as Site come from the location extensions. - [Location Extended](/schema-library/reference/location_extended.md): This schema extension is the most detailed when it comes to location, you'll find all the layers you can think of. It defines its own hierarchical Location.Rack, incompatible with the flat one extensions/rack defines, so load one or the other, not both. - [Location Minimal](/schema-library/reference/location_minimal.md): This schema extension provides a self-contained Region -> Country -> Metro -> Site hierarchy for storing location data, with the Site carrying facility, physical address, timezone and status. Its Site node is the same as the one in extensions/location_site, so the two can be loaded together. A location name is unique across every tier, so a single-country deployment should enter the hierarchy at Country, with Region as the national node, rather than repeating a country under several regions. - [Location Site](/schema-library/reference/location_site.md): This schema extension introduces a Site node with facility, physical address, timezone and status, for deployments that want a flat list of sites without a hierarchy. It is the same Site node as in extensions/location_minimal, which adds Region, Country and Metro tiers above it. - [MLAG](/schema-library/reference/mlag.md): This schema extension contains the foundations to capture Multi-Chassis Link Aggregation Groups (MLAG). It comes on top of the LAG extension. - [Module Port](/schema-library/reference/module_port.md): This schema extension adds module ports: the ports a module provides, as declared by its module type - what NetBox module-type definitions list under interfaces, console-ports and power-ports. - [Modules Linecards](/schema-library/reference/modules_linecards.md): This schema extension allows you to capture Linecard related information like the version. You can insert the Linecard into a Dcim Physical Device and leverage the Linecard type model. The Linecard can accept PIC to help configure PORT information like breakout-capabilities and configurations. - [Modules Routing Engine](/schema-library/reference/modules_routing_engine.md): This schema extension allows you to capture Routing Engine related information like the version. You can insert the Routing Engine into a Dcim Physical Device and leverage the Routing Engine type model. - [Optical Multiplexer](/schema-library/reference/optical_multiplexer.md): This schema extension models optical add-drop multiplexers (OADM) and the wavelength division multiplexing (WDM) channels they carry, for both CWDM and DWDM. It adds an Optical Multiplexer device with front and rear interfaces, a WDM Channel node holding channel number, wavelength and frequency, and a WDM Transceiver flavour of the transceiver model tuned to a channel. - [Optical Transport](/schema-library/reference/optical_transport.md): Comprehensive optical transport network schemas for DWDM/WDM systems (ADVA FSP 3000 and similar platforms). Covers four layers: wavelength (ITU-T G.694.1 grid, optical bands, DWDM channels), topology (logical optical nodes, passive multiplexers, fiber links), equipment (transponder/amplifier/ROADM modules, ROADM degrees, WSS cross-connects), and service (end-to-end optical services, optical paths, path segments). Not designed to be loaded together with extensions/optical_multiplexer. - [Organization](/schema-library/reference/organization.md): Base Organization schema: the generic organization plus Manufacturer and Provider nodes. - [Patch Panel](/schema-library/reference/patch_panel.md): This schema extension allows you to capture patch panel related information like rear and front interfaces and the mapping between them. You can insert the patch panel into a rack and leverage the device type model. Cassettes and other inserts are tracked as regular device modules in module bays, through extensions/device_module. - [Internet Exchange](/schema-library/reference/peering_ixp.md): This schema extension adds an Internet Exchange (IXP) node and an IXP Connection node linking your devices to an exchange, and ties IXP connections to the BGP sessions established over them. - [Physical Disk](/schema-library/reference/physical_disk.md): Simple schema allowing you to capture physical disk information for inventory and lifecycle management. - [QinQ](/schema-library/reference/qinq.md): This schema extension adds the Service VLAN and Customer VLAN nodes needed to model QinQ on top of the VLAN extension. - [QoS](/schema-library/reference/qos.md): This schema extension contains models for Quality of Service (QoS) - [Rack](/schema-library/reference/rack.md): This schema extension introduces a Rack node representing a physical equipment rack installed at a site. Racks are placed at a LocationSite, which comes from extensions/locationsite or extensions/locationminimal, and can host devices and other equipment. experimental/location_extended defines its own Rack node, so do not load both. - [Routing](/schema-library/reference/routing.md): This schema extension contains the Routing Protocol generic that every protocol extension builds on. The idea is one protocol instance per IpamVRF and DcimDevice pair. - [Routing Aggregate](/schema-library/reference/routing_aggregate.md): This schema extension adds an Aggregate Route node: a summary route, with its destination prefix and discard flag, announced by a routing protocol instance. - [Routing BGP](/schema-library/reference/routing_bgp.md): This schema extension adds Autonomous System, BGP Peer Group and BGP Session nodes, and links autonomous systems to devices and organizations. - [Routing BGP Community](/schema-library/reference/routing_bgp_community.md): This schema extension adds a BGP Community node to reference from routing policies. - [Routing BGP Route Reflector](/schema-library/reference/routing_bgp_rr.md): This schema extension adds a Route Reflector Cluster node on top of the BGP extension and links it to BGP peer groups. - [Routing OSPF](/schema-library/reference/routing_ospf.md): This schema extension adds OSPF and OSPF Interface nodes to model an OSPF instance per device and VRF and the interfaces it runs on. - [Routing PIM](/schema-library/reference/routing_pim.md): This schema extension adds PIM (Protocol Independent Multicast) and PIM Interface nodes to model a PIM instance per device and VRF and the interfaces it runs on. - [Routing Policies](/schema-library/reference/routing_policies.md): This schema extension contains the Routing Policy generic. Each routing protocol extension subclasses it with its own policy flavour. - [Routing Policies Aggregate](/schema-library/reference/routing_policies_aggregate.md): This schema extension adds an Aggregate Routing Policy node, a flavour of the Routing Policy generic, and replaces the free-text import and export policies on Aggregate Route with relationships to it. - [Routing Policies BGP](/schema-library/reference/routing_policies_bgp.md): This schema extension adds a BGP Routing Policy node, a flavour of the Routing Policy generic, and replaces the free-text import and export policies on BGP Peer Group and BGP Session with relationships to it. - [Routing Policies OSPF](/schema-library/reference/routing_policies_ospf.md): This schema extension adds an OSPF Routing Policy node, a flavour of the Routing Policy generic, and replaces the free-text import and export policies on OSPF with relationships to it. - [Routing Policies PIM](/schema-library/reference/routing_policies_pim.md): This schema extension adds a PIM Routing Policy node, a flavour of the Routing Policy generic, and replaces the free-text import and export policies on PIM with relationships to it. - [Security](/schema-library/reference/security.md): This schema extension contains models for implementing detailed security. - [SNMP](/schema-library/reference/snmp.md): This schema extension contains models for SNMP Communities and SNMP Clients. A community links to the devices it is configured on; any further wiring, to a tenant for instance, is left to you. - [Tenancy](/schema-library/reference/tenancy.md): This schema extension introduces a Tenant node that can own devices, IP prefixes and addresses, and hosting locations. See the comment at the bottom of tenancy.yml for an example of how to extend tenancy onto optional extension nodes such as DcimCircuit. - [Topology](/schema-library/reference/topology.md): A schema for defining and managing network topology, strategies, and services. - [Transceiver](/schema-library/reference/transceiver.md): This schema extension models pluggable transceivers across form factors (SFP, SFP+, QSFP, QSFP28, QSFP-DD, OSFP, CFP, XFP and more), with a Standard Transceiver and a Bidirectional Transceiver flavour built on a shared generic. A transceiver is either plugged into a physical interface or stored as a spare at a location, and can be linked to its manufacturer. - [VLAN](/schema-library/reference/vlan.md): This schema extension adds VLAN and VLAN Group nodes, with a generic VLAN to build on, and links VLANs to prefixes and layer 2 interfaces. - [VLAN Translation](/schema-library/reference/vlan-translation.md): This schema extension is based on Juniper VLAN MAP, and not yet test out for other vendors. - [VRF](/schema-library/reference/vrf.md): This schema extension adds VRF and Route Target nodes and links prefixes and IP addresses to a VRF. - [VRRP](/schema-library/reference/vrrp.md): This schema extension adds VRRP Group and VRRP Interface nodes, linking a virtual IP address to the layer 3 interfaces that take part in the group. ### release-notes - [Schema Library 2.0.0](/schema-library/release-notes/v2.0.0.md): What changes in your modelling workflow when you move from Schema Library 1.x to 2.0.0. ## skills Infrahub Skills is an open-source AI skills package covering the full Infrahub - [Infrahub Skills](/skills.md): Infrahub Skills is an open-source AI skills package covering the full Infrahub ### choosing-a-skill Sixteen skills is a lot to hold in your head. You do not have to: start from whatever - [Which skill do I use?](/skills/choosing-a-skill.md): Sixteen skills is a lot to hold in your head. You do not have to: start from whatever ### contributing - [Anatomy of a skill](/skills/contributing/anatomy-of-a-skill.md): This page is for people changing the skills, not using them. It covers - [The skill-change pipeline](/skills/contributing/skill-change-pipeline.md): The repository ships skills for changing its own skills. They run in ### first-schema Ten minutes, one schema, loaded onto a branch you can throw away. This - [Your first schema](/skills/first-schema.md): Ten minutes, one schema, loaded onto a branch you can throw away. This ### how-it-works A skill is a structured set of Markdown files: rules, examples, and references the AI reads at the point it needs them. The assistant matches each request against the available skills, activates the one that fits, loads only the files that task reaches, and applies their rules as it works. - [How it works](/skills/how-it-works.md): A skill is a structured set of Markdown files: rules, examples, and references the AI reads at the point it needs them. The assistant matches each request against the available skills, activates the one that fits, loads only the files that task reaches, and applies their rules as it works. ### installation-setup Infrahub Skills can be installed into any AI tool that supports skills or custom context files. Installation takes one command for most setups: install into a specific Infrahub repository to work in that project, or install globally to use the skills across all your projects. - [Installation and setup](/skills/installation-setup.md): Infrahub Skills can be installed into any AI tool that supports skills or custom context files. Installation takes one command for most setups: install into a specific Infrahub repository to work in that project, or install globally to use the skills across all your projects. ### release-notes What changed in each release of Infrahub Skills, and what is different about your workflow after upgrading. Newest first. - [Release Notes](/skills/release-notes.md): What changed in each release of Infrahub Skills, and what is different about your workflow after upgrading. Newest first. - [Release 0.0.1](/skills/release-notes/release-0_0_1.md): The first release of Infrahub Skills — eight skills that build, query, and audit Infrahub resources from natural language. - [Release 1.2.0](/skills/release-notes/release-1_2_0.md): Version realignment from 0.0.1 to 1.2.0 ahead of the automated release tooling. No skill changes. - [Release 1.2.1](/skills/release-notes/release-1_2_1.md): A documentation site for the skills package — installation, how-it-works, and a per-skill reference. - [Release 1.2.2](/skills/release-notes/release-1_2_2.md): New managing-schemas rules for production patterns, plus relationship and check-registration fixes. - [Release 1.2.3](/skills/release-notes/release-1_2_3.md): Every managing-* skill appears again after a fresh install; a frontmatter field had hidden six of them. - [Release 1.2.4](/skills/release-notes/release-1_2_4.md): analyzing-data now answers the question you asked instead of a built-in example when none is passed. - [Release 1.2.5](/skills/release-notes/release-1_2_5.md): Report Infrahub bugs and feature requests with the reporting-issues skill, sanitized and routed automatically. - [Release 1.2.6](/skills/release-notes/release-1_2_6.md): A diagnostics skill, CoreFileObject schema support, and a branch-first default for every data change. - [Release 1.2.7](/skills/release-notes/release-1_2_7.md): A CSV/TSV import skill, Profiles and Object Templates support, YAGNI audit rules, and diagnostics collection built on the infrahub-collect tool. - [Release 1.2.8](/skills/release-notes/release-1_2_8.md): Four new skills — NetBox device-type conversion, concept tutoring, diagnostic-bundle triage, and skill-gap reporting — plus verified generic and cardinality semantics and a corrected infrahubctl command surface. - [Release 1.3.0](/skills/release-notes/release-1_3_0.md): Generator guidance for concurrent relationship writes and delete ordering, managing skills that fire on modification and debugging work, and corrected menu, transform, and repository-configuration guidance. ### sdd-walkthrough-vlan This walkthrough builds a VLAN management domain end to end: a schema, the object data - [Walkthrough: VLAN management](/skills/sdd-walkthrough-vlan.md): This walkthrough builds a VLAN management domain end to end: a schema, the object data ### skills-reference - [Data Analyzer](/skills/skills-reference/analyzing-data.md): Skill: infrahub-analyzing-data - [Diagnostics Analyzer](/skills/skills-reference/analyzing-diagnostics.md): Skill: infrahub-analyzing-diagnostics - [Repo Auditor](/skills/skills-reference/auditing-repo.md): Skill: infrahub-auditing-repo - [Diagnostics Collector](/skills/skills-reference/collecting-diagnostics.md): Skill: infrahub-collecting-diagnostics - [NetBox Device Type Converter](/skills/skills-reference/converting-netbox-device-types.md): Skill: infrahub-converting-netbox-device-types - [Data Importer](/skills/skills-reference/importing-data.md): Skill: infrahub-importing-data - [Check Manager](/skills/skills-reference/managing-checks.md): Skill: infrahub-managing-checks - [Generator Manager](/skills/skills-reference/managing-generators.md): Skill: infrahub-managing-generators - [Menu Manager](/skills/skills-reference/managing-menus.md): Skill: infrahub-managing-menus - [Object Manager](/skills/skills-reference/managing-objects.md): Skill: infrahub-managing-objects - [Schema Manager](/skills/skills-reference/managing-schemas.md): Skill: infrahub-managing-schemas - [Transform Manager](/skills/skills-reference/managing-transforms.md): Skill: infrahub-managing-transforms - [Upgrade Planner](/skills/skills-reference/planning-upgrades.md): Skill: infrahub-planning-upgrades - [Issue Reporter](/skills/skills-reference/reporting-issues.md): Skill: infrahub-reporting-issues - [Skill Gap Reporter](/skills/skills-reference/reporting-skill-gaps.md): Skill: infrahub-reporting-skill-gaps - [Concept Tutor](/skills/skills-reference/teaching-concepts.md): Skill: infrahub-teaching-concepts ### spec-driven-development Spec-Driven Development (SDD) is a structured planning mode for complex or multi-part Infrahub builds. Instead of generating files immediately, the AI reasons through requirements with you first: capturing what needs to be built, validating the approach against Infrahub conventions, breaking the work into discrete tasks, and only generating once the plan is approved. - [Spec-Driven Development](/skills/spec-driven-development.md): Spec-Driven Development (SDD) is a structured planning mode for complex or multi-part Infrahub builds. Instead of generating files immediately, the AI reasons through requirements with you first: capturing what needs to be built, validating the approach against Infrahub conventions, breaking the work into discrete tasks, and only generating once the plan is approved. ### spec-kit-integration Spec Kit runs its own specify, plan, tasks, and implement commands, and on its own it - [Spec Kit integration](/skills/spec-kit-integration.md): Spec Kit runs its own specify, plan, tasks, and implement commands, and on its own it ## sync Infrahub Sync synchronizes infrastructure data between Infrahub and external systems — NetBox, Nautobot, IP Fabric, Slurp’it, Cisco ACI, Peering Manager, ServiceNow-style CMDBs, and any system with a REST/JSON API. Use it to migrate from a legacy system of record, run two systems side-by-side, or keep Infrahub in sync with another source of truth. Define a sync project declaratively in YAML, and the CLI generates the adapter code, calculates the diff, and applies only the deltas on each run. - [Infrahub Sync](/sync.md): Infrahub Sync synchronizes infrastructure data between Infrahub and external systems — NetBox, Nautobot, IP Fabric, Slurp’it, Cisco ACI, Peering Manager, ServiceNow-style CMDBs, and any system with a REST/JSON API. Use it to migrate from a legacy system of record, run two systems side-by-side, or keep Infrahub in sync with another source of truth. Define a sync project declaratively in YAML, and the CLI generates the adapter code, calculates the diff, and applies only the deltas on each run. ### adapters - [Cisco ACI adapter](/sync/adapters/aci.md): What is Cisco ACI? - [Choose an adapter](/sync/adapters/choosing-an-adapter.md): Infrahub Sync includes adapters for the most common infrastructure systems and a Generic REST API adapter for everything else. For systems with non-standard APIs, build a custom adapter. - [Device42 adapter](/sync/adapters/device42.md): What is Device42? - [GenericRestAPI adapter](/sync/adapters/genericrestapi.md): The GenericRestAPI adapter is a flexible, configurable adapter that can connect to any REST API following common patterns. It's designed to reduce code duplication and provide a foundation for creating adapters for new systems without having to build them from scratch. - [Infrahub adapter](/sync/adapters/infrahub.md): What is Infrahub? - [IP Fabric adapter](/sync/adapters/ipfabric.md): What is IP Fabric? - [LibreNMS adapter](/sync/adapters/librenms.md): What is LibreNMS? - [Local Adapters](/sync/adapters/local-adapters.md): Using local adapters - [Nautobot adapter](/sync/adapters/nautobot.md): What is Nautobot? - [NetBox adapter](/sync/adapters/netbox.md): What is NetBox? - [Observium adapter](/sync/adapters/observium.md): What is Observium? - [Peering Manager adapter](/sync/adapters/peering-manager.md): What is Peering Manager? - [PeeringDB adapter](/sync/adapters/peeringdb.md): What is PeeringDB? - [Prometheus adapter](/sync/adapters/prometheus.md): What is Prometheus? - [Slurp’it adapter](/sync/adapters/slurpit.md): What is Slurp’it? ### contributing This guide covers how to set up a development environment for infrahub-sync and contribute to the project. For the release runbook, see RELEASING.md at the repository root — that's maintainer-only. - [Contributing](/sync/contributing.md): This guide covers how to set up a development environment for infrahub-sync and contribute to the project. For the release runbook, see RELEASING.md at the repository root — that's maintainer-only. ### creating-a-sync-project A sync project is a directory containing a config.yml file that defines one synchronization between two systems. Configure four parts: source and destination, sync order, schema mapping, and sync behavior. A Nautobot → Infrahub example runs through each. - [Create a sync project](/sync/creating-a-sync-project.md): A sync project is a directory containing a config.yml file that defines one synchronization between two systems. Configure four parts: source and destination, sync order, schema mapping, and sync behavior. A Nautobot → Infrahub example runs through each. ### custom-certificates For sync sources or destinations that use TLS certificates signed by an internal CA — common in enterprise networks — install the CA in the system trust store, then point Python's HTTP client at that store. - [Use custom CA certificates](/sync/custom-certificates.md): For sync sources or destinations that use TLS certificates signed by an internal CA — common in enterprise networks — install the CA in the system trust store, then point Python's HTTP client at that store. ### installation Infrahub Sync is available on PyPI and can be installed using the pip package installer. It is recommended to install the Sync into a virtual environment. - [Install Infrahub Sync](/sync/installation.md): Infrahub Sync is available on PyPI and can be installed using the pip package installer. It is recommended to install the Sync into a virtual environment. ### migrating-from-netbox-or-nautobot Migrate data from NetBox or Nautobot into Infrahub one model at a time. The existing system keeps running throughout, and you decide when — or whether — to retire it. - [Migrate from NetBox or Nautobot](/sync/migrating-from-netbox-or-nautobot.md): Migrate data from NetBox or Nautobot into Infrahub one model at a time. The existing system keeps running throughout, and you decide when — or whether — to retire it. ### orchestration Infrahub Sync runs as a single CLI command. Schedule it with whatever tooling already runs scheduled jobs in your environment — cron, CI, Prefect, Dagster, or a homegrown runner. - [Schedule sync runs](/sync/orchestration.md): Infrahub Sync runs as a single CLI command. Schedule it with whatever tooling already runs scheduled jobs in your environment — cron, CI, Prefect, Dagster, or a homegrown runner. ### reference - [Cache layout](/sync/reference/cache-layout.md): infrahub-sync diff and infrahub-sync apply persist run state under: - [infrahub-sync](/sync/reference/cli.md): Infrahub-sync: synchronize data between infrastructure sources and destinations. - [Sync instance configuration](/sync/reference/config.md): The configuration file allows you to define the resources needs for the sync. - [Incremental Extraction](/sync/reference/incremental-extraction.md): infrahub-sync can skip re-extracting unchanged data on warm runs by - [Schema mapping reference](/sync/reference/schema-mapping.md): The schema mapping section of a sync project's config.yml defines how data translates between the source system and the destination system. Worked examples for NetBox → Infrahub and Nautobot → Infrahub appear at the end. ### release-notes - [Release Notes](/sync/release-notes.md) - [Infrahub Sync](/sync/release-notes/infrahub-sync.md) - [Release 1.5.6](/sync/release-notes/infrahub-sync/release-1_5_6.md): Release Number - [Release 1.6.0](/sync/release-notes/infrahub-sync/release-1_6_0.md): Release Number - [Release 2.0.0](/sync/release-notes/infrahub-sync/release-2_0_0.md): Release Number - [Release 2.0.1](/sync/release-notes/infrahub-sync/release-2_0_1.md): Release Number ### running-a-sync Learn how to use Infrahub Sync's commands to calculate differences, synchronize data, and apply previously cached plans against your destination. - [Run a sync](/sync/running-a-sync.md): Learn how to use Infrahub Sync's commands to calculate differences, synchronize data, and apply previously cached plans against your destination. ### tutorials - [Sync NetBox to Infrahub](/sync/tutorials/netbox-demo-to-infrahub.md): Set up a local Infrahub instance, load a data model, and synchronize infrastructure data from the public NetBox demo. ### using-netbox-or-nautobot-with-infrahub If you're adopting Infrahub but already have an established system of record in NetBox or Nautobot — with accumulated data, custom fields, and automation built around it — run Infrahub side-by-side with the existing tool and use Infrahub Sync to keep both systems holding the same data. - [Use NetBox or Nautobot with Infrahub](/sync/using-netbox-or-nautobot-with-infrahub.md): If you're adopting Infrahub but already have an established system of record in NetBox or Nautobot — with accumulated data, custom fields, and automation built around it — run Infrahub side-by-side with the existing tool and use Infrahub Sync to keep both systems holding the same data. ## vscode Infrahub VSCode extension - your development companion for infrastructure automation - [VSCode Extension](/vscode.md): Infrahub VSCode extension - your development companion for infrastructure automation ### guides - [How to Configure Multiple Infrahub Servers](/vscode/guides/configure-multiple-servers.md): Set up connections to development, staging, and production Infrahub servers for seamless environment switching - [How to Execute GraphQL Queries](/vscode/guides/execute-graphql-queries.md): Run GraphQL queries against Infrahub servers with variable support and branch selection - [How to Manage Branches](/vscode/guides/manage-branches.md): Create, delete, and work with Infrahub branches directly from VSCode - [How to Run Transforms and Artifacts](/vscode/guides/running-transforms.md): Execute Jinja2 and Python transforms directly from VSCode with automatic command selection and variable support - [How to use Infrahub snippets in VSCode](/vscode/guides/snippets.md): Step-by-step guide to inserting and customizing Infrahub YAML and automation snippets in Visual Studio Code - [How to Visualize Your Schema](/vscode/guides/visualize-schema.md): Explore and understand your Infrahub schema structure using the interactive graph visualizer ### reference - [Extension Commands and Settings Reference](/vscode/reference/commands-settings.md): Complete reference for all commands, settings, and configuration options in the Infrahub VSCode extension ### release-notes Releases and changes to infrahub-vscode. - [Release notes](/vscode/release-notes.md): Releases and changes to infrahub-vscode. ### topics - [Understanding the Extension Architecture](/vscode/topics/extension-architecture.md): Deep dive into how the Infrahub VSCode extension is designed and how its components work together - [Schema Validation and YAML Intelligence](/vscode/topics/schema-validation.md): Understanding how the extension provides intelligent YAML editing and schema validation for Infrahub - [Security Configuration and Best Practices](/vscode/topics/security-configuration.md): Comprehensive guide to security settings, TLS configuration, and best practices for the Infrahub VSCode extension ### tutorials - [Getting Started with Infrahub VSCode Extension](/vscode/tutorials/getting-started.md): Learn how to install and configure the Infrahub VSCode extension for your first infrastructure automation project ## artifact-file-storage ### configure The storage API provides direct access to Infrahub's object storage layer for uploading and retrieving content by identifier. - [Configure storage](/artifact-file-storage/configure.md): The storage API provides direct access to Infrahub's object storage layer for uploading and retrieving content by identifier. ### overview Infrahub uses an object storage layer to persist binary and text content outside of the graph database. This layer stores the raw bytes of file objects and rendered artifacts. Separating file content from graph data allows Infrahub to keep the graph database focused on relationships, metadata, and version control while delegating bulk storage to a system optimized for that purpose. - [About storage](/artifact-file-storage/overview.md): Infrahub uses an object storage layer to persist binary and text content outside of the graph database. This layer stores the raw bytes of file objects and rendered artifacts. Separating file content from graph data allows Infrahub to keep the graph database focused on relationships, metadata, and version control while delegating bulk storage to a system optimized for that purpose. ## artifacts ### content-composition This guide shows you how to build a composite artifact whose Transformation pulls in content from other artifacts or file objects. This enables modular configuration pipelines where each artifact generates one section of a configuration, and a composite artifact assembles the final result. - [Composing artifact content](/artifacts/content-composition.md): This guide shows you how to build a composite artifact whose Transformation pulls in content from other artifacts or file objects. This enables modular configuration pipelines where each artifact generates one section of a configuration, and a composite artifact assembles the final result. ### overview An artifact is the result of a Transformation for a specific context and/or object. - [Artifacts](/artifacts/overview.md): An artifact is the result of a Transformation for a specific context and/or object. ### use Generate configuration files and other artifacts by combining Infrahub data with templates. This guide shows you how to create artifacts that automatically update when your infrastructure data changes. - [Use artifacts](/artifacts/use.md): Generate configuration files and other artifacts by combining Infrahub data with templates. This guide shows you how to create artifacts that automatically update when your infrastructure data changes. ## automation-and-outputs - [Design & Integrate](/automation-and-outputs.md) ## branches-and-change-control - [Branches & Change Control](/branches-and-change-control.md) ## branches ### branch-agnostic-data A branch-agnostic attribute or relationship on a branch-aware object stores its value once and shares that single value with every branch, instead of keeping a copy per branch. Deleting the object that holds such a field on one branch therefore does not release the value — the object may still be readable on another branch, and its branch-agnostic fields must remain readable with it. - [Branch-agnostic data](/branches/branch-agnostic-data.md): A branch-agnostic attribute or relationship on a branch-aware object stores its value once and shares that single value with every branch, instead of keeping a copy per branch. Deleting the object that holds such a field on one branch therefore does not release the value — the object may still be readable on another branch, and its branch-agnostic fields must remain readable with it. ### create Start a new branch from the default branch (typically main or master). When you query the new branch, Infrahub combines two things no data is duplicated, and Infrahub stores only the branchedfrom timestamp and the changes made on the branch. - [Create a branch](/branches/create.md): Start a new branch from the default branch (typically main or master). When you query the new branch, Infrahub combines two things no data is duplicated, and Infrahub stores only the branchedfrom timestamp and the changes made on the branch. ### delete After a branch has served its purpose — whether it's been merged, abandoned, or superseded — it can be deleted. Deleting a branch that has not been merged will permanently discard all changes accumulated on it. - [Delete a branch](/branches/delete.md): After a branch has served its purpose — whether it's been merged, abandoned, or superseded — it can be deleted. Deleting a branch that has not been merged will permanently discard all changes accumulated on it. ### merge When the changes on a branch are complete, you merge them into the default branch through a Proposed Change, where the checks run and reviewers approve the change before the merge. You can also merge a branch directly, with Merge on the branch details page or the BranchMerge mutation. A direct merge runs the same conflict and constraint checks and skips the Proposed Change pipeline. - [Merge a branch](/branches/merge.md): When the changes on a branch are complete, you merge them into the default branch through a Proposed Change, where the checks run and reviewers approve the change before the merge. You can also merge a branch directly, with Merge on the branch details page or the BranchMerge mutation. A direct merge runs the same conflict and constraint checks and skips the Proposed Change pipeline. ### overview Infrahub's branching model allows teams to work on features, fixes, or experiments in isolated environments. Each branch represents a separate line of development, enabling parallel work streams without interference. Unlike traditional version control systems, Infrahub's approach combines the familiar Git branching concepts with the unique data management capabilities of its graph database foundation. - [Branches](/branches/overview.md): Infrahub's branching model allows teams to work on features, fixes, or experiments in isolated environments. Each branch represents a separate line of development, enabling parallel work streams without interference. Unlike traditional version control systems, Infrahub's approach combines the familiar Git branching concepts with the unique data management capabilities of its graph database foundation. ### parallel-branches Several teams or Generators can work on separate branches at the same time. When you query one of those branches, Infrahub returns the default branch's data as of that branch's branched_from, plus the changes made on that branch. Merging one branch into the default branch changes nothing on the others, and no status indicates that the default branch has changed, so Infrahub reports conflicts and duplicate values only when it compares a branch with the default branch again: when you refresh the branch's diff, run its Proposed Change checks, rebase it or merge it. - [Parallel branches](/branches/parallel-branches.md): Several teams or Generators can work on separate branches at the same time. When you query one of those branches, Infrahub returns the default branch's data as of that branch's branched_from, plus the changes made on that branch. Merging one branch into the default branch changes nothing on the others, and no status indicates that the default branch has changed, so Infrahub reports conflicts and duplicate values only when it compares a branch with the default branch again: when you refresh the branch's diff, run its Proposed Change checks, rebase it or merge it. ### rebase A rebase brings a branch up to date with the default branch. Afterwards, a query on the branch returns the default branch's current data together with the branch's own changes. Rebase before you open a Proposed Change, and again after another branch merges into the default branch. - [Rebase a branch](/branches/rebase.md): A rebase brings a branch up to date with the default branch. Afterwards, a query on the branch returns the default branch's current data together with the branch's own changes. Rebase before you open a Proposed Change, and again after another branch merges into the default branch. ### resolve-conflicts A conflict occurs when the same data changed on a branch and on the default branch after the branch's branched_from. - [Resolve conflicts](/branches/resolve-conflicts.md): A conflict occurs when the same data changed on a branch and on the default branch after the branch's branched_from. ## category ### advanced-schema-features - [Advanced schema features](/category/advanced-schema-features.md) ### authentication - [Authentication](/category/authentication.md) ### configuration-files - [Configuration Files](/category/configuration-files.md) ### display--presentation - [Display & presentation](/category/display--presentation.md) ### install--configure - [Install & configure](/category/install--configure.md) ### maintain--upgrade - [Maintain & upgrade](/category/maintain--upgrade.md) ### permissions - [Permissions](/category/permissions.md) ### run--observe - [Run & observe](/category/run--observe.md) ### schema-operations - [Schema operations](/category/schema-operations.md) ### user-management--security - [User Management & Security](/category/user-management--security.md) ## change-approval ### change-approval-workflow This guide walks you through implementing a change approval workflow in Infrahub. By the end, you'll have a structured process ensuring all infrastructure changes are properly reviewed and approved before being merged into production, enhancing your governance and safety practices. - [How to implement a change approval workflow](/change-approval/change-approval-workflow.md): This guide walks you through implementing a change approval workflow in Infrahub. By the end, you'll have a structured process ensuring all infrastructure changes are properly reviewed and approved before being merged into production, enhancing your governance and safety practices. ## checks ### overview Checks are user-defined logic, stored in an external repository linked to Infrahub, that run as part of a proposed change. They let users perform any kind of data validation logic during a proposed change. If a check does not complete successfully, the proposed change cannot be merged. - [Checks & Validation](/checks/overview.md): Checks are user-defined logic, stored in an external repository linked to Infrahub, that run as part of a proposed change. They let users perform any kind of data validation logic during a proposed change. If a check does not complete successfully, the proposed change cannot be merged. ## computed-attributes ### overview What a computed attribute is, when to use it, and how Infrahub recalculates it as your data changes. - [Computed attributes](/computed-attributes/overview.md): What a computed attribute is, when to use it, and how Infrahub recalculates it as your data changes. ## deploy-manage ### install-configure - [How to configure Infrahub](/deploy-manage/install-configure/configure-infrahub.md): This guide explains how to configure your Infrahub instance by setting environment variables that control various aspects of the system, including timeouts, security settings, and integration parameters. - [Hardware requirements](/deploy-manage/install-configure/hardware-requirements.md): This page outlines the hardware requirements for running Infrahub, including minimum and recommended specifications, enterprise sizing, cloud provider machine types, task manager database storage, and a utility for benchmarking your system's performance. - [Install Infrahub Community](/deploy-manage/install-configure/install/community.md): Infrahub Community is deployed as a container-based architecture and can be installed using several methods. - [Install Infrahub Enterprise Enterprise Edition](/deploy-manage/install-configure/install/enterprise.md): Infrahub Enterprise is based on the Community version, with several enhancements for: - [Observability stack](/deploy-manage/install-configure/install/observability-stack.md): Infrahub ships an observability stack that runs alongside Infrahub: - [Installation](/deploy-manage/install-configure/install/overview.md): Infrahub Community and Enterprise are deployed as container-based architectures. The installation methods below are for non-resilient deployments suitable for development, testing, and single-node production environments. - [Tune performance](/deploy-manage/install-configure/performance-tuning.md): Infrahub's defaults target a general-purpose deployment. As an instance grows — more objects in the database, more open branches, more automation — some of those defaults stop matching the workload. The settings below are the ones worth revisiting, each with the symptom it addresses and what you give up in exchange. - [High availability](/deploy-manage/install-configure/production-deployment/high-availability.md): This guide covers how to deploy Infrahub in a high availability configuration that eliminates single points of failure. - [Production deployment](/deploy-manage/install-configure/production-deployment/overview.md): This guide walks you through deploying Infrahub in a production environment with enhanced security, reliability, and maintainability. By following these steps, you'll set up a production-ready Infrahub instance that follows industry best practices. - [Trust a private CA](/deploy-manage/install-configure/production-deployment/private-ca.md): This guide explains how to make Infrahub trust certificates issued by your organization's private certificate authority (CA). Once configured, every outbound TLS connection Infrahub opens, such as cloning a repository from an internal Git server, calling a webhook, reaching an SSO provider, or connecting to the database, the message broker and S3 object storage, trusts your CA without rebuilding the Infrahub Docker image. ### maintain-upgrade - [Backup and restore](/deploy-manage/maintain-upgrade/database-backup/backup-and-restore.md): This guide shows you how to create comprehensive backups of your Infrahub deployment and restore them when needed. You'll learn to backup the Neo4j graph database, object storage, and task management data to ensure complete data recovery capabilities. - [Cluster backup and restore Enterprise Edition](/deploy-manage/maintain-upgrade/database-backup/cluster-backup-and-restore.md): If you're running Infrahub with a Neo4j cluster, follow these steps to backup from one node and restore to another while maintaining cluster integrity. - [Understanding database backup and restore](/deploy-manage/maintain-upgrade/database-backup/overview.md): This topic explains how Infrahub's database backup and restore system works, the architectural decisions behind it, and the various approaches available for protecting your data. Understanding these concepts helps you make informed decisions about your backup strategy and troubleshoot issues when they arise. - [Upgrade Community](/deploy-manage/maintain-upgrade/upgrade/community.md): The process to migrate your instance of Infrahub to the latest version will vary depending on your deployment of Infrahub. However, at a high-level, it will involve getting the latest version and performing any needed Database Migrations and Schema updates. - [Upgrade Enterprise Enterprise Edition](/deploy-manage/maintain-upgrade/upgrade/enterprise.md): The process to migrate your instance of Infrahub Enterprise to the latest version will vary depending on your deployment of Infrahub Enterprise. However, at a high-level, it will involve getting the latest version and performing any needed Database Migrations and Schema updates. - [Upgrade the observability stack](/deploy-manage/maintain-upgrade/upgrade/observability-stack.md): Docker Compose - [Upgrade](/deploy-manage/maintain-upgrade/upgrade/overview.md): Upgrading Infrahub involves pulling the latest container images, running database and schema migrations, and restarting services. The specific steps vary by edition (Community vs Enterprise) and deployment method (Docker Compose vs Helm). ### run-observe - [Activity log](/deploy-manage/run-observe/activity-log.md): Changes (events) in Infrahub are documented in the Activity log. It helps you see which objects were impacted, when a change was made, and who made it. It can be used to troubleshoot unforeseen changes, audit previous operations, and comprehend the order of updates across various branches. - [Configure log forwarding Enterprise Edition](/deploy-manage/run-observe/log-forwarding/configure-log-forwarding.md): This guide walks through configuring Infrahub to forward audit events and application logs to external SIEM or syslog systems. For conceptual background on how log forwarding works, see the log forwarding overview. - [Log forwarding Enterprise Edition](/deploy-manage/run-observe/log-forwarding/overview.md): Log forwarding enables Infrahub to stream audit events and application logs to external systems via the syslog protocol. This supports compliance, security monitoring, and operational visibility by integrating with SIEM platforms and centralized log management. - [Metrics](/deploy-manage/run-observe/metrics.md): Infrahub exposes Prometheus metrics from the API server and from each task worker. Use them to track API latency and errors, database load and lock contention. - [Tasks](/deploy-manage/run-observe/tasks.md): The Tasks system in Infrahub is designed to manage and control various backend operations with robust error reporting, improved supervision, and enhanced logging capabilities. - [Local telemetry storage](/deploy-manage/run-observe/telemetry.md): Infrahub stores a daily telemetry snapshot locally in the Neo4j database, regardless of whether remote telemetry reporting is enabled. This ensures all deployments - including air-gapped and opted-out environments - retain usage data for support, auditing, and license compliance. ### user-management - [Authentication](/deploy-manage/user-management/authentication.md): Infrahub provides flexible authentication options to fit various organizational needs. - [Advanced LDAP configuration Enterprise Edition](/deploy-manage/user-management/ldap/advanced-ldap.md): These options extend a working LDAP setup with directory group resolution, nested-group handling, server failover, and stricter TLS. Configure the connection and user lookup first — see Configure LDAP authentication. - [Configure LDAP authentication Enterprise Edition](/deploy-manage/user-management/ldap/configure-ldap.md): This guide explains how to connect Infrahub to your LDAP directory so users can sign in with their directory credentials. - [LDAP authentication Enterprise Edition](/deploy-manage/user-management/ldap/overview.md): With LDAP authentication, users sign in to Infrahub with the credentials from your existing directory — Active Directory, OpenLDAP, or any RFC 4510-compliant LDAP server. Use it when your organization manages identities in a central directory and does not run an OIDC or OAuth2 identity provider. - [Managing API tokens](/deploy-manage/user-management/managing-api-tokens.md): API tokens can be used as an authentication mechanism for Infrahub's REST- and GraphQL API, the Python SDK and infrahubctl. - [Managing preferences](/deploy-manage/user-management/managing-preferences.md): Infrahub stores per-user preferences that control aspects of the web interface and how it displays data. Preferences follow your account to any session or device, and — with the manageglobalpreferences permission — an administrator can set organisation-wide defaults for users who haven't set their own. - [Manage accounts and permissions](/deploy-manage/user-management/permissions-roles/manage-accounts-and-permissions.md): In Infrahub, managing access and control starts with creating accounts, assigning them to groups, and managing their roles and permissions. - [Permissions and roles](/deploy-manage/user-management/permissions-roles/overview.md): Roles and permissions are essential for controlling user access and behavior in Infrahub. Within the platform, they provide precise control over what users can see, modify, or manage. - [Advanced SSO configuration](/deploy-manage/user-management/sso/advanced-sso.md): Multiple identity providers - [Configure SSO (single sign-on)](/deploy-manage/user-management/sso/configure-sso.md): This guide walks you through configuring single sign-on (SSO) in Infrahub using OpenID Connect (OIDC) or OAuth2 authentication protocols. - [Single sign-on (SSO)](/deploy-manage/user-management/sso/overview.md): Single sign-on (SSO) allows users to authenticate once with an external identity provider and gain access to Infrahub without needing separate credentials. Infrahub integrates with popular identity providers — Microsoft Entra ID, Okta, Google Workspace, and others — through industry-standard protocols. ## deployment-and-management - [Deployment & Management](/deployment-and-management.md) ## development - [Contributing](/development.md) ### backend In order start developing on Infrahub backend, it is recommended to have a decent knowledge about topics such as Docker, Python and generally UNIX systems. Tools such as Docker and Python virtual environment help us in isolating the development work without interfering with the system itself. In this guide, we will use: - [Backend guide](/development/backend.md): In order start developing on Infrahub backend, it is recommended to have a decent knowledge about topics such as Docker, Python and generally UNIX systems. Tools such as Docker and Python virtual environment help us in isolating the development work without interfering with the system itself. In this guide, we will use: ### changelog Infrahub utilizes a tool called towncrier for Changelog management and generation. - [Changelog guide](/development/changelog.md): Infrahub utilizes a tool called towncrier for Changelog management and generation. ### docs Welcome to the Infrahub documentation guide. This document aims to answer any questions that may come up when creating or updating documentation. - [Documentation guide](/development/docs.md): Welcome to the Infrahub documentation guide. This document aims to answer any questions that may come up when creating or updating documentation. ### editor More details coming soon - [Visual Studio Code](/development/editor.md): More details coming soon ### frontend Welcome to the Infrahub frontend guide! This guide details the technologies and steps required to contribute effectively to the Infrahub frontend. - [Frontend guide](/development/frontend.md): Welcome to the Infrahub frontend guide! This guide details the technologies and steps required to contribute effectively to the Infrahub frontend. - [Getting set up with frontend](/development/frontend/getting-set-up.md): Make sure Infrahub Backend is up and running. If not, in your terminal execute: - [Running & writing tests for frontend](/development/frontend/testing-guidelines.md): If you have never run Infrahub tests before, we highly suggest following the frontend guide. ### git-best-practices This guide explains Git workflows and best practices when contributing to Infrahub, covering submodule management, branching strategies, and pull request workflows. - [How to work with Git when developing Infrahub](/development/git-best-practices.md): This guide explains Git workflows and best practices when contributing to Infrahub, covering submodule management, branching strategies, and pull request workflows. ### style-guide This guide defines writing style, capitalization, and grammar rules for Infrahub documentation. As a general rule, prefer consistency and simplicity when possible. For anything not answered below, reference the Microsoft Style Guide. - [Documentation style guide](/development/style-guide.md): This guide defines writing style, capitalization, and grammar rules for Infrahub documentation. As a general rule, prefer consistency and simplicity when possible. For anything not answered below, reference the Microsoft Style Guide. ## development-resources - [Development Resources](/development-resources.md) ### developer-guide Infrahub support various form of extensibility that rely on users providing their own code that then will be executed by Infrahub. - [Developer guide](/development-resources/developer-guide.md): Infrahub support various form of extensibility that rely on users providing their own code that then will be executed by Infrahub. ### graphql-fragments GraphQL fragments are reusable field selections that can be shared across multiple stored queries. Instead of duplicating the same nested field selections in every query, you define them once as a fragment and reference them using the standard GraphQL spread syntax (...fragmentName). - [Using GraphQL fragments](/development-resources/graphql-fragments.md): GraphQL fragments are reusable field selections that can be shared across multiple stored queries. Instead of duplicating the same nested field selections in every query, you define them once as a fragment and reference them using the standard GraphQL spread syntax (...fragmentName). ### graphql - [Working with groups](/development-resources/graphql/groups.md): Groups are first-class objects in Infrahub that can be queried and manipulated through GraphQL. Groups provide powerful ways to organize and operate on collections of infrastructure objects. - [GraphQL](/development-resources/graphql/overview.md): The GraphQL interface is the main interface to interact with Infrahub. The GraphQL schema is automatically generated based on the core models and the user-defined schema models. - [Queries & mutations](/development-resources/graphql/queries-and-mutations.md): In GraphQL, a query is used to fetch data and mutations are used to create/update or delete data. In Infrahub, a GraphQL query and 4 mutations will be generated for each model you define in the schema. The name of the query or mutation is based on the namespace and name of the model. - [Single-target queries](/development-resources/graphql/single-target-queries.md): When writing GraphQL queries for transformations, generators, artifacts, and computed attributes, it's critical to use a single-target query pattern to ensure proper tracking by the system. - [Stored queries](/development-resources/graphql/stored-queries.md): Infrahub can store GraphQL queries in the database to simplify execution and associate them with other internal objects such as Transformations. ### local-demo-environment A local environment based on Docker Compose is available for demo and testing. - [Local demo environment](/development-resources/local-demo-environment.md): A local environment based on Docker Compose is available for demo and testing. ### sbom A software bill of materials (SBOM) is a complete inventory of the components, libraries, and dependencies contained in a piece of software. SBOMs are a core building block for supply-chain security: they let you audit what ships inside an image, match it against vulnerability databases, and satisfy compliance requirements such as those described in the US Executive Order on cybersecurity. - [Image signing and SBOM](/development-resources/sbom.md): A software bill of materials (SBOM) is a complete inventory of the components, libraries, and dependencies contained in a piece of software. SBOMs are a core building block for supply-chain security: they let you audit what ships inside an image, match it against vulnerability databases, and satisfy compliance requirements such as those described in the US Executive Order on cybersecurity. ### testcontainers The infrahub-testcontainers package starts a complete Infrahub stack in Docker during your test session. Use it to write integration tests that validate schemas, SDK usage, or GraphQL queries against a live Infrahub instance. - [Integration testing with Testcontainers](/development-resources/testcontainers.md): The infrahub-testcontainers package starts a complete Infrahub stack in Docker during your test session. Use it to write integration tests that validate schemas, SDK usage, or GraphQL queries against a live Infrahub instance. ## events ### event-actions An event action is a node you create in Infrahub that defines an outcome: add a device to a group, run a Generator definition. Actions on their own do nothing — they fire only when an event rule matches and points at them. - [Event actions](/events/event-actions.md): An event action is a node you create in Infrahub that defines an outcome: add a device to a group, run a Generator definition. Actions on their own do nothing — they fire only when an event rule matches and points at them. ### event-rules An event rule is a node you create in Infrahub that names a set of conditions and ties one or more actions to fire when those conditions match. Rules turn raw events into useful automation: instead of reacting to every infrahub.node.updated event, you describe the precise update you care about — "an InfraDevice whose status changed to active" — and Infrahub runs your action only when that pattern shows up. - [Event rules](/events/event-rules.md): An event rule is a node you create in Infrahub that names a set of conditions and ties one or more actions to fire when those conditions match. Rules turn raw events into useful automation: instead of reacting to every infrahub.node.updated event, you describe the precise update you care about — "an InfraDevice whose status changed to active" — and Infrahub runs your action only when that pattern shows up. ### event-system Infrahub emits a structured event every time a significant mutation happens in the system: a node is created, updated, or deleted; a branch is created, merged, rebased, or deleted; a group gains or loses a member; and many more. Events are the foundation of every event-driven feature — automation, webhook delivery, the activity log, and external SIEM forwarding all consume them. - [Event system](/events/event-system.md): Infrahub emits a structured event every time a significant mutation happens in the system: a node is created, updated, or deleted; a branch is created, merged, rebased, or deleted; a group gains or loses a member; and many more. Events are the foundation of every event-driven feature — automation, webhook delivery, the activity log, and external SIEM forwarding all consume them. ### overview Infrahub emits events on every significant mutation in the system — node creates, branch operations, group membership changes, and more. The event system lets you react to those events automatically: when a device is updated, when a circuit joins a provisioning group, when a branch merges. Common uses include keeping groups in sync as data changes, triggering Generators on attribute updates, and notifying external systems through webhooks. - [Events](/events/overview.md): Infrahub emits events on every significant mutation in the system — node creates, branch operations, group membership changes, and more. The event system lets you react to those events automatically: when a device is updated, when a circuit joins a provisioning group, when a branch merges. Common uses include keeping groups in sync as data changes, triggering Generators on attribute updates, and notifying external systems through webhooks. ## faq Here are the key details about Infrahub: - [Frequently asked questions](/faq.md): Here are the key details about Infrahub: ## generators ### build A Generator queries data and creates new nodes and relationships from the result. The steps below cover how to create one. - [Build a generator](/generators/build.md): A Generator queries data and creates new nodes and relationships from the result. The steps below cover how to create one. ### modular A Generator reads data from Infrahub and creates new objects based on the result. A single Generator works well when the scope is contained: one input kind, one set of outputs, no intermediate dependencies. - [Modular Generators](/generators/modular.md): A Generator reads data from Infrahub and creates new objects based on the result. A single Generator works well when the scope is contained: one input kind, one set of outputs, no intermediate dependencies. ### modular-best-practices The patterns below come from real-world experience building and operating modular Generator cascades in Infrahub. They address problems that are not obvious until you have built a multi-layer cascade and run it in production. - [Best practices for modular Generators](/generators/modular-best-practices.md): The patterns below come from real-world experience building and operating modular Generator cascades in Infrahub. They address problems that are not obvious until you have built a multi-layer cascade and run it in production. ### overview A Generator is a generic plugin that queries data and creates new nodes and relationships based on the result. - [Generators](/generators/overview.md): A Generator is a generic plugin that queries data and creates new nodes and relationships based on the result. ### remove Removing a Generator involves two separate things: the Generator definition registered from .infrahub.yml, and the objects the Generator created in Infrahub. Removing the definition stops the Generator from running, but it does not delete the objects it already created — those stay in Infrahub until you remove them. - [Remove a generator](/generators/remove.md): Removing a Generator involves two separate things: the Generator definition registered from .infrahub.yml, and the objects the Generator created in Infrahub. Removing the definition stops the Generator from running, but it does not delete the objects it already created — those stay in Infrahub until you remove them. ## git-integration ### branch-synchronization Infrahub automatically creates all branches from a connected Git repository by default. While this ensures full visibility, it can create unnecessary noise when many Git branches are unrelated to Infrahub data or workflows. Selective branch synchronization introduces an optional configuration that allows teams to control which Git branches are imported and synchronized into Infrahub based on custom naming patterns. - [Selective branch synchronization](/git-integration/branch-synchronization.md): Infrahub automatically creates all branches from a connected Git repository by default. While this ensures full visibility, it can create unnecessary noise when many Git branches are unrelated to Infrahub data or workflows. Selective branch synchronization introduces an optional configuration that allows teams to control which Git branches are imported and synchronized into Infrahub based on custom naming patterns. ### connect-repository Connecting an external Git repository will enable many features in Infrahub, such as Transformations, Generators, Checks ... that rely on the repository to store code files. - [How to connect external Git repositories](/git-integration/connect-repository.md): Connecting an external Git repository will enable many features in Infrahub, such as Transformations, Generators, Checks ... that rely on the repository to store code files. ### develop-changes Change the schemas, objects, Transformations, Generators, and other .infrahub.yml content an instance imports from a read-only repository, and land the change on the instance's main safely. This is the recommended workflow for a single instance; promoting a change across environments builds on it — see promote changes between environments. - [Develop changes from a Git repository](/git-integration/develop-changes.md): Change the schemas, objects, Transformations, Generators, and other .infrahub.yml content an instance imports from a read-only repository, and land the change on the instance's main safely. This is the recommended workflow for a single instance; promoting a change across environments builds on it — see promote changes between environments. ### infrahub-yml The .infrahub.yml file serves as the central manifest that defines how Infrahub integrates with external Git repositories. This topic explains the role of this configuration file and the design philosophy behind its structure. - [Understanding the .infrahub.yml configuration file](/git-integration/infrahub-yml.md): The .infrahub.yml file serves as the central manifest that defines how Infrahub integrates with external Git repositories. This topic explains the role of this configuration file and the design philosophy behind its structure. ### multi-environment Run a separate Infrahub instance for each environment — development, staging, production — from one Git repository. Each instance reads its schemas, objects, and automation from a read-only repository pinned to one long-lived branch. To move a change from one environment to the next, merge it into the next branch on your Git host, then trigger an import on the target instance. - [Multiple environments from a single repository](/git-integration/multi-environment.md): Run a separate Infrahub instance for each environment — development, staging, production — from one Git repository. Each instance reads its schemas, objects, and automation from a read-only repository pinned to one long-lived branch. To move a change from one environment to the next, merge it into the next branch on your Git host, then trigger an import on the target instance. ### overview Connect an external Git repository to keep the code that drives Infrahub — schemas, Transformations, Generators, checks, GraphQL queries, and artifact definitions — under version control, next to your infrastructure data. Infrahub imports that code and keeps it in sync as the repository changes. - [Git Integration](/git-integration/overview.md): Connect an external Git repository to keep the code that drives Infrahub — schemas, Transformations, Generators, checks, GraphQL queries, and artifact definitions — under version control, next to your infrastructure data. Infrahub imports that code and keeps it in sync as the repository changes. ### promote-between-environments Run a separate Infrahub instance for each environment from one Git repository, and move changes from one environment to the next. This guide covers the promotion — taking a change that is already developed on one environment and landing it on the next. To develop and land a change on a single instance, see develop changes from a Git repository; for the concepts, see multiple environments from a single repository. - [Promote changes between environments](/git-integration/promote-between-environments.md): Run a separate Infrahub instance for each environment from one Git repository, and move changes from one environment to the next. This guide covers the promotion — taking a change that is already developed on one environment and landing it on the next. To develop and land a change on a single instance, see develop changes from a Git repository; for the concepts, see multiple environments from a single repository. ## graph-traversal ### analyze-dependencies Use Dependency mode to find every object of a given kind that is reachable from a source object. - [Analyze dependencies](/graph-traversal/analyze-dependencies.md): Use Dependency mode to find every object of a given kind that is reachable from a source object. ### overview Use Graph Traversal to navigate the relationships in your infrastructure data — trace every path - [Graph Traversal](/graph-traversal/overview.md): Use Graph Traversal to navigate the relationships in your infrastructure data — trace every path ### query-with-graphql Both Graph Traversal modes are available programmatically — as GraphQL queries - [Query traversal with GraphQL](/graph-traversal/query-with-graphql.md): Both Graph Traversal modes are available programmatically — as GraphQL queries ### trace-a-path Use Path mode to find the paths between two objects in your infrastructure graph. - [Trace a path](/graph-traversal/trace-a-path.md): Use Path mode to find the paths between two objects in your infrastructure graph. ## groups ### add-members Attach existing objects to a Standard group. - [Add members to a group](/groups/add-members.md): Attach existing objects to a Standard group. ### create Create a Standard group when you want to hand-pick the objects it contains. - [Create a group](/groups/create.md): Create a Standard group when you want to hand-pick the objects it contains. ### delete Remove a group without affecting its member objects. - [Delete a group](/groups/delete.md): Remove a group without affecting its member objects. ### overview Groups are containers that establish relationships between objects in your infrastructure. They let you create logical collections that span different object types — you might group together devices, locations, and configurations that share a common purpose or characteristic. - [Groups](/groups/overview.md): Groups are containers that establish relationships between objects in your infrastructure. They let you create logical collections that span different object types — you might group together devices, locations, and configurations that share a common purpose or characteristic. ### query-members Read what's in a group, or find what groups an object belongs to. Use these patterns for auditing, verification, or feeding automation. - [Query group membership](/groups/query-members.md): Read what's in a group, or find what groups an object belongs to. Use these patterns for auditing, verification, or feeding automation. ### remove-members Detach objects from a Standard group without deleting the objects themselves. - [Remove members from a group](/groups/remove-members.md): Detach objects from a Standard group without deleting the objects themselves. ### use-in-automation Target a group from an artifact definition, Transformation, or Check so that the automation applies to every member without hard-coding a list. - [Use groups in automation](/groups/use-in-automation.md): Target a group from an artifact definition, Transformation, or Check so that the automation applies to every member without hard-coding a list. ## immutable-history ### overview Infrahub preserves previous values and relationships as your infrastructure data changes. Earlier versions remain available for queries, so you can inspect what existed at a specific time, compare changes across a period, and trace how an object or relationship changed. - [Immutable history](/immutable-history/overview.md): Infrahub preserves previous values and relationships as your infrastructure data changes. Earlier versions remain available for queries, so you can inspect what existed at a specific time, compare changes across a period, and trace how an object or relationship changed. ### query-historical-data You can read infrastructure data as it existed at previous points in time, and compare how it changed between them. A timestamped query answers what current data cannot: which devices and interfaces existed for a site during last night's incident, which interface attributes changed between the last known-good time and now, or which prefixes were assigned to a site on a given date. - [Query historical data](/immutable-history/query-historical-data.md): You can read infrastructure data as it existed at previous points in time, and compare how it changed between them. A timestamped query answers what current data cannot: which devices and interfaces existed for a site during last night's incident, which interface attributes changed between the last known-good time and now, or which prefixes were assigned to a site on a given date. ## integrations-overview - [Integrations](/integrations-overview.md) ## ipam ### allocate-ips-and-prefixes When to allocate from a pool - [Allocate IPs and prefixes](/ipam/allocate-ips-and-prefixes.md): When to allocate from a pool ### build-your-ipam-schema Infrahub includes the IpamNamespace node and the BuiltinIPNamespace, BuiltinIPPrefix, and BuiltinIPAddress generics by default — but no concrete IP prefix or address node until you load one. - [Build your IPAM schema](/ipam/build-your-ipam-schema.md): Infrahub includes the IpamNamespace node and the BuiltinIPNamespace, BuiltinIPPrefix, and BuiltinIPAddress generics by default — but no concrete IP prefix or address node until you load one. ### overview Use Infrahub IPAM to manage IP prefixes, IP addresses, and namespaces alongside the rest of your infrastructure data. Prefixes and addresses are ordinary Infrahub objects, so you can add relationships to devices, interfaces, and services the same way you would on any other node. Infrahub computes hierarchy automatically and calculates utilization on read. Every change is branch-aware. Both IPv4 and IPv6 are supported. - [IP Address Management](/ipam/overview.md): Use Infrahub IPAM to manage IP prefixes, IP addresses, and namespaces alongside the rest of your infrastructure data. Prefixes and addresses are ordinary Infrahub objects, so you can add relationships to devices, interfaces, and services the same way you would on any other node. Infrahub computes hierarchy automatically and calculates utilization on read. Every change is branch-aware. Both IPv4 and IPv6 are supported. ### plan-changes-on-a-branch Use a branch to draft IP prefix and address changes, review exactly what will change, and merge once you're confident — the same version-control workflow Infrahub applies to the rest of your infrastructure data. - [Plan changes on a branch](/ipam/plan-changes-on-a-branch.md): Use a branch to draft IP prefix and address changes, review exactly what will change, and merge once you're confident — the same version-control workflow Infrahub applies to the rest of your infrastructure data. ### query-ipam-data Read the computed values on IP prefixes and addresses, or follow the hierarchy relationships. Use these patterns for reporting, automation, or verification. - [Query IPAM data](/ipam/query-ipam-data.md): Read the computed values on IP prefixes and addresses, or follow the hierarchy relationships. Use these patterns for reporting, automation, or verification. ### use-namespaces Use IP namespaces to isolate sets of IP prefixes and addresses within the same Infrahub instance — for example, to give each customer or business unit its own IP space, even when their ranges overlap. - [Use namespaces](/ipam/use-namespaces.md): Use IP namespaces to isolate sets of IP prefixes and addresses within the same Infrahub instance — for example, to give each customer or business unit its own IP space, even when their ranges overlap. ## learn ### tutorials - [Build a check in Infrahub](/learn/tutorials/build-a-check.md): By the end of this tutorial you will have built, deployed, and validated a custom check that enforces a naming convention on tags. You will set up sample data, write a GraphQL query, implement the check logic in Python, configure it in .infrahub.yml, deploy it via a connected Git repository, and verify it runs against a proposed change. - [Build your first schema](/learn/tutorials/build-your-first-schema.md): By the end of this tutorial you will have a working schema for network devices and interfaces, covering nodes, attributes, relationships, and generic abstractions. You'll load each version into a branch and verify the results. - [Build chained generators](/learn/tutorials/generators/build-chained-generators.md): By the end of this tutorial you will have wired two layers of modular Generators together — fabric → pod → rack — using a checksum attribute and Infrahub's event framework. You will have added a GeneratorTarget generic with a checksum attribute to your downstream node kinds, implemented a GeneratorMixin that writes the checksum to downstream targets as the last step of generate(), built downstream Generators that validate upstream completeness before doing any work, and created CoreGeneratorAction and CoreNodeTriggerRule objects so the chain runs automatically when an upstream layer finishes. You will leave with a concrete model of how a checksum makes Generator chaining idempotent — re-runs that produce the same output do not re-trigger the next layer. - [Build your first generator](/learn/tutorials/generators/build-your-first-generator.md): By the end of this tutorial you will have built a working Generator end-to-end: modeled two object kinds, written a GraphQL query, implemented a Python Generator class, registered it in .infrahub.yml, run it locally with infrahubctl, and verified it runs automatically as part of a proposed change. You will leave with a Widget and Resource schema loaded into Infrahub and a Generator that creates Resource objects from each Widget's count attribute. - [Organize objects with groups](/learn/tutorials/groups.md): By the end of this tutorial you will have created a group, added two objects to it, and queried the result end-to-end. You'll leave with a concrete mental model of how groups work and where to go next. - [Tutorials](/learn/tutorials/overview.md): The most direct way to learn a specific Infrahub workflow is to run a tutorial. Each one walks you through a real task end to end — modeling a schema, writing a check, building a Generator — against your own Infrahub instance, using the same GraphQL, Python, and schema snippets you'd write in production. You follow the steps directly in these docs, at your own pace, with no external platform involved. - [Build a Jinja2 Transformation](/learn/tutorials/transformations/build-a-jinja2-transformation.md): By the end of this tutorial you will have built a working Jinja2 Transformation end-to-end: loaded a small network-device schema, created a few sample devices, written a GraphQL query that filters by device name, written a Jinja template that renders a configuration snippet from the result, registered it in .infrahub.yml, tested it locally with infrahubctl render, added the repository to Infrahub, and called the render API. You'll leave with a deviceconfigtransform you can call against any device by name. - [Build a Python Transformation](/learn/tutorials/transformations/build-a-python-transformation.md): By the end of this tutorial you will have built a working Python Transformation end-to-end: loaded a small network-device schema, created a few sample devices, written a GraphQL query that filters by device name, implemented a DeviceConfigTransform Python class that returns a JSON object derived from the response, registered it in .infrahub.yml, tested it locally with infrahubctl transform, and called the Transformation via the REST API. You'll leave with both the raw-dictionary and SDK-converted patterns side by side so you can pick the one that fits the next Transformation you write. ## menu ### overview Infrahub lets you control the menu on the left side of the web interface. - [Menu customization](/menu/overview.md): Infrahub lets you control the menu on the left side of the web interface. ## object-templates ### allocate-resources-from-pools Object templates support automatic resource allocation. This guide extends the device and interface example from Use object templates to show how to wire a CoreIPAddressPool to the interface template so that IP addresses are allocated automatically on object creation. - [Allocate resources from pools](/object-templates/allocate-resources-from-pools.md): Object templates support automatic resource allocation. This guide extends the device and interface example from Use object templates to show how to wire a CoreIPAddressPool to the interface template so that IP addresses are allocated automatically on object creation. ### overview In many infrastructures, multiple instances of objects share a common structure. Consider network devices: we know in advance the port setup for a given model. When documenting this in our source of truth, repeatedly entering the same port details is both inefficient and error-prone. The Object Template feature allows you to create a reusable blueprint for any object. This blueprint can be used to generate multiple instances that adhere to the predefined structure, ensuring uniformity while reducing manual effort. - [Object Templates](/object-templates/overview.md): In many infrastructures, multiple instances of objects share a common structure. Consider network devices: we know in advance the port setup for a given model. When documenting this in our source of truth, repeatedly entering the same port details is both inefficient and error-prone. The Object Template feature allows you to create a reusable blueprint for any object. This blueprint can be used to generate multiple instances that adhere to the predefined structure, ensuring uniformity while reducing manual effort. ### use This guide provides a structured approach to defining an object template and creating object instances based on that template. - [Use object templates](/object-templates/use.md): This guide provides a structured approach to defining an object template and creating object instances based on that template. ### with-profiles When both generatetemplate and generateprofile are configured on a schema node, you can assign Profiles to templates to enable bulk configuration updates. Objects created from templates automatically inherit the Profiles assigned to those templates, allowing you to update values in bulk by modifying the Profile. - [Assign Profiles to a template](/object-templates/with-profiles.md): When both generatetemplate and generateprofile are configured on a schema node, you can assign Profiles to templates to enable bulk configuration updates. Objects created from templates automatically inherit the Profiles assigned to those templates, allowing you to update values in bulk by modifying the Profile. ## objects ### convert-object-kind Object conversion changes an existing object from one kind to another, keeping the attribute values and relationships that both kinds share. Convert a Layer 2 interface to Layer 3, or a read-only repository to a read-write one, and the object keeps its relationships to everything else. - [Object conversion](/objects/convert-object-kind.md): Object conversion changes an existing object from one kind to another, keeping the attribute values and relationships that both kinds share. Convert a Layer 2 interface to Layer 3, or a read-only repository to a read-write one, and the object keeps its relationships to everything else. ### create-objects There are three ways to add objects to Infrahub. Which one you need depends on how many objects you are creating and where their definition comes from: - [Create objects](/objects/create-objects.md): There are three ways to add objects to Infrahub. Which one you need depends on how many objects you are creating and where their definition comes from: ### import-from-csv Prompt an AI coding assistant to translate a CSV or TSV export into Infrahub object YAML, then load it the same way as any other object file. - [Import data from CSV](/objects/import-from-csv.md): Prompt an AI coding assistant to translate a CSV or TSV export into Infrahub object YAML, then load it the same way as any other object file. ### load-from-yaml An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema. It provides a declarative way to define and manage resources in your Infrahub instance. - [Object files](/objects/load-from-yaml.md): An Object file is a YAML file that allows you to manage data to be loaded in Infrahub based on your own custom schema. It provides a declarative way to define and manage resources in your Infrahub instance. ### manage-from-cli Use infrahubctl to query, create, update, and delete objects directly from your terminal. The commands accept any schema kind in your instance and can display results as a table, JSON, CSV, or YAML. - [Manage objects with infrahubctl](/objects/manage-from-cli.md): Use infrahubctl to query, create, update, and delete objects directly from your terminal. The commands accept any schema kind in your instance and can display results as a table, JSON, CSV, or YAML. ### metadata Data lineage - [Data lineage and metadata](/objects/metadata.md): Data lineage ### overview An object is a record stored in Infrahub that conforms to a schema node definition. If schema nodes are the blueprints, objects are the actual instances of data — a specific router, an interface, a BGP session, a rack. - [Objects](/objects/overview.md): An object is a record stored in Infrahub that conforms to a schema node definition. If schema nodes are the blueprints, objects are the actual instances of data — a specific router, an interface, a BGP session, a rack. ## overview A graph-based infrastructure data management platform with built-in version control, CI workflows, peer review, and API access. - [What is Infrahub](/overview.md): A graph-based infrastructure data management platform with built-in version control, CI workflows, peer review, and API access. ### architecture Infrahub's architecture combines graph database technology with Git-like version control to create a powerful platform for infrastructure management. This topic explains the core components, design principles, and how they work together to deliver a unified infrastructure management solution. - [Understanding Infrahub's architecture](/overview/architecture.md): Infrahub's architecture combines graph database technology with Git-like version control to create a powerful platform for infrastructure management. This topic explains the core components, design principles, and how they work together to deliver a unified infrastructure management solution. ### build-with-ai Describe the network you want to model and have your assistant build the Infrahub schema, automation, and queries that represent it. - [Build with AI](/overview/build-with-ai.md): Describe the network you want to model and have your assistant build the Infrahub schema, automation, and queries that represent it. - [Set up your AI assistant](/overview/build-with-ai/setup.md): Install the Infrahub Skills, connect the MCP server, and choose the combination that fits how you work. - [Work with your assistant](/overview/build-with-ai/working-with-ai.md): Decide when to describe a change directly and when to plan it first, and what to check in what your assistant produces. ### community-vs-enterprise Infrahub is available in two distinct editions designed to meet different organizational needs: Community Edition and Enterprise Edition. This topic explains the differences between these editions to help you choose the right version for your infrastructure management needs. - [Understanding Infrahub community vs enterprise](/overview/community-vs-enterprise.md): Infrahub is available in two distinct editions designed to meet different organizational needs: Community Edition and Enterprise Edition. This topic explains the differences between these editions to help you choose the right version for your infrastructure management needs. ### concepts Core principles behind Infrahub — flexible schemas, version control, Transformations, Generators, and design-driven automation. - [Key Concepts](/overview/concepts.md): Core principles behind Infrahub — flexible schemas, version control, Transformations, Generators, and design-driven automation. ### explore See Infrahub in action through the sandbox, interactive labs, videos, and demos. - [Explore Infrahub](/overview/explore.md): See Infrahub in action through the sandbox, interactive labs, videos, and demos. ### next-steps Turn your local Infrahub setup into a proof of concept for your organization. - [Next Steps](/overview/next-steps.md): Turn your local Infrahub setup into a proof of concept for your organization. ### quickstart Set up a local Infrahub instance, load a data model, create infrastructure data, and explore branching. - [Quick Start](/overview/quickstart.md): Set up a local Infrahub instance, load a data model, create infrastructure data, and explore branching. ## profiles ### assign When creating or updating an object, reference a Profile by HFID. The object inherits the Profile's values for any attributes you don't set explicitly. - [Assign a Profile to an object](/profiles/assign.md): When creating or updating an object, reference a Profile by HFID. The object inherits the Profile's values for any attributes you don't set explicitly. ### create Define a reusable set of attribute values for a Profile-enabled node type. - [Create a Profile](/profiles/create.md): Define a reusable set of attribute values for a Profile-enabled node type. ### override-values When a Profile-assigned object should differ for a specific field, set the value explicitly when creating or updating the object. Explicit values take precedence over Profile values; other attributes still inherit from the Profile. - [Override specific Profile values](/profiles/override-values.md): When a Profile-assigned object should differ for a specific field, set the value explicitly when creating or updating the object. Explicit values take precedence over Profile values; other attributes still inherit from the Profile. ### overview This topic explains the concept of Profiles in Infrahub, their purpose in the system architecture, and how they enable configuration consistency across your infrastructure. You'll gain a deeper understanding of Profile inheritance, priority mechanisms, and the design decisions behind this feature. - [Profiles](/profiles/overview.md): This topic explains the concept of Profiles in Infrahub, their purpose in the system architecture, and how they enable configuration consistency across your infrastructure. You'll gain a deeper understanding of Profile inheritance, priority mechanisms, and the design decisions behind this feature. ### priority-and-inheritance When an object has one or more Profiles assigned, Infrahub uses a deterministic process to decide which value applies to each attribute or relationship. This page explains both the inheritance flow and the priority system that resolves conflicts when multiple Profiles apply. - [Priority and inheritance](/profiles/priority-and-inheritance.md): When an object has one or more Profiles assigned, Infrahub uses a deterministic process to decide which value applies to each attribute or relationship. This page explains both the inheritance flow and the priority system that resolves conflicts when multiple Profiles apply. ### update Change Profile values; all objects assigned to the Profile inherit the change automatically. Objects that have explicitly overridden the attribute keep their override — only objects relying on the Profile value see the change. - [Update a Profile](/profiles/update.md): Change Profile values; all objects assigned to the Profile inherit the change automatically. Objects that have explicitly overridden the attribute keep their override — only objects relying on the Profile value see the change. ### use-multiple A single object can be assigned multiple Profiles. When multiple Profiles define the same attribute, the profile_priority value (lower number = higher priority) determines which Profile's value wins. - [Use multiple Profiles](/profiles/use-multiple.md): A single object can be assigned multiple Profiles. When multiple Profiles define the same attribute, the profile_priority value (lower number = higher priority) determines which Profile's value wins. ## proposed-changes ### lifecycle Proposed changes follow a workflow with specific states that track progression from initial creation to final resolution. - [Lifecycle and state transitions](/proposed-changes/lifecycle.md): Proposed changes follow a workflow with specific states that track progression from initial creation to final resolution. ### overview A proposed change in Infrahub is a structured workflow mechanism that enables teams to review, discuss, and merge changes in a controlled and collaborative manner. It serves as the primary method for implementing infrastructure changes safely while maintaining proper oversight and governance. - [Proposed Changes](/proposed-changes/overview.md): A proposed change in Infrahub is a structured workflow mechanism that enables teams to review, discuss, and merge changes in a controlled and collaborative manner. It serves as the primary method for implementing infrastructure changes safely while maintaining proper oversight and governance. ### resolve-conflict When a proposed change has data conflicts between its source and target branches, Infrahub blocks the merge to protect the integrity of your infrastructure data. Conflicts are resolved during the review process, before the change can be approved and merged. - [Resolve a proposed-change conflict](/proposed-changes/resolve-conflict.md): When a proposed change has data conflicts between its source and target branches, Infrahub blocks the merge to protect the integrity of your infrastructure data. Conflicts are resolved during the review process, before the change can be approved and merged. ### review-and-stamp The review process gives team members structured ways to evaluate a proposed change, comment on specific elements, and ultimately stamp it as approved or rejected. - [Review and stamp](/proposed-changes/review-and-stamp.md): The review process gives team members structured ways to evaluate a proposed change, comment on specific elements, and ultimately stamp it as approved or rejected. ## reference - [Reference](/reference.md) ### configuration Configuration options for Infrahub - [Infrahub configuration](/reference/configuration.md): Configuration options for Infrahub ### dotinfrahub The repository configuration file allows you to define multiple resources that need to be imported into Infrahub. - [Repository configuration file](/reference/dotinfrahub.md): The repository configuration file allows you to define multiple resources that need to be imported into Infrahub. ### error-catalogue Catalogue version: 1 — 14 codes - [Error Catalogue](/reference/error-catalogue.md): Catalogue version: 1 — 14 codes ### graph-traversal Reference for the InfrahubPathTraversal and InfrahubReachableNodes GraphQL queries. - [Graph Traversal reference](/reference/graph-traversal.md): Reference for the InfrahubPathTraversal and InfrahubReachableNodes GraphQL queries. ### infrahub-cli - [CLI](/reference/infrahub-cli.md) - [infrahub db](/reference/infrahub-cli/infrahub-db.md): Manage the graph in the database. - [infrahub dev](/reference/infrahub-cli/infrahub-dev.md): Usage: - [infrahub recover](/reference/infrahub-cli/infrahub-recover.md): Recover from failed operations. - [infrahub server](/reference/infrahub-cli/infrahub-server.md): Control the API Server. - [infrahub upgrade](/reference/infrahub-cli/infrahub-upgrade.md): Upgrade Infrahub to the latest version. ### infrahub-events - [Account events](/reference/infrahub-events/account.md): Account Logged In Event - [Artifact events](/reference/infrahub-events/artifact.md): Artifact Created Event - [Branch events](/reference/infrahub-events/branch.md): Branch Created Event - [Commit events](/reference/infrahub-events/commit.md): Commit Updated Event - [Group events](/reference/infrahub-events/group.md): Group Auto Create Capped Event - [Node events](/reference/infrahub-events/node.md): Node Created Event - [Event reference](/reference/infrahub-events/overview.md): Complete reference for all events emitted by Infrahub. Each page lists every event in that category with its type identifier, description, and payload fields. - [Proposed events](/reference/infrahub-events/proposed.md): Proposed Change Approval Revoked Event - [Schema events](/reference/infrahub-events/schema.md): Schema Updated Event - [Validator events](/reference/infrahub-events/validator.md): Validator Failed Event ### infrahub-tests The tests configuration file allows you to define multiple tests for Infrahub resources such as Jinja2 Transformations, Python Transformations, checks and GraphQL queries. - [Tests configuration file](/reference/infrahub-tests.md): The tests configuration file allows you to define multiple tests for Infrahub resources such as Jinja2 Transformations, Python Transformations, checks and GraphQL queries. ### ldap This reference document describes the configuration options for LDAP authentication in Infrahub. - [LDAP](/reference/ldap.md): This reference document describes the configuration options for LDAP authentication in Infrahub. ### menu A menu definition file allows you to control the layout and structure of the menu on the left side of the Infrahub web interface. More information can be found in the Controlling the menu guide. - [Menu definition file](/reference/menu.md): A menu definition file allows you to control the layout and structure of the menu on the left side of the Infrahub web interface. More information can be found in the Controlling the menu guide. ### message-bus-events This document provides detailed documentation for all events used in the Infrahub message bus system. - [Message bus events](/reference/message-bus-events.md): This document provides detailed documentation for all events used in the Infrahub message bus system. ### metrics Infrahub exposes the metrics below in the Prometheus text format. The API server serves them on /metrics on its HTTP port, and each task worker serves them on the port set by INFRAHUBMETRICSPORT (default 8000). Task-manager metrics come from the Prefect exporter included in the observability stack. - [Prometheus metrics](/reference/metrics.md): Infrahub exposes the metrics below in the Prometheus text format. The API server serves them on /metrics on its HTTP port, and each task worker serves them on the port set by INFRAHUBMETRICSPORT (default 8000). Task-manager metrics come from the Prefect exporter included in the observability stack. ### permissions Reference documentation for Infrahub's global and object permissions - [Permissions](/reference/permissions.md): Reference documentation for Infrahub's global and object permissions ### schema - [Schema Specification](/reference/schema.md) - [Attribute](/reference/schema/attribute.md): In a schema file, an attribute can be defined inside a node, a generic or a node extension. - [Generic](/reference/schema/generic.md): All options to define a Generic in the schema - [Groups](/reference/schema/groups.md): Groups schema reference - [Node](/reference/schema/node.md): Node schema reference - [Node Extension](/reference/schema/node-extension.md): All options to define a node extension in the schema - [Relationship](/reference/schema/relationship.md): In a schema file, a relationship can be defined inside a node, a generic or a node extension. - [Schema Update](/reference/schema/validator-migration.md): In this context, an element represent either a Node, a Generic, an Attribute or a Relationship ### schema-validation Infrahub requires the user to define multiple YAML files. One or more files defining the schema in Infrahub and the external repository configuration file. - [Schema validation](/reference/schema-validation.md): Infrahub requires the user to define multiple YAML files. One or more files defining the schema in Infrahub and the external repository configuration file. ### sso This reference document describes the available SSO protocols, configuration options, and parameters in Infrahub. - [SSO (Single sign-on)](/reference/sso.md): This reference document describes the available SSO protocols, configuration options, and parameters in Infrahub. ## release-notes - [Release Notes](/release-notes.md) ### deprecation-guides - [Deprecation Guides](/release-notes/deprecation-guides.md) - [How to migrate from display_labels to display_label](/release-notes/deprecation-guides/display_labels.md): With Infrahub version 1.5, the displaylabels configuration was deprecated in favor of a Jinja2-based displaylabel configuration that provides more flexibility and consistency. - [Schema load validation and the write contract](/release-notes/deprecation-guides/schema-load-write-contract.md): Infrahub now validates every schema submitted to POST /api/schema/load against a - [How to migrate off the SSO account-name fallback](/release-notes/deprecation-guides/sso-account-name-fallback.md): Infrahub 1.8.7 and 1.9.7 introduce a feature flag, ssoaccountname_fallback, that ### infrahub Chronological feed of all Infrahub releases, with full detail for the newest release lines. - [Infrahub release notes](/release-notes/infrahub.md): Chronological feed of all Infrahub releases, with full detail for the newest release lines. - [Documentation restructure](/release-notes/infrahub/docs-restructure.md): Why we reorganized - [Release 0.10.0 - Alpha #4](/release-notes/infrahub/release-0_10.md): Hierarchical mode and the new pytest-based test framework. - [Release 0.11.0 - Alpha #5](/release-notes/infrahub/release-0_11.md): Check testing, read-only repositories, object search, and database backup/restore. - [Release 0.12.0 - Beta #1](/release-notes/infrahub/release-0_12.md): Unified storage improvements, CI pipeline, and schema updates. - [Release 0.13.0](/release-notes/infrahub/release-0_13.md): Built-in IPAM: IPv4/IPv6 prefixes and addresses with automatic prefix trees. - [Release 0.14.0](/release-notes/infrahub/release-0_14.md): Start of the open beta: documentation overhaul and the new Resource Manager. - [Release 0.15.0](/release-notes/infrahub/release-0_15_0.md): User-experience enhancements and groundwork for future features. - [Release 0.15.1](/release-notes/infrahub/release-0_15_1.md): Bug-fix release. - [Release 0.15.2](/release-notes/infrahub/release-0_15_2.md): Bug-fix release. - [Release 0.15.3](/release-notes/infrahub/release-0_15_3.md): Add usage of Towncrier to generate Changelog as part of the release process. Serve Swagger & Redoc files locally so that the REST-API docs work offline or when isolated from the internet. - [Release 0.16](/release-notes/infrahub/release-0_16_0.md): Number resource pools and object-management improvements for additional use cases. - [Release 0.16.1](/release-notes/infrahub/release-0_16_1.md): - In list views, always show relationships of type 'Parent.' In the details view of an object, hide the 'Parent' relationship if the parent is the current object itself. - [Release 0.16.2](/release-notes/infrahub/release-0_16_2.md): Loading a schema with an invalid order by field raises a proper error. Updates internal logic to improve performance when generating a diff. - [Release 0.16.3](/release-notes/infrahub/release-0_16_3.md): Save a diff in smaller pieces instead of all at once to prevent out-of-memory error. Fixes exception handling section in the Python SDK batch guide. - [Release 0.16.4](/release-notes/infrahub/release-0_16_4.md): Fixed an issue on the UI where a new relationship was being added to the main branch instead of the current branch. - [Release 0.6.0](/release-notes/infrahub/release-0_6.md): New logo and colors, user management and authentication, and the first version of Groups. - [Release 0.7.0](/release-notes/infrahub/release-0_7.md): Early beta release. - [Release 0.8.0 - Alpha #2](/release-notes/infrahub/release-0_8.md): Early beta release. - [Release 0.9.0 - Alpha #3](/release-notes/infrahub/release-0_9.md): Early beta release. - [Release 1.0](/release-notes/infrahub/release-1_0_0.md): General availability: improved diffing, rebasing, and branch merges for a production-ready source of truth. - [Release 1.0.1](/release-notes/infrahub/release-1_0_1.md): When a user is not logged in and the branch name is not found, hide the quick-create action and display the message: 'No branch found' (4801) Fix automation to trigger generation of artifacts after merging a branch (4804) - [Release 1.0.10](/release-notes/infrahub/release-1_0_10.md): Make URL fields clickable in the details view (5005) - [Release 1.0.2](/release-notes/infrahub/release-1_0_2.md): Update branch merge logic to use smaller queries outside of a transaction to allow merging a branch with many changes (4448) Ensure the GraphQL query InfrahubResourcePoolUtilization works properly when the schema is different in the branch (4761) - [Release 1.0.3](/release-notes/infrahub/release-1_0_3.md): Fix hierarchical schema update logic to correctly update peer on parent relationship of new node (4838) Fix hierarchical schema update logic to correctly update peer on parent of new child node (4839) - [Release 1.0.4](/release-notes/infrahub/release-1_0_4.md): Profiles now have a Human-Friendly Identifier (HFID) defined based on their Profile name (4758) Workers out of sync after deleting node from schema (4836) - [Release 1.0.5](/release-notes/infrahub/release-1_0_5.md): Node attribute name can now be type (4381) - [Release 1.0.6](/release-notes/infrahub/release-1_0_6.md): Forbid changing the 'optional' property of an inherited attribute to not break GraphQL schema generation (4936) The permission to edit the default branch is now enforced properly when loading a schema (4958) - [Release 1.0.7](/release-notes/infrahub/release-1_0_7.md): Bug-fix release. - [Release 1.0.8](/release-notes/infrahub/release-1_0_8.md): Add a security setting for the default SSO user group, giving the name of a group to which SSO users are assigned if the identity provider does not give a list of groups to use (4924) Added a configuration setting for Git repositories that appends '.git' to repositories defined with an HTTP URL for the configured domains (5077) - [Release 1.0.9](/release-notes/infrahub/release-1_0_9.md): Adding invoke tasks to assist with release process. Add pagination and backend search in new combobox for relationships. - [Release 1.1.0](/release-notes/infrahub/release-1_1_0.md): Computed attributes — a highly requested feature — plus many behind-the-scenes improvements. - [Release 1.1.1](/release-notes/infrahub/release-1_1_1.md): Raise a better error when trying to resolve an invalid HFID for a relationship (5360) Fix an issue with session management that could lead to the crash of the GraphQL resolver - [Release 1.1.2](/release-notes/infrahub/release-1_1_2.md): Added a configuration option for INFRAHUB_PUBLIC_URL, which could be required for SSO depending on how Infrahub is published and accessed within your organization. - [Release 1.1.3](/release-notes/infrahub/release-1_1_3.md): Add a new link in the object details button to redirect to the tasks list with a filter for the current object - [Release 1.1.4](/release-notes/infrahub/release-1_1_4.md): Artifacts can now be of type: YAML, XML, markdown, SVG and CSV. - [Release 1.1.5](/release-notes/infrahub/release-1_1_5.md): Allow OIDC providers to fall back to the ID token for group membership reports if they are not provided within the userinfo URL. - [Release 1.1.6](/release-notes/infrahub/release-1_1_6.md): Allow Default Address Type quick selection in the Resource Manager form (3489) Added code viewer for new content-types, preview of raw markdown content, one-click file download or copy, and redesign of artifact details view (5452) - [Release 1.1.7](/release-notes/infrahub/release-1_1_7.md): Data diffs are loaded in sequential batches for faster performance with large changes. The diff tree and diff list can now be scrolled independently. - [Release 1.1.8](/release-notes/infrahub/release-1_1_8.md): Fixed an error in the query to count the number of peers for a given cardinality-many relationship. Fixed the HFID format in the mutations IPAddressPoolGetResource and IPPrefixPoolGetResource. - [Release 1.1.9](/release-notes/infrahub/release-1_1_9.md): Improved the performance of the GraphQL cardinality-many relationship resolver by batching database calls together. - [Release 1.10.0](/release-notes/infrahub/release-1_10_0.md): Graph path traversal with a visual topology explorer, native LDAP authentication for Enterprise, auto-created account groups from identity-provider claims, database-level branch merges, and a structured GraphQL error catalogue. - [Release 1.10.1](/release-notes/infrahub/release-1_10_1.md): Adds a shortest-paths toggle to path traversal; restores webhook delivery and fixes default-branch Git sync, merge backfills, and unique-constraint validation on merge. - [Release 1.10.2](/release-notes/infrahub/release-1_10_2.md): Fixes mutation events being dropped for nodes with ~250+ relationship peers, and errors from display labels reading a deleted peer. - [Release 1.10.3](/release-notes/infrahub/release-1_10_3.md): Initialization locks now auto-expire so a dead worker can't block startup; fixes IPv6 search normalization, repository connectivity status, and branch-merge rollback. - [Release 1.10.4](/release-notes/infrahub/release-1_10_4.md): Adds Neo4j cluster addresses via INFRAHUB_DB_ADDRESS; fixes Git repository re-pointing, cascade-delete validation, and missing webhook account IDs. - [Release 1.10.5](/release-notes/infrahub/release-1_10_5.md): Fixes a diff-recalculation race after rebase, schema-diff failures when merging branches that removed schema nodes, and schema migrations being counted twice on rebased branches. - [Release 1.10.6](/release-notes/infrahub/release-1_10_6.md): Speeds up node creation by avoiding a redundant peer query for empty relationships, and fixes repository cascade deletion, IPAM namespace link navigation, git-sync import, and diff-tree rendering. - [Release 1.10.7](/release-notes/infrahub/release-1_10_7.md): Speeds up GraphQL queries that only request a relationship peer's id, and fixes artifact generation, number-pool computed attributes, non-main default branches, group mutation events, git-sync, and several object form issues. - [Release 1.10.8](/release-notes/infrahub/release-1_10_8.md): Fixes a crash in the proposed change Data diff tab on large diffs, number pool allocation stalling on pre-existing values, mutation events being refused by Prefect, and migrations failing on transient database errors. - [Release 1.10.9](/release-notes/infrahub/release-1_10_9.md): Fixes a crash on the Tasks page when a task references a related node whose kind can no longer be resolved, and an attribute rename on a branch leaving the old attribute open, which could duplicate paths to the renamed attribute after a rebase. - [Release 1.11.0](/release-notes/infrahub/release-1_11_0.md): Scale and performance: a merge regenerates only the artifacts and Generators it actually affected, computed attributes recompute only when their inputs change, and schema constraint validation is scoped to the kinds and fields a change can violate. Webhook deliveries become tasks you can inspect, retry and cancel, an interrupted merge is detectable and recoverable, and task priority lanes keep user-facing operations ahead of background work. - [Release 1.11.1](/release-notes/infrahub/release-1_11_1.md): Makes object creates and updates faster, most notably when creating objects from an object template, and stops API server memory growing without bound by evicting superseded GraphQL schemas. Also fixes read queries being pushed onto the async path, which made schema introspection take over ten seconds, and repairs nodes left without attribute rows when an existing kind started inheriting from a generic. - [Release 1.11.2](/release-notes/infrahub/release-1_11_2.md): Fixes account preferences to preview the date and timezone values that saving will produce, cleans up an SSO account's identities and tokens when it is deleted, purges a deleted branch's settled tasks, and keeps the branch registry cache in sync with the database. Artifacts and Generators are now regenerated when a display label or human-friendly ID changes. - [Release 1.11.3](/release-notes/infrahub/release-1_11_3.md): Adds a configurable CA bundle for outbound TLS, a command to reset the databases, and a load-shed marker header that the web UI uses to wait and retry. Schema load and check errors now return one 422 entry per offending field, and many fixes improve diff, merge, and listing performance on large branches. - [Release 1.11.4](/release-notes/infrahub/release-1_11_4.md): Infrahub now refuses to serve an artifact file that no longer matches its checksum, adds an option to skip TLS certificate validation for S3 and syslog servers, and adds a command to delete unfrozen diffs. A rebase now emits an event for each of the branch's own changes, and many fixes improve diff and rebase correctness and performance on large branches. - [Release 1.11.5](/release-notes/infrahub/release-1_11_5.md): Infrahub now uses updated versions of PyJWT, urllib3 and other dependencies that fix published security vulnerabilities, including a critical PyJWT vulnerability. Other fixes speed up operations on Profiles used by many objects, and resolve missing related objects in large GraphQL queries and searches that returned no results when the text starts or ends with a space. - [Release 1.11.6](/release-notes/infrahub/release-1_11_6.md): Infrahub 1.11.6 brings the selective regeneration improvements from the 1.12 line to 1.11. After a merge or in a proposed change, regeneration now narrows to the affected members instead of regenerating every member of a definition, and artifacts and Generators regenerate again when a change touches a field their query filters on. - [Release 1.11.7](/release-notes/infrahub/release-1_11_7.md): Infrahub 1.11.7 rejects concurrent creates of the same IP address on a branch other than the default branch when the schema declares a uniqueness constraint on it, and shows the info severity badge in task logs in blue. - [Release 1.11.8](/release-notes/infrahub/release-1_11_8.md): Infrahub 1.11.8 regenerates only the artifacts and Generators whose query reads a changed node through a fragment, a generic or a relationship, and fixes several cases where they were not regenerated. It also limits the scheduled job that revokes approvals to open proposed changes, fixes the erase error in the Git credential helper, and adds Python 3.15 support to the infrahub-testcontainers package. - [Release 1.11.9](/release-notes/infrahub/release-1_11_9.md): Infrahub 1.11.9 updates certifi to 2026.10.19 to remove the emSign root certificates (GHSA-6q48-6c7w-9gw2), allows a null node_metadata on relationships to a generic in the GraphQL schema, and no longer regenerates artifacts and Generators when a change only affects peers that a relationship filter excludes. It also fixes GraphQL queries that failed when they requested node_metadata on a relationship to a generic, and data conflicts on the fingerprint of Generator and Transformation definitions. - [Release 1.2.0](/release-notes/infrahub/release-1_2_0.md): Highly anticipated new features alongside bug fixes and performance improvements. - [Release 1.2.1](/release-notes/infrahub/release-1_2_1.md): Added relationships changes details in the activities. Added an INFRAHUB_SCHEMA_STRICT_MODE environment variable. - [Release 1.2.10](/release-notes/infrahub/release-1_2_10.md): Added the ability to use alternative value types for all attribute types with computed attributes. Computed Attribute of kind Jinja will only be recalculated during a schema update if the template itself has been updated. - [Release 1.2.11](/release-notes/infrahub/release-1_2_11.md): Add the CoreWeightedPoolResource generic to better control which resource should be used when allocating from a pool. - [Release 1.2.12](/release-notes/infrahub/release-1_2_12.md): Remove uniqueness constraint on generic templates to support upsert mutations (6478) Add a migration to clean up duplicated data from improper merges of branches containing node schemas with an updated kind or inheritance (6502) - [Release 1.2.2](/release-notes/infrahub/release-1_2_2.md): Fixed generic schema updates to correctly propagate an updated order weight to a downstream attribute or relationship on an inheriting schema. - [Release 1.2.3](/release-notes/infrahub/release-1_2_3.md): Added support for Jinja2 filters from Netutils. - [Release 1.2.4](/release-notes/infrahub/release-1_2_4.md): Fixed the migration to remove an attribute from a schema to correctly ignore overridden attributes from a generic schema. - [Release 1.2.5](/release-notes/infrahub/release-1_2_5.md): Added support for computed attributes on generics. Added a new database selected-export command to run an anonymized export of selected objects that includes no actual data. - [Release 1.2.6](/release-notes/infrahub/release-1_2_6.md): Added generics to node selection in number pool form. Enabled node select in the webhook form to quickly choose the node kind. - [Release 1.2.7](/release-notes/infrahub/release-1_2_7.md): Security release: Update the h11 package to 0.16.0. - [Release 1.2.8](/release-notes/infrahub/release-1_2_8.md): Added support for automatic query response conversion in Python Transformations. Enabled HCL syntax highlighting for artifacts. - [Release 1.2.9](/release-notes/infrahub/release-1_2_9.md): Added the INFRAHUB_TESTING_SCHEMA_STRICT_MODE environment variable to allow users to control INFRAHUB_SCHEMA_STRICT_MODE when using infrahub-testcontainers. - [Release 1.3.0](/release-notes/infrahub/release-1_3_0.md): A new Action System that automates routine tasks from system events — group triggers and Generator runs. - [Release 1.3.1](/release-notes/infrahub/release-1_3_1.md): Fix bug that could prevent renaming a unique attribute on a schema (6147) Fix a bug where Number attribute min_value/max_value/excluded_values constraints were not enforced during node creation (6714) - [Release 1.3.2](/release-notes/infrahub/release-1_3_2.md): Improve performance of uniqueness constraint checks during create/update/upsert mutations by allowing ordering elements from more specific to less specific within a constraint group (6377) Fixed: min/max constraints no longer trigger on empty values when the field is optional. - [Release 1.3.3](/release-notes/infrahub/release-1_3_3.md): Add a command to run a single migration - [Release 1.3.5](/release-notes/infrahub/release-1_3_5.md): Add a new check for orphaned Relationship vertices to the database check command - [Release 1.3.6](/release-notes/infrahub/release-1_3_6.md): Add a database check-inheritance command to validate and fix any schemas that have had their inheritance updated and a failed migration. - [Release 1.3.7](/release-notes/infrahub/release-1_3_7.md): Ensure that only users with 'manage schema' permissions can add or remove dropdown and enum values (6410) Fix bug in branch delete cypher query that could leave behind orphaned branch-agnostic relationships. - [Release 1.4.0](/release-notes/infrahub/release-1_4_0.md): New features, performance improvements, and fixes across the platform. - [Release 1.4.1](/release-notes/infrahub/release-1_4_1.md): Fix bug in schema validation that would incorrectly flag Dropdown attributes of node schema that override a generic attribute as having illegal values (7086) - [Release 1.4.10](/release-notes/infrahub/release-1_4_10.md): Fix issue with template that would set the value/source of all attributes even for the attribute that are not defined in the template. - [Release 1.4.11](/release-notes/infrahub/release-1_4_11.md): The login form now automatically focuses on the first field. - [Release 1.4.12](/release-notes/infrahub/release-1_4_12.md): Schema Visualizer now displays on-delete settings for relationships. Fixed display of common parent settings in relationships. - [Release 1.4.13](/release-notes/infrahub/release-1_4_13.md): Added new error message for git connection error (7392) - [Release 1.4.2](/release-notes/infrahub/release-1_4_2.md): Fix a bug where a proposed change could be merged without approval even if some approvals were required (Enterprise) Removed incorrect log warning about 'Branch schema hash is not set, cannot update branch registry' due to including the '-global-' branch when processing branch updates. - [Release 1.4.3](/release-notes/infrahub/release-1_4_3.md): Force branches data to be reloaded when the hash doesn't look healthy. In the UI, clicking the artifact generation button now refreshes the token and retries if the access token has expired. - [Release 1.4.4](/release-notes/infrahub/release-1_4_4.md): Fix HTTP 403 when trying to fetch object metadata in changelog without being allowed to manage permissions (ifc1760) Fix HTTP 403 when trying to fetch nodes though a CoreNode query, this could prevent users to select nodes in various places with the user interface (6733) - [Release 1.4.5](/release-notes/infrahub/release-1_4_5.md): Security release: Fixes bug in authentication logic that allowed expired and/or deleted API tokens to authenticate successfully. - [Release 1.4.6](/release-notes/infrahub/release-1_4_6.md): Make related nodes clickable in task views (6420) Add an option to match trigger actions on any attribute value - [Release 1.4.7](/release-notes/infrahub/release-1_4_7.md): Added optional configuration to fetch and map groups when using Google as an identity provider for OAuth/OIDC. Added the name of the artifact definition to the payload of artifact webhook events. - [Release 1.4.8](/release-notes/infrahub/release-1_4_8.md): Report proper branch when read-only repositories fail to synchronize due to invalid branch (5713) Add an HFID for Attribute and Relationship matches for a Node Trigger Rule (6713) - [Release 1.4.9](/release-notes/infrahub/release-1_4_9.md): Fix prefix/IP Address creation when passing in the IP namespace HFID (7239) Fix bug in schema integrity checks of a proposed change that prevented resolved violations from being removed (7278) - [Main changes](/release-notes/infrahub/release-1_5_0.md): HFID and display_label refactored at write time, Profiles reworked, backup/restore tool added, webhook formats aligned. - [Release 1.5.1](/release-notes/infrahub/release-1_5_1.md): Security release: Updated FastAPI and a vulnerable version of Starlette - [Release 1.5.2](/release-notes/infrahub/release-1_5_2.md): Fix migration that backfills display labels and human-friendly IDs to account for schema that only exist on the branch being migrated. Prevent attempting diff update on a deleted branch. - [Release 1.5.3](/release-notes/infrahub/release-1_5_3.md): Fixed bug that prevented retrieving cardinality-one relationships on a branch that was already merged and included changes to the relationship. - [Main changes](/release-notes/infrahub/release-1_6_0.md): Improved Git integration and UI navigation, branch management, Profiles in templates, dashboard landing page. - [Release 1.6.1](/release-notes/infrahub/release-1_6_1.md): Add support for PKCE within Oauth2 and OIDC authentications. - [Release 1.6.2](/release-notes/infrahub/release-1_6_2.md): Fix Migration041 to determine edge uniqueness correctly and account for incoming Relationship edges. - [Release 1.6.3](/release-notes/infrahub/release-1_6_3.md): Stop showing warnings for deprecated attribute schema length and regex fields when they are not used (7995) - [Release 1.7.0](/release-notes/infrahub/release-1_7_0.md): Audit capabilities with immutable metadata tracking, Profile support for relationships, backend upgrades. - [Release 1.7.1](/release-notes/infrahub/release-1_7_1.md): Added option to use username/password authentication on Redis connections (7994) - [Release 1.7.2](/release-notes/infrahub/release-1_7_2.md): Added 'parallel mode' plugin to the GraphQL web sandbox. GraphQL query parsing and validation is now leveraging a cache to improve performance and CPU consumption. - [Release 1.7.3](/release-notes/infrahub/release-1_7_3.md): Security release: Update system dependencies: OpenSSL patch for CVE-2025-15467 - [Release 1.7.4](/release-notes/infrahub/release-1_7_4.md): Fix bug in computed attribute calculation that prevented having a computed attribute on a branch if there were no computed attributes on the default branch (8270) Add migration to allow rebasing branches created before (8221) was fixed so that the uniqueness constraint on SchemaNode.name and SchemaGeneric.name is removed - [Release 1.7.5](/release-notes/infrahub/release-1_7_5.md): Add migration to handle setting duplicated schemas on the default branch to be deleted, keeping the one with the latest update (8221) Handle deleted parent relationship schemas when combining diffs without crashing (8388) - [Release 1.7.6](/release-notes/infrahub/release-1_7_6.md): Pass order weights into Profile schema fields to prevent reordering causing a hash mismatch Update schema validation and processing to be completely idempotent to prevent incorrect hash errors when retrieving schemas - [Release 1.7.7](/release-notes/infrahub/release-1_7_7.md): Fixed display labels showing 'None' for relationship-based fields after upsert. - [Release 1.8.0](/release-notes/infrahub/release-1_8_0.md): File objects, automatic branch freeze-on-merge, resource pools in object templates, Kubernetes backup support. - [Release 1.8.1](/release-notes/infrahub/release-1_8_1.md): Added schema processing to schema integrity check in order to validate the schema (8355) - [Release 1.8.2](/release-notes/infrahub/release-1_8_2.md): Fix scheduled reconfiguration of webhooks targeting 'all' events (8694) Fixed branch rebase conflicts during 1.7 to 1.8 upgrades caused by migration 056 writing unrelated schema attributes to branch timelines - [Release 1.8.3](/release-notes/infrahub/release-1_8_3.md): Corrected data diff view within a proposed change or branch view so that changes to Profiles show up. Fixed hard failures on GraphQL queries that would exhaust Neo4j's server thread pool by implementing back off retry. - [Release 1.8.4](/release-notes/infrahub/release-1_8_4.md): Link a merging proposed change to its diff during the merge operation if it has not been linked yet (8769) Fixed an issue where webhook match statements (node kind filters) were lost during scheduled reconfiguration. - [Release 1.8.5](/release-notes/infrahub/release-1_8_5.md): Ensure that changes to a password attribute counts as a mutation event for a node. Add distributed lock around branch creation to prevent race condition (8368) - [Release 1.8.6](/release-notes/infrahub/release-1_8_6.md): Schema deletions are now rejected when a generic is still referenced by the inheritance of another node, and partial schema writes are rolled back if loading the updated schema fails. - [Release 1.9.0](/release-notes/infrahub/release-1_9_0.md): Two headline additions: an interactive schema visualizer that turns your schema into a navigable graph, and syslog log forwarding for Enterprise — streaming activity, login/logout, and permission-denied events to SIEM systems such as Splunk, Datadog, and ELK over TCP or UDP with optional TLS. Jinja2 computed attributes now recalculate inline on local changes instead of spawning a background task per node, and new Jinja2 filters let artifacts inline and parse content from other artifacts and file objects. - [Release 1.9.1](/release-notes/infrahub/release-1_9_1.md): Fixes stale schema cache when importing Git commits mixing schema and object files, duplicate hierarchy parents after merge, and branch owners unable to delete their own branch. - [Release 1.9.10](/release-notes/infrahub/release-1_9_10.md): Fixes the branch-merge rollback so a mid-merge database error no longer leaves partially merged data on the destination branch. - [Release 1.9.2](/release-notes/infrahub/release-1_9_2.md): Merged or deleted branches no longer reappear as needing a rebase after object-type conversions or an upgrade. - [Release 1.9.3](/release-notes/infrahub/release-1_9_3.md): Broader rollback protection against partially merged branches, and a fix for a race condition where concurrent workers shared the same Neo4j session. - [Release 1.9.4](/release-notes/infrahub/release-1_9_4.md): Adds a global permission for rebasing branches; diff calculation now scales with the branch's changes instead of database size, and IP/MAC attribute values are normalized. - [Release 1.9.5](/release-notes/infrahub/release-1_9_5.md): Fixes CoreNumberPool upserts, migrations when an attribute stops being unique, and cardinality constraints declared on subtypes of a generic peer. - [Release 1.9.6](/release-notes/infrahub/release-1_9_6.md): Fixes Copy ID/HFID/Token actions over plain HTTP and merges deleting objects whose kind changed on the default branch after forking. - [Release 1.9.7](/release-notes/infrahub/release-1_9_7.md): Enables OIDC id_token verification by default and blocks local password changes for directory-backed accounts. Schema names containing __ are now rejected. - [Release 1.9.8](/release-notes/infrahub/release-1_9_8.md): Faster transform-based computed attributes; fixes schema-constraint reconciliation on generics, prefix utilization on new branches, and Profile-sourced relationship overrides. - [Release 1.9.9](/release-notes/infrahub/release-1_9_9.md): Upgrades GitPython to address GHSA-mv93-w799-cj2w (configuration injection); also fixes Git imports with conflicting branches and rebase permission checks. ## resource-manager ### allocate-ip-address IP address pools (CoreIPAddressPool) dynamically allocate individual IP addresses from source prefixes. - [Allocate IP addresses](/resource-manager/allocate-ip-address.md): IP address pools (CoreIPAddressPool) dynamically allocate individual IP addresses from source prefixes. ### allocate-ip-prefix IP prefix pools (CoreIPPrefixPool) allocate IP subnets from larger prefixes. - [Allocate IP prefixes](/resource-manager/allocate-ip-prefix.md): IP prefix pools (CoreIPPrefixPool) allocate IP subnets from larger prefixes. ### allocate-number Number pools (CoreNumberPool) automatically assign sequential numbers to numeric attributes. - [Allocate numbers](/resource-manager/allocate-number.md): Number pools (CoreNumberPool) automatically assign sequential numbers to numeric attributes. ### overview Resource Manager in Infrahub automates the allocation of network resources from predefined pools, eliminating manual assignment and preventing conflicts across your infrastructure. This system ensures consistent resource allocation while maintaining complete visibility and control over your available resources. - [Resource Manager](/resource-manager/overview.md): Resource Manager in Infrahub automates the allocation of network resources from predefined pools, eliminating manual assignment and preventing conflicts across your infrastructure. This system ensures consistent resource allocation while maintaining complete visibility and control over your available resources. ### weighted-allocation When multiple resources can be allocated from a pool, you can control the allocation order using weights. Resources with higher weights are allocated first. - [Weighted allocation](/resource-manager/weighted-allocation.md): When multiple resources can be allocated from a pool, you can control the allocation order using weights. Resources with higher weights are allocated first. ## schema-and-data - [Schema & Data](/schema-and-data.md) ## schema ### analyze-your-data Ask an AI assistant questions about live Infrahub data through the MCP server, without writing GraphQL. - [Analyze your data](/schema/analyze-your-data.md): Ask an AI assistant questions about live Infrahub data through the MCP server, without writing GraphQL. ### branch-awareness Every schema element — nodes, attributes, and relationships — can be configured to control how changes to its data behave across branches. - [Branch awareness](/schema/branch-awareness.md): Every schema element — nodes, attributes, and relationships — can be configured to control how changes to its data behave across branches. ### build-your-schema Describe a schema change in plain language and have your assistant produce the schema YAML for it, validated before it reaches you. - [Build your schema with AI](/schema/build-your-schema.md): Describe a schema change in plain language and have your assistant produce the schema YAML for it, validated before it reaches you. ### create-and-load Schemas are defined in YAML format and follow a strict structure. Splitting a schema into multiple smaller files is recommended to keep it maintainable as it grows. - [Create and load schema](/schema/create-and-load.md): Schemas are defined in YAML format and follow a strict structure. Splitting a schema into multiple smaller files is recommended to keep it maintainable as it grows. ### default-ordering The order_by field on a node or generic sets the default sort order for every list of that kind's objects. Once declared, the order applies everywhere the objects are listed - the web interface, the GraphQL API, and the Python SDK - without each query specifying how to sort. - [Default ordering](/schema/default-ordering.md): The order_by field on a node or generic sets the default sort order for every list of that kind's objects. Once declared, the order applies everywhere the objects are listed - the web interface, the GraphQL API, and the Python SDK - without each query specifying how to sort. ### display_label Display labels in Infrahub provide human-friendly names and identifiers for schema elements and object instances. They serve as the primary way users interact with and identify objects throughout the system, from the user interface to GraphQL queries. - [Display labels](/schema/display_label.md): Display labels in Infrahub provide human-friendly names and identifiers for schema elements and object instances. They serve as the primary way users interact with and identify objects throughout the system, from the user interface to GraphQL queries. ### extensions Schema extensions provide a mechanism to add attributes and relationships to existing nodes without redefining them. This enables modular schema composition where features can be developed, reviewed, and managed as self-contained files. - [Schema extensions](/schema/extensions.md): Schema extensions provide a mechanism to add attributes and relationships to existing nodes without redefining them. This enables modular schema composition where features can be developed, reviewed, and managed as self-contained files. ### field-visibility Infrahub schemas can declare how attributes and relationships should appear in the frontend, independently of their presence in the data model. These declarations are purely UI hints — they do not affect data access via the API, GraphQL, or forms. - [Field visibility](/schema/field-visibility.md): Infrahub schemas can declare how attributes and relationships should appear in the frontend, independently of their presence in the data model. These declarations are purely UI hints — they do not affect data access via the API, GraphQL, or forms. ### file-object Infrastructure management often involves more than just structured data. Contracts, documents, and pictures are all essential assets that relate directly to the devices, circuits, and services they describe. Infrahub's file object feature lets you attach files to any node in the graph, making these files first-class citizens of your infrastructure data model with full version control, branch isolation, and permission enforcement. - [File objects](/schema/file-object.md): Infrastructure management often involves more than just structured data. Contracts, documents, and pictures are all essential assets that relate directly to the devices, circuits, and services they describe. Infrahub's file object feature lets you attach files to any node in the graph, making these files first-class citizens of your infrastructure data model with full version control, branch isolation, and permission enforcement. ### generics-and-inheritance A Generic in Infrahub is a reusable base that shares attributes and relationships across multiple node types. They work similarly to abstract base classes or interfaces in object-oriented programming — you define common structure once, and node types that inherit_from a generic receive that structure automatically. - [Generics & inheritance](/schema/generics-and-inheritance.md): A Generic in Infrahub is a reusable base that shares attributes and relationships across multiple node types. They work similarly to abstract base classes or interfaces in object-oriented programming — you define common structure once, and node types that inherit_from a generic receive that structure automatically. ### hierarchy Infrahub supports organizing nodes of similar types into a tree structure. Hierarchy mode enables ancestor and descendant queries, and allows filtering related data across multiple levels of the tree without direct relationships between every node. - [Hierarchy](/schema/hierarchy.md): Infrahub supports organizing nodes of similar types into a tree structure. Hierarchy mode enables ancestor and descendant queries, and allows filtering related data across multiple levels of the tree without direct relationships between every node. ### marketplace The Infrahub Marketplace is a public catalog of pre-built schemas and schema collections that you can fetch and load into any Infrahub instance. - [Infrahub Marketplace](/schema/marketplace.md): The Infrahub Marketplace is a public catalog of pre-built schemas and schema collections that you can fetch and load into any Infrahub instance. ### migration Unlike most databases that support a single schema at a time, in Infrahub it is possible to have a different schema per branch. - [Schema migration](/schema/migration.md): Unlike most databases that support a single schema at a time, in Infrahub it is possible to have a different schema per branch. ### namespaces Every model in your schema belongs to a namespace. A namespace groups related models together and makes each model's kind unique, so two teams can both define a Device model without a name collision. - [Namespaces](/schema/namespaces.md): Every model in your schema belongs to a namespace. A namespace groups related models together and makes each model's kind unique, so two teams can both define a Device model without a name collision. ### nodes-and-attributes A Node is the fundamental unit of the schema — it represents a concrete object in your infrastructure model such as a device, interface, or IP address. Nodes are composed of Attributes (direct values) and Relationships (links to other nodes). This page covers how to define nodes and attributes, what kinds are available, and how to configure identifiers, constraints, and display. - [Nodes & attributes](/schema/nodes-and-attributes.md): A Node is the fundamental unit of the schema — it represents a concrete object in your infrastructure model such as a device, interface, or IP address. Nodes are composed of Attributes (direct values) and Relationships (links to other nodes). This page covers how to define nodes and attributes, what kinds are available, and how to configure identifiers, constraints, and display. ### number-pool The NumberPool attribute kind enables the dynamic creation of a CoreNumberPool for the specific schema node and attribute rather than requiring users to define this after the schema is loaded. - [Number pools](/schema/number-pool.md): The NumberPool attribute kind enables the dynamic creation of a CoreNumberPool for the specific schema node and attribute rather than requiring users to define this after the schema is loaded. ### order-weight The orderweight property controls how attributes and relationships are ordered in the Infrahub frontend, including table views and detailed object views. **Lower orderweight values appear first. This means items with smaller numbers are displayed before those with larger numbers. Understanding how default values are assigned and how to work with them effectively is crucial for creating well-organized schemas. - [Order weight](/schema/order-weight.md): The orderweight property controls how attributes and relationships are ordered in the Infrahub frontend, including table views and detailed object views. **Lower orderweight values appear first. This means items with smaller numbers are displayed before those with larger numbers. Understanding how default values are assigned and how to work with them effectively is crucial for creating well-organized schemas. ### overview The schema is Infrahub's data model — a flexible, organization-specific definition of what objects exist in your infrastructure, design, and business logic, what properties they have, and how they relate to each other. It acts as an abstraction layer over the graph database, so no knowledge of database administration is needed for day-to-day use. - [About schema](/schema/overview.md): The schema is Infrahub's data model — a flexible, organization-specific definition of what objects exist in your infrastructure, design, and business logic, what properties they have, and how they relate to each other. It acts as an abstraction layer over the graph database, so no knowledge of database administration is needed for day-to-day use. ### relationships A Relationship in Infrahub represents a typed link between two nodes. Unlike a foreign key, relationships have a kind that determines how they appear in the UI and how they behave during deletion and hierarchy traversal. - [Relationships](/schema/relationships.md): A Relationship in Infrahub represents a typed link between two nodes. Unlike a foreign key, relationships have a kind that determines how they appear in the UI and how they behave during deletion and hierarchy traversal. ## snippets ### attribute-kind-params | Parameter | Default | - [attribute-kind-params](/snippets/attribute-kind-params.md): | Parameter | Default | ### pre-reqs-base | Prerequisite Tool(s) | Post Installation Steps | - [pre-reqs-base](/snippets/pre-reqs-base.md): | Prerequisite Tool(s) | Post Installation Steps | ### pre-reqs-frontend | Prerequisite Tool(s) | Post Installation Steps | - [pre-reqs-frontend](/snippets/pre-reqs-frontend.md): | Prerequisite Tool(s) | Post Installation Steps | ## testing-framework ### overview Summary - [Testing framework](/testing-framework/overview.md): Summary ## transformations ### jinja2 A Jinja2 Transformation renders Infrahub data through a Jinja template, producing plain text output (configurations, manifests, payloads). The steps below cover how to write one. - [Write a Jinja2 Transformation](/transformations/jinja2.md): A Jinja2 Transformation renders Infrahub data through a Jinja template, producing plain text output (configurations, manifests, payloads). The steps below cover how to write one. ### overview A Transformation is a generic plugin to transform a dataset into a different format to simplify it's ingestion by third-party systems. - [Transformations](/transformations/overview.md): A Transformation is a generic plugin to transform a dataset into a different format to simplify it's ingestion by third-party systems. ### python A Python Transformation processes Infrahub data through user-written Python code, producing JSON output (or any structured data you serialize). Use this when Jinja templating isn't enough — for example, conditional logic, external API calls, or complex aggregation. The steps below cover how to write one. - [Write a Python Transformation](/transformations/python.md): A Python Transformation processes Infrahub data through user-written Python code, producing JSON output (or any structured data you serialize). Use this when Jinja templating isn't enough — for example, conditional logic, external API calls, or complex aggregation. The steps below cover how to write one. ## webhooks ### create 1. Login to Infrahub's web interface as an administrator. - [Create a webhook](/webhooks/create.md): 1. Login to Infrahub's web interface as an administrator. ### custom-transformation Use a custom webhook to transform event data before Infrahub sends it to an external endpoint. This is useful when the receiving system expects a specific payload format, such as Slack, Microsoft Teams, GitHub Actions, or other third-party APIs. - [Webhook with custom Transformation](/webhooks/custom-transformation.md): Use a custom webhook to transform event data before Infrahub sends it to an external endpoint. This is useful when the receiving system expects a specific payload format, such as Slack, Microsoft Teams, GitHub Actions, or other third-party APIs. ### overview Webhooks push data to external systems each time a matching event occurs in Infrahub. Use them to: - [What are webhooks?](/webhooks/overview.md): Webhooks push data to external systems each time a matching event occurs in Infrahub. Use them to: