Skip to main content

Using the 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.

By the end of this tutorial, you'll understand how to enable the Service Catalog, navigate the interface, view existing infrastructure, and create new data centers through a guided form-based workflow.

What you'll accomplish​

In this tutorial, you will:

  1. Enable the Service Catalog container
  2. Access the web interface
  3. Switch between Infrahub branches
  4. View existing data centers and colocation centers
  5. Visualize rack layouts with device placement
  6. Create a new data center using the web form
  7. Understand the automated workflow behind the scenes

Prerequisites​

Before starting this tutorial, ensure you have:

  • Completed the installation guide and have Infrahub running
  • Completed the user walkthrough tutorial
  • Docker and Docker Compose installed and configured
  • Access to modify environment variables or Docker Compose configuration
tip

The Service Catalog is an optional component that simplifies infrastructure provisioning. It's particularly useful for teams who want a web-based interface for infrastructure requests.

Step 1: enable the service catalog​

The Service Catalog runs as a separate Docker container that can be enabled through environment variables or Docker Compose profiles.

  1. Open your .env file (or create it from .env.example)
  2. Set the Service Catalog variable to true:
INFRAHUB_SERVICE_CATALOG=true
  1. Restart Infrahub to apply the changes:
uv run invoke restart

Verify the container is running​

Check that the service-catalog container is running:

docker ps --filter "name=service-catalog"

You should see a container named infrahub-bundle-dc-service-catalog-1 or similar in the output.

Step 2: access the service catalog​

Once the container is running, access the Service Catalog web interface:

  1. Open your web browser
  2. Navigate to http://localhost:8501
  3. The Service Catalog landing page should load

The interface displays:

  • Branch selector - Dropdown to switch between Infrahub branches
  • Data centers - List of existing TopologyDataCenter objects
  • Colocation centers - List of existing TopologyColocationCenter objects
  • Create new data center - Button to access the DC creation form
info

If the page doesn't load, verify the container is running and check the logs with docker logs infrahub-bundle-dc-service-catalog-1.

Step 3: switch branches and view infrastructure​

The Service Catalog allows you to view infrastructure across different Infrahub branches.

Switch branches​

  1. Locate the branch selector dropdown at the top of the page
  2. Click the dropdown to see all available branches
  3. Select a branch (for example, main, add-dc3, etc.)
  4. The page will refresh and display infrastructure from the selected branch

View existing infrastructure​

After selecting a branch, you'll see two lists:

Data centers​

Each data center card displays:

  • Data center name (for example, DC-1, DC-2, DC-3)
  • Location information
  • Link to view in Infrahub UI

Colocation centers​

Each colocation center card displays:

  • Colocation center name (for example, PAR-1, LON-1)
  • Location information
  • Link to view in Infrahub UI
tip

The lists automatically update when you switch branches, allowing you to see infrastructure in different states (main, proposed changes, feature branches).

Step 4: visualize rack layouts​

The Service Catalog includes a rack visualization page that displays physical rack layouts with mounted devices, similar to NetBox's rack elevation diagrams. This feature helps you understand device placement, rack occupancy, and physical infrastructure organization.

Access rack visualization​

  1. Navigate to the sidebar in the Service Catalog
  2. Click Rack Visualization in the navigation menu
  3. The rack visualization page will load

Understanding the rack view​

The rack visualization displays:

  • Physical rack diagrams - Visual representations of racks with numbered rack units (U1-U42)
  • Mounted devices - Colored rectangles showing device positions and heights
  • Device information - Names, types, and rack unit positions
  • Role-based colors - Visual differentiation by device role

Select a location row​

Before racks appear, you need to select a location row:

  1. Use the Select Location Row dropdown at the top of the page
  2. Choose a row (for example, Row-1 in Pod-1)
  3. All racks in that row will display in a grid layout
info

Location rows are created automatically by the DC generator. Each data center has a Pod (for example, Pod-1) containing a Row (for example, Row-1) with multiple racks.

Reading rack diagrams​

Each rack diagram shows:

Rack units​

  • Numbered from bottom (U1) to top (U42)
  • Each unit represents 1.75 inches of vertical space
  • Devices mount at specific U positions

Device rectangles​

Devices appear as colored rectangles with:

  • Height - 1U, 2U, 4U devices shown proportionally
  • Position - Starting U position labeled (for example, U42, U41)
  • Name or type - Text showing device identifier
  • Role color - Background color indicating device function

For 1U devices, only the device name or type is shown. For multi-unit devices (2U+), both the primary label and secondary information are displayed.

