Skip to main content

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.

By the end of this walkthrough, you'll understand how to use Infrahub's branch-based workflow to safely design, validate, and deploy network infrastructure.

Prerequisites​

Before starting this tutorial, ensure you have:

  • Completed the installation guide and have Infrahub running
  • Loaded the bootstrap data and schemas
  • Access to the Infrahub web interface at http://localhost:8000

What you'll accomplish​

In this tutorial, you will:

  1. Create a new branch for your changes
  2. Load a data center design (DC-3)
  3. Wait for the automatic generator to create devices, interfaces, and connections
  4. Create a proposed change
  5. Review the generated artifacts and validation results
  6. Merge the changes to the main branch

Step 1: Create a new branch​

All changes in Infrahub happen in branches. This allows you to work on infrastructure changes safely without affecting the main branch until you're ready.

  1. Navigate to http://localhost:8000
  2. Click on the branch selector in the top-right corner (shows "main" by default)
  3. Click Create Branch
  4. Enter branch name: add-dc3
  5. Click Create

You should see a success message confirming the branch was created.

tip

Branch names should be descriptive and indicate what changes you're making, like add-dc3, update-security-policies, or fix-bgp-config.

Step 2: Switch to your new branch​

In the web interface:

  1. Click the branch selector in the top-right
  2. Select add-dc3 from the list
  3. The interface should now show add-dc3 as the active branch
info

All subsequent actions will be performed on the add-dc3 branch until you switch back to another branch.

Step 3: load the DC-3 design​

The DC-3 design is a pre-configured data center topology specification that defines:

  • A data center named "DC-3"
  • Spine-leaf fabric architecture
  • Device roles and platform assignments
  • IP address pools and subnets
  • BGP autonomous system configuration

Load the design data onto your branch:

uv run infrahubctl object load objects/dc/dc-arista-s.yml --branch add-dc3

Watch the output for success messages. You should see confirmations that the topology data has been loaded.

Verify the design loaded​

In the web interface:

  1. Ensure you're on the add-dc3 branch
  2. Navigate to Network Topologies → Deployments → Data center
  3. You should see a new entry for DC-3
  4. Click on DC-3 to view its properties

The design specifies high-level parameters like:

  • Data center name and location
  • Number of spines and leaves
  • Underlay routing protocol (eBGP or OSPF)
  • Addressing schemes

Multi-vendor support​

This demo supports multiple network device vendors with pre-configured data center designs. The DC-3 topology you just loaded uses Arista EOS switches, but the demo can generate configurations for several other vendors.

Available vendor designs:

  • Arista EOS - The default DC-3 design with Arista switches (objects/dc/dc-arista-s.yml)
  • Cisco NX-OS - The DC-2 design (objects/dc/dc-cisco-s.yml)
  • Juniper JunOS - DC-5 design with Juniper switches
  • SONiC NOS - DC-4 design with EdgeCore switches running SONiC

Using alternative vendor designs:

To explore Arista EOS configurations, you can use the automated demo command:

uv run invoke demo-dc-arista

This command creates a branch, loads the Arista design, waits for generator completion, then creates a proposed change.

For other vendors, load the design files directly:

# Juniper design (DC-5)
uv run infrahubctl object load objects/dc/dc-juniper-s.yml --branch add-dc5

# SONiC design (DC-4)
uv run infrahubctl object load objects/dc/dc-sonic-border-leafs.yml --branch add-dc4

Each vendor design generates appropriate configurations for that platform's CLI syntax and features. The same workflow (branch creation, design loading, generator execution, proposed change, merge) applies regardless of vendor.

Step 4: Wait for automatic generator execution​

When you loaded the DC-3 design in Step 3, Infrahub automatically triggered a generator action that transforms the abstract design into concrete infrastructure objects including devices, interfaces, IP addresses, and routing configurations.

This automation is configured through an event action (defined in objects/events/98_generator_action.yml) that runs the create_dc generator whenever a data center topology is created or updated.

Monitor generator progress​

Generator execution can take several minutes as it creates hundreds of objects. Monitor the task status:

  1. Navigate to System → Tasks in the left sidebar
  2. Find your generator task in the list (look for create_dc)
  3. Watch the status change from "Pending" to "Running" to "Completed"
info

Generator actions are event-driven automations configured in Infrahub. When you load a data center topology object, the event system automatically triggers the create_dc generator. This eliminates the need for manual generator execution and ensures consistency across deployments.

tip

Generators create infrastructure following best practices. For DC-3, the create_dc generator will create spine switches, leaf switches, border leafs, management connections, fabric peering, loopback interfaces, and BGP configurations.

Step 5: Review generated infrastructure​

Once the generator completes, explore what was created:

View devices​

  1. Navigate to Device Management → Infrastructure → All Devices
  2. You should see multiple devices created:
    • Spine switches (typically 2 or more)
    • Leaf switches (typically 4 or more)
    • Border leaf switches (typically 2)

View interfaces​

Click on any device to see its details including:

  • Physical and loopback interfaces
  • IP addresses assigned to each interface
  • Interface descriptions and roles

View IP prefixes​

Navigate to IP Address Management → IP Prefixes to see:

  • Management network prefixes
  • Loopback prefixes
  • Underlay point-to-point link prefixes

View routing​

Navigate to Routing sections to see:

  • BGP peer groups
  • BGP sessions between spines and leaves
  • Autonomous system assignments

Step 6: Create a proposed change​

Now that you've made changes on your branch, create a proposed change to merge them into main. Proposed changes provide a review mechanism with diffs, validation checks, and artifact generation.

Create the proposed change​

  1. Navigate to Proposed Changes
  2. Click New Proposed Change
  3. Fill in the form:
    • Name: Add DC-3 data center
    • Source Branch: add-dc3
    • Destination Branch: main
    • Description (optional): This change adds the DC-3 data center with spine-leaf fabric
  4. Click Create Proposed Change

Understanding what happens next​

When you create a proposed change, Infrahub automatically:

  • Creates a diff showing all objects added, modified, or deleted
  • Runs validation checks defined in your checks
  • Regenerates all artifacts affected by the changes
  • Runs repository checks if configured

Step 7: Review validations and artifacts​

Navigate to your proposed change to review the results:

View the diff​

  1. Click on the Files or Diff tab
  2. Review all the objects that will be created when you merge
  3. You should see hundreds of additions including:
    • Devices
    • Interfaces
    • IP addresses
    • BGP configurations
    • Routing protocols

Check validation results​

  1. Click on the Checks or Validations tab
  2. Review the validation results
  3. All checks should pass with a green checkmark
  4. If any checks fail, review the error messages and fix issues before merging

Common validations include:

  • Spine connectivity checks - Verify all spines are properly connected
  • Leaf connectivity checks - Verify all leaves are connected to all spines
  • IP address uniqueness - Ensure no duplicate IP assignments
  • BGP configuration - Validate BGP peer groups and sessions

View generated artifacts​

  1. Click on the Artifacts tab
  2. You should see generated artifacts including:
    • Device configurations (one per device)
      • Spine, leaf, and border-leaf configurations in native vendor CLI format
      • For Arista and Juniper leaf switches, additional OpenConfig-formatted configurations demonstrating multi-format output
    • Topology cabling matrix (CSV format) - Complete cabling plan with source/destination interfaces
    • Containerlab topology file - Virtual lab topology definition for testing configurations

Click on any artifact to view its content. For example, view a spine configuration to see the generated CLI commands.

Multi-format configuration rendering:

Infrahub's transformation system can generate multiple configuration formats from the same source data. For Arista EOS and Juniper JunOS leaf switches, you'll find both:

  • Native CLI format - Vendor-specific command syntax ready for deployment
  • OpenConfig format - Standardized, vendor-neutral YANG-based configuration

This demonstrates how a single data model in Infrahub can produce multiple output formats, enabling flexibility in deployment methods (traditional CLI, NETCONF, gNMI, etc.) without duplicating source data.

Infrastructure artifacts:

Beyond device configurations, the generator creates supporting artifacts:

  • CSV cabling matrix - Documents physical connectivity between all devices and interfaces, useful for operations teams during installation and troubleshooting
  • Containerlab topology file - Enables spinning up virtual lab environments that mirror your production topology for testing and validation
tip

Artifacts are regenerated automatically when you create a proposed change. This ensures they always reflect the latest data.

Step 8: Merge the proposed change​

Once you've reviewed everything and all validations pass, you're ready to merge:

  1. In the proposed change view, click the Merge button
  2. Confirm the merge in the dialog
  3. Wait for the merge task to complete

The merge process:

  • Applies all changes from the source branch to the destination branch
  • Runs any post-merge hooks or actions
  • Updates the main branch with your new infrastructure

Verify the merge​

  1. Switch back to the main branch using the branch selector
  2. Navigate to Device Management → Infrastructure → All Devices
  3. You should now see all the DC-3 devices in the main branch
  4. Navigate to Services → Topology Deployments → Data center
  5. Verify that DC-3 appears in the main branch

Step 9: View device configurations​

Now that DC-3 is in the main branch, view the generated device configurations:

  1. Ensure you're on the main branch
  2. Navigate to Device Management → Infrastructure → All Devices
  3. Click on a spine device (for example, dc3-spine1)
  4. Look for an Artifacts section or tab
  5. Click on the spine configuration artifact

You should see a complete device configuration including:

  • Interface configurations
  • IP addressing
  • BGP configuration
  • OSPF configuration (if using OSPF underlay)
  • VxLAN EVPN configuration

What you've learned​

Congratulations! You've completed the full workflow:

  • ✅ Created a branch for your changes
  • ✅ Loaded a topology design
  • ✅ Monitored automatic generator execution to create infrastructure
  • ✅ Created a proposed change with automatic validation
  • ✅ Reviewed diffs, checks, and artifacts
  • ✅ Merged changes to the main branch
  • ✅ Viewed generated device configurations

Next steps​

Now that you understand the basic workflow, you can:

  • Explore variations - Try creating DC-3 or a POP topology
  • Modify designs - Edit the objects/dc/dc-arista-s.yml file to change the topology
  • Add network services - Create Layer 2 or Layer 3 services on top of the fabric
  • Customize configurations - Modify templates in the templates/ directory
  • Add validation checks - Create custom checks in the checks/ directory

For a deeper understanding, continue to:

Troubleshooting​

Generator fails or times out​

If the generator task fails:

  1. Check the task logs in System → Tasks
  2. Look for error messages indicating what went wrong
  3. Common issues include missing data, incorrect schema relationships, or resource allocation failures

Validation checks fail​

If validation checks fail:

  1. Review the check output to understand what failed
  2. Fix the underlying data issues
  3. Re-run validations by updating the proposed change

Merge conflicts​

If you encounter merge conflicts:

  1. Review the conflicting objects
  2. Resolve conflicts manually if needed
  3. You may need to rebase your branch or create a new branch