Core Concepts

​

The three pillars

​

Flexible schema

• Fully customizable: Define any node type, attribute, or relationship your infrastructure needs
• Version controlled: Schema changes are tracked in branches and can be tested before merging
• YAML-based: Easy to read, write, and manage in Git alongside your code
• Self-documenting: Schema definitions include labels, descriptions, and validation rules

​

Schema components

• Nodes: The primary objects in your infrastructure (e.g., Device, Site, VLAN)
• Attributes: Properties of nodes (e.g., name, IP address, status)
  • Types: Text, Number, Boolean, Dropdown, JSON, DateTime, URL, etc.
  • Validation: Unique, optional, regex patterns, min/max values
• Relationships: Connections between nodes
  • Attribute relationships: Simple foreign keys (many-to-one)
  • Component relationships: Parent-child with cascading deletion
  • Generic relationships: Many-to-many associations
  • Hierarchy relationships: For modeling organizational structures

​

Example schema

version: '1.0'
nodes:
  - name: Device
    namespace: Infra
    description: "A network device"
    display_label: "{{ name__value }}"
    attributes:
      - name: name
        kind: Text
        unique: true
      - name: role
        kind: Dropdown
        choices:
          - name: router
            color: "#0099ff"
          - name: switch
            color: "#00cc66"
      - name: status
        kind: Dropdown
        choices:
          - name: active
          - name: planned
        default_value: "active"
    relationships:
      - name: site
        peer: InfraSite
        cardinality: one
        kind: Attribute
      - name: interfaces
        peer: InfraInterface
        cardinality: many
        kind: Component

• GraphQL mutations for creating/updating devices
• UI forms for data entry
• Validation rules
• Database indexes

​

Version control

​

Branching and merging

• Test schema changes without affecting production
• Stage infrastructure updates for review
• Experiment with network designs
• Prepare changes for maintenance windows

• Web UI: Click “Create Branch” from any page
• GraphQL API: BranchCreate mutation
• CLI: infrahubctl branch create

​

Proposed changes

• Diff view: See exactly what will change when merging
• Comments and threads: Collaborate on changes with your team
• Reviews and approvals: Require sign-off before merging
• CI checks: Run automated validation and artifact generation
• Conflict detection: Identify conflicts before merging

​

Immutable history

• Query the state of your infrastructure at any point in time
• Track who made what changes and when
• Audit compliance and troubleshoot issues
• Restore previous states if needed

​

Unified storage

​

Graph database foundation

• Rich relationships: Model complex dependencies between infrastructure components
• Fast traversals: Query relationships efficiently (e.g., “find all devices in site X with status Y”)
• Natural modeling: Infrastructure is inherently a graph (devices connect to interfaces, which connect to VLANs, etc.)
• Temporal branching: Version control is implemented directly in the graph structure

​

Git integration

• Schema definitions: Your data model in YAML
• Transformations: Jinja2 templates and Python code to generate configurations
• Generators: Python code to automate object creation
• GraphQL queries: Reusable queries for data retrieval
• Python scripts: Custom automation and integrations

• Version control for code and data: Both evolve together in branches
• GitOps workflows: Treat infrastructure as code
• Collaboration: Use Git workflows for code review and collaboration

​

Key capabilities

​

Transformations

• Device configurations: Generate vendor-specific configs from unified data
• Documentation: Create network diagrams, cable plans, runbooks
• API payloads: Transform data for external systems (CloudFormation, Terraform, etc.)
• Reports: Generate compliance or inventory reports

​

How Transformations work

1. GraphQL query: Defines what data to retrieve
2. Transformation logic: Jinja2 template or Python class that processes the data

hostname {{ device.name.value }}
!
{% for interface in device.interfaces.edges %}
interface {{ interface.node.name.value }}
  description {{ interface.node.description.value }}
  {% if interface.node.enabled.value %}no shutdown{% else %}shutdown{% endif %}
{% endfor %}

from infrahub_sdk.transforms import InfrahubTransform

class CustomTransform(InfrahubTransform):
    async def transform(self, data: dict) -> dict:
        # Process data and return transformed output
        return {
            "devices": [
                {"name": d["name"]["value"], "role": d["role"]["value"]}
                for d in data["InfraDevice"]["edges"]
            ]
        }

​

Artifacts

• Version tracking: Each artifact has a version tied to a branch and commit
• Storage: Stored in local filesystem or S3-compatible object storage
• Access control: Artifacts can be retrieved via REST API or webhooks
• Change detection: Compare artifacts across branches or over time

• Store generated device configurations
• Trigger deployments via webhooks
• Archive compliance snapshots
• Provide audit trails

​

Generators

1. Define a high-level design (e.g., “Deploy a new site”)
2. Generator creates all necessary objects (devices, interfaces, IP addresses, BGP peers)
3. Transformations generate configurations
4. Review and merge in a proposed change

• Create complex object hierarchies
• Implement business logic and policies
• Allocate resources from pools (IP addresses, VLANs, ASNs)
• Link generated objects back to the design for lifecycle management

• Provision a new data center site
• Deploy a new service instance
• Onboard a new customer
• Roll out a new device type

​

Resource pools

• IP Prefixes and Addresses: RFC 1918 and public IP space
• VLANs: 802.1Q VLAN IDs
• ASNs: BGP autonomous system numbers
• Number pools: Generic integer allocation

• Namespaces: Isolate allocations by region, tenant, or environment
• Hierarchical allocation: Allocate subnets from parent prefixes
• Automatic allocation: Request next available resource
• Conflict detection: Prevent overlapping allocations

​

Interfaces and APIs

​

Web UI

• Object management: Create, read, update, delete objects
• Schema explorer: Browse loaded schema and relationships
• Branch management: Create branches, view diffs, merge changes
• GraphQL sandbox: Test queries and mutations interactively
• Global search: Find objects, documentation, and schema elements
• Proposed change workflows: Review, comment, approve changes

​

GraphQL API

• Schema-driven: Automatically generated from your schema
• Strongly typed: Type-safe queries and mutations
• Flexible querying: Request exactly the data you need
• Relationship traversal: Query across relationships efficiently
• Metadata access: Query created_by, updated_by, timestamps

query GetDevices {
  InfraDevice(role__value: "router") {
    edges {
      node {
        id
        name { value }
        site {
          node {
            name { value }
          }
        }
        interfaces {
          edges {
            node {
              name { value }
              enabled { value }
            }
          }
        }
      }
    }
  }
}

​

Python SDK

• Object-oriented interface for creating and querying data
• Schema introspection and validation
• Batch operations for performance
• Async support for concurrent operations

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

# Create a device
device = await client.create(
    kind="InfraDevice",
    name="router-01",
    role="router",
    status="active"
)
await device.save()

# Query devices
devices = await client.filters(kind="InfraDevice", role__value="router")
for device in devices:
    print(device.name.value)

​

REST API

• Schema loading and retrieval
• Artifact access and download
• Object storage operations
• Saved GraphQL query execution

​

Integrations

• Ansible: Use Infrahub as a dynamic inventory source
• Nornir: Python-based network automation with Infrahub inventory
• Webhooks: Trigger external systems on events (branch merge, artifact generation)
• Git: Sync schemas and code bidirectionally

​

Putting it all together

​

Design-driven automation example

1. Define a service in the schema: Model a “VPN Service” node
2. Create a Generator: Automate creation of routers, interfaces, BGP peers, etc.
3. Create Transformations: Generate device configs from the service data
4. Work in a branch:
   • Create a branch for the new service deployment
   • Run the Generator to create all objects
   • Review generated artifacts
   • Run CI checks
5. Propose the change: Create a proposed change for review
6. Collaborate: Team reviews diffs, comments, requests changes
7. Merge: Approved changes merge to main
8. Deploy: Webhook triggers Ansible playbook to deploy configs

​

Agility in infrastructure management example

1. Plan a major upgrade (e.g., OS version across 100 routers)
2. Create a branch to stage the changes
3. Update the schema (add new OS version attribute)
4. Update Transformations to use new OS version in configs
5. Update data in the branch (set OS version for devices)
6. Generate artifacts for all devices
7. Run tests in the branch (syntax checks, lab deployments)
8. Review in proposed change (diff shows config changes)
9. Merge during maintenance window
10. Deploy configs to production

​

Next steps