Color coding by role​

The rack visualization uses role-based colors to help identify device types at a glance:

  • Green - Leaf switches (access layer)
  • Blue - Spine switches (aggregation layer)
  • Purple - Border leaf switches (edge connectivity)
  • Orange - Console servers (out-of-band management)
  • Brown - OOB switches (management network)
  • Cyan - Edge routers (WAN connectivity)
  • Red - Firewalls (security devices)

A legend at the bottom of the page explains the color mappings.

Toggle device labels​

You can change what information displays on device rectangles:

  1. Locate the Display Options section in the sidebar
  2. Use the Device Label dropdown
  3. Choose between:
    • Hostname (default) - Shows device name (for example, dc-3-leaf-01)
    • Device Type - Shows hardware model (for example, Arista DCS-7280SR-48C6)

For multi-unit devices, the secondary label shows the alternate information. For instance, if you select "Device Type", the secondary label shows the hostname.

Device placement logic​

The DC generator assigns devices to racks based on predefined rules:

Leaf devices​

  • Assigned to rack numbers matching their device number
  • For example, dc-3-leaf-01 → Rack-1, dc-3-leaf-02 → Rack-2
  • Positioned at the top of the rack (U42 for 1U devices)

Infrastructure devices​

Spine switches, border leafs, console servers, and OOB devices are assigned to middle racks:

  • Spine switches - Positioned below leaf devices
  • Border leaf switches - Positioned below spines
  • Console servers - Positioned below border leafs
  • OOB switches - Positioned at the bottom

This placement strategy ensures infrastructure devices are centrally located for optimal cabling.

Each device in the rack diagram is clickable:

  1. Click any device rectangle
  2. A new browser tab opens showing the device in Infrahub UI
  3. View full device details, interfaces, and relationships

The link preserves the current branch context, so you see the device as it exists in the selected branch.

Example workflow​

Here's how to use rack visualization after creating a data center:

  1. Create a new DC using the Service Catalog form (for example, DC-3)
  2. Wait for the generator to complete
  3. Navigate to Rack Visualization
  4. Switch to the branch containing your DC (for example, add-dc3)
  5. Select the location row (for example, Row-1)
  6. View the generated racks with mounted devices
  7. Verify device placement matches your design
  8. Click devices to inspect details in Infrahub
tip

Rack visualization is particularly useful during proposed change review. Switch to the branch, view rack layouts, and verify devices are positioned correctly before merging to main.

Step 5: create a new data center​

The Service Catalog provides a guided form for creating new data centers.

Access the creation form​

  1. Click the Create New Data Center button
  2. The form page will load with several input fields

Fill in the form​

Complete each field in the form:

1. Data center name​

  • Enter a unique name for your data center (for example, DC-6)
  • This will be used in the branch name and as the DC identifier

2. Location​

  • Select a location from the dropdown
  • Options include existing LocationBuilding objects (for example, PAR-1, LON-1)
  • The location determines where the data center will be deployed

3. Provider​

  • Select a provider from the dropdown
  • Options include existing ProviderNetworkProvider objects
  • The provider supplies connectivity and services

4. Design​

  • Select a design template from the dropdown
  • Options include predefined data center architectures
  • Different designs support different vendors and topologies

5. Management subnet​

  • Select an IP prefix for management interfaces
  • Used for out-of-band device management
  • Choose an available /24 or appropriate size

6. Underlay subnet​

  • Select an IP prefix for underlay routing
  • Used for spine-leaf physical connectivity
  • Typically a /24 or /16 depending on DC size

7. Overlay subnet​

  • Select an IP prefix for overlay services
  • Used for VXLAN and EVPN addressing
  • Usually a /16 or larger for tenant networks

Submit the request​

  1. Review all form fields for accuracy
  2. Click the Submit button
  3. The Service Catalog will display a progress indicator

Step 6: understand the behind-the-scenes workflow​

When you submit the form, the Service Catalog executes an automated workflow that:

1. Creates a branch​

The Service Catalog creates a new branch in Infrahub with the naming pattern add-{dc_name}:

Branch name: add-dc6 (if you named your DC "DC-6")

This branch isolates your new infrastructure from the main branch, allowing review before merging.

2. Loads data to the branch​

The Service Catalog constructs a DesignTopologyDesign YAML object with your form inputs and loads it to the new branch:

nodes:
  - kind: DesignTopologyDesign
    data:
      name: DC-6
      location: PAR-1
      provider: provider-1
      design_template: dc-design-template-1
      mgmt_prefix: 10.0.6.0/24
      underlay_prefix: 192.168.6.0/24
      overlay_prefix: 172.16.0.0/16

3. Waits for the generator​

After loading data, the Service Catalog waits for Infrahub's generator to execute:

  • Default wait time: 60 seconds (configurable via GENERATOR_WAIT_TIME)
  • The generator (for example, create_dc) processes the design data
  • Devices, interfaces, cables, and IP addresses are automatically created

4. Creates a proposed change​

Once the generator completes, the Service Catalog creates a Proposed Change in Infrahub:

  • Compares the new branch to the main branch
  • Shows all differences (new devices, interfaces, configurations)
  • Allows review before merging to production

View the results​

After the workflow completes:

  1. Navigate to Proposed Changes in the Infrahub UI (http://localhost:8000)
  2. Find the proposed change for your DC (for example, "Add DC-6")
  3. Review the Data tab to see new objects
  4. Review the Artifacts tab to see generated configurations
  5. Approve and merge when ready
tip

This workflow demonstrates infrastructure-as-code principles: declarative design data is transformed into imperative implementation through automated generators.

Troubleshooting​

Service catalog container not starting​

If the container fails to start:

  1. Check Docker logs:
docker logs infrahub-bundle-dc-service-catalog-1
  1. Verify environment variables in .env:
INFRAHUB_SERVICE_CATALOG=true
INFRAHUB_ADDRESS=http://infrahub-server:8000
  1. Ensure Infrahub server is running and accessible:
docker ps --filter "name=infrahub-server"

Cannot access http://localhost:8501​

If the web interface doesn't load:

  1. Verify port 8501 is not in use by another application
  2. Check container port mapping:
docker ps --format "table {{.Names}}\t{{.Ports}}" --filter "name=service-catalog"
  1. Try accessing via container IP directly:
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' infrahub-bundle-dc-service-catalog-1

Branch selector is empty​

If no branches appear in the dropdown:

  1. Verify Infrahub server connection from the container:
docker exec infrahub-bundle-dc-service-catalog-1 curl http://infrahub-server:8000/api/schema
  1. Check that branches exist in Infrahub:
uv run infrahubctl branch list
  1. Review Service Catalog logs for API errors:
docker logs infrahub-bundle-dc-service-catalog-1 | grep -i error

Generator timeout errors​

If DC creation fails with timeout errors:

  1. Increase the wait time in .env:
GENERATOR_WAIT_TIME=120  # Increase to 120 seconds
  1. Check generator status in Infrahub UI under Task Management
  2. Verify generator definition is registered in .infrahub.yml

Form submission fails​

If the submit button doesn't work:

  1. Check browser console for JavaScript errors (F12 → Console)
  2. Verify all required fields are filled
  3. Check that selected options (location, provider, design) exist in Infrahub
  4. Review Service Catalog logs during submission:
docker logs -f infrahub-bundle-dc-service-catalog-1

Advanced usage​

Custom default branch​

Change the default branch shown in the branch selector:

# In .env
DEFAULT_BRANCH=production

Adjust timeouts​

Tune timeouts for your environment:

# In .env
GENERATOR_WAIT_TIME=90  # Generator execution wait
API_TIMEOUT=30          # API request timeout
API_RETRY_COUNT=3       # API retry attempts

Integration with CI/CD​

The Service Catalog workflow can be automated via API:

  1. POST form data to Service Catalog endpoint
  2. Wait for branch creation
  3. Run validation checks
  4. Auto-approve proposed changes if checks pass

This enables self-service infrastructure provisioning with approval gates.

What you've learned​

Congratulations! You've explored Infrahub's Service Catalog:

  • ✅ Enabled the Service Catalog container
  • ✅ Accessed the web interface at http://localhost:8501
  • ✅ Switched between branches to view different infrastructure states
  • ✅ Viewed existing data centers and colocation centers
  • ✅ Visualized rack layouts with color-coded device placement
  • ✅ Created a new data center using the guided form
  • ✅ Understood the automated workflow (branch → data → generator → proposed change)

Next steps​

Now that you understand the Service Catalog, you can:

  • Customize the form - Modify service_catalog/pages/create_dc.py to add fields
  • Add validation - Implement checks before submission
  • Extend to other infrastructure types - Create forms for POPs, segments, or services
  • Integrate with approval workflows - Connect to ticketing or change management systems
  • Build custom dashboards - Add Streamlit pages for monitoring and reporting

For deeper understanding: