Best Practices

Best Practices

This page provides recommended practices for creating efficient, maintainable, and scalable dot2net configurations. Focus on overall design principles that span both DOT and YAML configuration.

Topology-Driven Design Principles

Separation of Concerns

✅ Clear role separation:

• DOT files: Define WHAT the network looks like (topology structure)
• YAML files: Define HOW each component should be configured (behavior templates)
• Parameter rules: Define automatic value assignment patterns

❌ Mixing concerns:

• Avoid hardcoding configuration details in DOT files
• Avoid topology assumptions in YAML templates
• Don't duplicate parameter assignments across files

Hierarchical Network Modeling

Network-wide settings → NodeClass values
    ↓
Node-specific config → InterfaceClass inheritance
    ↓
Interface-specific → ConnectionClass sharing
    ↓
Connection parameters → SegmentClass coordination

Design pattern:

1. Start broad: Define network-wide policies and standards
2. Specialize gradually: Add device-specific, interface-specific details
3. Coordinate related objects: Use segments for VLAN management, groups for areas

Automatic Parameter Management

Parameter Assignment Strategy

Maximize automation while maintaining control:

1. Use Parameter Rules for patterns:

   • VLAN IDs: assign: segment for consistent segment-wide assignment
   • Connection IDs: assign: connection for link identification
   • Interface numbers: assign: object for unique per-interface values

2. Reserve manual overrides for exceptions:

   • Special-purpose VLANs (management, backup)
   • Backbone connections with specific requirements
   • Legacy integration constraints

3. Layer parameter coordination:

   • Different layers (IPv4, IPv6, MPLS) can have independent parameter spaces
   • Use layer specification in parameter rules for layer-specific assignments

Cross-Object Reference Design

Leverage parameter symmetry:

• Interface templates can reference: {{ .node_name }}, {{ .conn_vlan_id }}
• Connection templates can reference: {{ .name }}, {{ .conn_id }}
• Avoid complex multi-hop references that reduce maintainability

Scalability and Maintainability

Protocol and Service Modeling

Use layers for protocol separation:

• Separate IPv4, IPv6, MPLS into different layers
• Apply different IP policies per layer
• Enable multi-protocol configurations on same physical topology

Leverage virtual nodes for complex topologies:

• Model logical centralized services (BGP route reflectors, DHCP servers)
• Simplify IP address assignment for hub-and-spoke patterns
• Exclude virtual components from final deployment (virtual: true)

Configuration Template Organization

Choose appropriate template style:

• Hierarchical: For strict dependency control and embedding relationships
• Sort: For flexible configuration assembly with priority-based ordering
• Named templates: For reusable configuration blocks

Manage template complexity:

• Group related configurations using group and sort_group
• Use priority to control ordering within groups
• Leverage depends for explicit template dependencies

Development and Validation Workflow

Incremental Development Approach

1. Start with topology: Define basic network structure in DOT
2. Add device types: Assign NodeClass labels to establish device roles
3. Configure interfaces: Define InterfaceClass behavior per connection type
4. Coordinate segments: Use SegmentClass for network-wide coordination
5. Validate frequently: Check parameter assignment and IP allocation at each stage

Testing and Debugging

Parameter verification workflow:

# 1. Check parameter assignments
dot2net params -c input.yaml input.dot

# 2. Verify IP address allocation
dot2net visual -c input.yaml input.dot | dot -Tpdf > network.pdf

# 3. Test configuration generation
dot2net build -c input.yaml input.dot

# 4. Validate specific platform output
dot2net tinet -c input.yaml input.dot    # TiNET output
dot2net clab -c input.yaml input.dot     # Containerlab output

Common Design Patterns

Hub-and-spoke networks:

• Use virtual hub nodes for IP address coordination
• Apply consistent InterfaceClass to spoke connections
• Leverage SegmentClass for spoke-side VLAN management

Hierarchical data center:

• Separate spine/leaf device roles with NodeClass
• Use ConnectionClass for uplink/downlink differentiation
• Apply ParameterRule with assign: segment for VLAN consistency

Multi-protocol environments:

• Define separate layers for IPv4, IPv6, MPLS
• Use layers attribute in InterfaceClass for protocol-specific configuration
• Coordinate parameter assignment across protocols

Error Prevention and Troubleshooting

Configuration Consistency

Avoid conflicting class assignments:

• Don't assign contradictory InterfaceClass types to same interface
• Ensure ParameterRule ranges don't overlap unintentionally
• Validate ConnectionClass and SegmentClass parameter compatibility

Parameter scope management:

• Use appropriate parameter assignment scope (object, connection, segment)
• Coordinate parameter rules across different object types
• Leverage cross-object references for parameter sharing

Performance Considerations

Optimize for large networks:

• Minimize complex cross-object template references
• Use appropriate parameter assignment scope to reduce computation
• Choose efficient template organization (Hierarchical vs Sort) based on dependency complexity

Template efficiency:

• Prefer direct parameter access over multi-hop references
• Group related configurations for batch processing
• Use named templates for reusable configuration blocks

Following these best practices ensures that your dot2net configurations are maintainable, scalable, and leverage the full power of the topology-driven configuration approach.