Key concepts
Infrahub stores infrastructure data and its relationships, versions changes, and generates outputs for your automation. You can describe a new site, review its devices and addressing before deployment, and produce configurations from the same data.
Connected data and a flexible schema​
An object represents something you manage: a site, device, circuit, or service. Attributes describe it, such as a device's name or status. Relationships connect objects, such as a device to its site or a service to its circuit. Together, these objects and relationships form a graph.
These connections make the data useful beyond an inventory. You can find the services that depend on a circuit before planning its replacement.
The schema defines the kinds of objects you can create, their attributes, relationships, and validation rules. You define it in YAML to match your infrastructure and business, including concepts such as customers or service tiers. Infrahub generates the web UI and API endpoints from that schema.
Start with your existing model or define a schema, then evolve it as your requirements change.
Branches and Proposed Changes​
A branch is a separate version of your infrastructure data, schema, and artifacts.
For a new site, you can prepare devices, addressing, and schema changes on a branch while others continue working on the default branch.
A Proposed Change is the review of a branch before merging, similar to a pull request. Reviewers inspect the differences, discuss the changes, examine the validation results, and approve the change. Before the merge, resolve any conflicts with the default branch. Merging applies the changes to the default branch.
Branches isolate branch-aware data. You can also define shared data that stays the same across branches, such as an IP address Resource Pool.
Validation before merge​
Schema rules describe valid data: required attributes, allowed values, and relationships. Checks add your business and infrastructure design rules in Python, such as requiring two WAN circuits for every site. This can flag a design that leaves a site dependent on a single connection.
Checks run as part of a Proposed Change, so reviewers can catch a missing backup connection before approving a site design. Finding that gap before deployment helps reduce the risk of an outage that interrupts business operations.
History and data ownership​
Immutable history records earlier versions of objects, attributes, and relationships. The Activity log records operations, including who changed an object and when.
Data lineage describes where a value came from and who owns it. You can record source and owner metadata on individual attributes and relationships, which is useful when people and external systems maintain different parts of the same device record.
You can query a past state to investigate which circuit a service used before a change, then use the Activity log to identify who changed it and when.
Reusable definitions and resource allocation​
When adding another site, some details repeat and others must be unique. These concepts address different parts of that work:
| Concept | Example use |
|---|---|
| Object Templates | Create a switch with its standard set of interfaces. Later template edits do not change existing objects. |
| Profiles | Share interface settings across switches. Updating a Profile updates inherited values, while explicit overrides remain. |
| Groups | Select the devices that a check, Generator, or artifact definition targets. |
| IPAM | Model IP prefixes and addresses and their relationships to your infrastructure. |
| Resource Manager | Allocate addresses, prefixes, or numbers such as VLAN IDs from defined pools. |
Generators, Transformations, and artifacts​
A Generator runs your Python logic to create or update objects and relationships in Infrahub. For example, a Generator can turn a site design into firewall and switch devices, their networks, and monitoring services according to your rules. Infrahub records which objects each Generator run created. When the site design changes and the Generator runs again, it creates the objects the new design needs and removes the ones it no longer needs.
A Transformation converts queried data into an output format using Jinja2 or Python. It can produce a device configuration, an automation inventory or a report. An artifact is a stored output for a particular target, available for review and retrieval.
The distinction is the output: Generators change the data model's objects; Transformations produce content from that data.
Git integration​
An external Git repository stores the files that define your automation: schemas, GraphQL queries, Generators, Transformations, and Checks. In the repository, .infrahub.yml declares which resources Infrahub imports and how they connect: which query a Transformation reads, which objects a Generator targets, or which checks validate a change.
With a standard Repository connection, Infrahub automatically imports updates from Git into corresponding Infrahub branches. For a new site, you can change a configuration template in Git and add devices on the matching Infrahub branch, then review the resulting data and artifacts in a Proposed Change. When the branch is configured to sync with Git, merging in Infrahub also merges the linked Git branch.
A Read-only Repository connection imports a selected branch, tag, or commit. You request updates explicitly; Infrahub does not poll it or write back to Git.
Choose a Read-only Repository connection when you want to control when new automation code is imported.
Git versions the files; Infrahub versions the infrastructure data. Editing a device in Infrahub does not write that device back to Git. See Git integration to choose a connection and configure synchronization.
External automation​
External tools can query data through the GraphQL API and retrieve artifacts for deployment through the REST API. Events and webhooks connect changes in Infrahub to other workflows, such as notifying an automation pipeline after a merge. Write scripts against the Python SDK, manage Infrahub from the command line with infrahubctl, and import data from systems such as NetBox or Nautobot with Infrahub Sync.
Merging updates the data in the main branch of Infrahub. Infrahub does not deploy configurations. An external deployment tool that you operate, such as an Ansible playbook or a CI/CD pipeline, controls when and how they are applied to infrastructure.
Try it​
Explore Infrahub to view objects, relationships, and branches in the web UI, or build your first schema to model your own infrastructure.