feat(docs): add TOSCA-based topology description proposal

Add comprehensive documentation proposing TOSCA (Topology and Orchestration Specification for Cloud Applications) as the standard format for GNS3 network topologies. The document outlines strategic benefits including standardized YAML descriptions, toolchain ecosystem integration, Git-based workflows, and template reuse capabilities. This initiative aims to modernize GNS3 topology management, improve user experience, and align with industry best practices for network automation and orchestration.
2026-08-27 12:30:13 +03:00 · 2026-03-11 22:13:23 +08:00 · 2026-03-11 22:13:23 +08:00 · e82bce9e16
commit e82bce9e16
parent ad3621db0f
1 changed files with 527 additions and 0 deletions
--- a/docs/gns3-copilot/todo/tosca-topology-description.md
+++ b/docs/gns3-copilot/todo/tosca-topology-description.md
@ -0,0 +1,527 @@
+# TOSCA-Based Topology Description for GNS3
+
+## Overview
+
+This document outlines a strategic initiative to adopt **TOSCA (Topology and Orchestration Specification for Cloud Applications)** as the standard format for describing GNS3 network topologies. This approach aims to modernize GNS3 topology management, improve user experience, and align with industry best practices.
+
+## Executive Summary
+
+### Current State
+- GNS3 uses proprietary `.gns3` file format (Python-based)
+- Topology editing requires GUI interface
+- Limited version control capabilities
+- No standard way to share and reuse topologies
+- Difficult to integrate with external automation tools
+
+### Proposed Solution
+- Adopt TOSCA Simple Profile YAML as the standard topology description language
+- Provide dual-mode editing: GUI and YAML
+- Enable template-based topology creation
+- Support version control and collaborative workflows
+- Integrate with TOSCA toolchain ecosystem
+
+### Expected Benefits
+- **Productivity**: 5-10x faster topology creation
+- **Quality**: 80% reduction in configuration errors
+- **Collaboration**: Enable team-based workflows
+- **Portability**: Cross-platform topology definitions
+- **Ecosystem**: Integration with industry-standard tools
+
+---
+
+## Background
+
+### What is TOSCA?
+
+**TOSCA** (Topology and Orchestration Specification for Cloud Applications) is an **OASIS standard** for describing cloud application and service topologies. It provides:
+
+- **Standardized YAML syntax** for defining topologies
+- **Type system** for nodes and relationships
+- **Inheritance mechanisms** for template reuse
+- **Workflow definitions** for orchestration
+- **Portability** across platforms and vendors
+
+### Why TOSCA for GNS3?
+
+| Aspect | Current GNS3 | TOSCA-Based |
+|--------|--------------|-------------|
+| Format | Proprietary Python | Open Standard YAML |
+| Readability | Requires code knowledge | Human-readable |
+| Version Control | Binary/blob-like | Git-friendly |
+| Tooling | GNS3-specific | Rich ecosystem |
+| Learning Curve | Steep | Moderate |
+| Industry Alignment | None | Strong |
+
+---
+
+## Strategic Benefits
+
+### 1. Standardized YAML Description
+
+#### Human-Readable Topology Definitions
+
+**Before (GNS3 .gns3 file):**
+- Proprietary Python-based format
+- Difficult to understand without GUI
+- Requires specialized tools to edit
+
+**After (TOSCA YAML):**
+- Clear, self-documenting structure
+- Edit with any text editor
+- Instant understanding of network architecture
+
+#### Universal Language
+
+- **Standard syntax**: All users use the same language
+- **Reduced training**: Familiar YAML format for DevOps engineers
+- **Cross-team communication**: Network, DevOps, SRE teams share common language
+
+---
+
+### 2. Toolchain Ecosystem
+
+#### Validation Tools
+
+- **Syntax validators**: Catch errors before deployment
+- **Schema validation**: Ensure type correctness
+- **Best practices checkers**: Enforce standards
+- **Integration into CI/CD**: Automated testing pipelines
+
+#### Visualization Tools
+
+- **Auto-generated diagrams**: Visual topology from YAML
+- **Real-time preview**: See changes as you type
+- **Interactive editors**: GUI ↔ YAML bidirectional sync
+
+#### Orchestration Engines
+
+- **Cloudify**: Mature TOSCA orchestrator
+- **OpenStack Heat**: Alternative implementation
+- **Custom tools**: Build on open-source libraries
+
+---
+
+### 3. Version Control and Collaboration
+
+### Git-Friendly Workflows
+
+#### Meaningful Diffs
+
+Before:
+```
+Binary files differ
+```
+
+After:
+```diff
+- node: R1
+ node: Core-Router-1
+    type: router
+    template: c7200
+```
+
+#### Branch Management
+
+- **Feature branches**: Experiment with new topologies
+- **Isolated development**: Multiple parallel changes
+- **Easy merge**: Text-based merge tools
+
+#### Code Review Process
+
+- **Pull Requests**: Review topology changes
+- **Comments and discussions**: Collaborative refinement
+- **Approval workflows**: Maintained standards
+
+### Real-World Scenarios
+
+**Educational Use Case:**
+- Students submit topology homework via Git PRs
+- Teaching assistants review and comment
+- Automated tests verify requirements
+- Track progress over time
+
+**Enterprise Use Case:**
+- Network engineers propose changes
+- Security team reviews compliance
+- Architecture team validates design
+- Manager approves deployment
+
+---
+
+### 4. Template Reuse and Inheritance
+
+### Template Hierarchy
+
+```
+Base Templates
+    ↓
+Industry-Specific Templates
+    ↓
+Organizational Templates
+    ↓
+Project-Specific Topologies
+```
+
+#### Base Templates
+
+- **Standard node types**: Router, Switch, Firewall
+- **Common configurations**: Default settings
+- **Best practices**: Security hardening, performance tuning
+
+#### Domain Templates
+
+- **Enterprise WAN**: Multi-site BGP topology
+- **Data Center**: Spine-leaf fabric
+- **Campus Network**: Hierarchical design
+- **Service Provider**: MPLS backbone
+
+#### Organizational Templates
+
+- **Company standards**: Approved device models
+- **Security policies**: Mandatory configurations
+- **Compliance requirements**: Regulatory constraints
+
+### Efficiency Gains
+
+| Task | Traditional | With Templates |
+|------|-------------|-----------------|
+| Simple topology | 30 minutes | 5 minutes |
+| Complex topology | 2 hours | 30 minutes |
+| Multi-site deployment | Manual | Automated |
+| Consistency check | Manual review | Automated validation |
+
+---
+
+### 5. Cross-Platform Portability
+
+### Vendor Neutrality
+
+TOSCA is an **open standard** supported by:
+- Multiple vendors
+- Open-source projects
+- Toolchain ecosystem
+
+### Multi-Environment Deployment
+
+Same topology definition can deploy to:
+- **GNS3**: Local development and testing
+- **EVE-NG**: Remote lab access
+- **Physical devices**: Production deployment
+- **Cloud platforms**: AWS, Azure, GCP
+
+### Integration with Other Tools
+
+#### Configuration Management
+
+- **Ansible**: Use topology for inventory
+- **Terraform**: Infrastructure as code
+- **Python scripts**: Automation workflows
+
+#### Monitoring and Observability
+
+- **Prometheus**: Monitoring targets from topology
+- **ELK Stack**: Log aggregation
+- **Grafana**: Visualization dashboards
+
+#### CI/CD Pipelines
+
+- **Jenkins/GitLab CI**: Automated testing
+- **GitHub Actions**: Workflow automation
+- **ArgoCD**: GitOps deployments
+
+---
+
+## Technical Approach
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│              User Interfaces                    │
+├─────────────────────────────────────────────────┤
+│  GUI Editor  │  YAML Editor  │  Import/Export │
+└───────────────┴───────────────┴────────────────┘
+                    │
+                    ↓
+┌─────────────────────────────────────────────────┐
+│            TOSCA Parser/Validator               │
+├─────────────────────────────────────────────────┤
+│  Schema Validation  │  Type Checking  │  Lint  │
+└───────────────┴───────────────┴────────────────┘
+                    │
+                    ↓
+┌─────────────────────────────────────────────────┐
+│            GNS3 Core Engine                     │
+├─────────────────────────────────────────────────┤
+│  Node Management  │  Link Management  │  APIs  │
+└─────────────────────────────────────────────────┘
+```
+
+### Schema Design
+
+#### GNS3 Type System
+
+Extend TOSCA standard types with GNS3-specific nodes:
+
+- **Compute Nodes**: Virtual machines, containers
+- **Network Devices**: Routers, switches, firewalls
+- **Links**: Connections between devices
+- **Configurations**: Device-specific settings
+
+#### Backward Compatibility
+
+- **Dual format support**: Read/write both `.gns3` and `.yaml`
+- **Migration tools**: Convert existing topologies
+- **Gradual adoption**: Users can migrate at their own pace
+
+---
+
+## Implementation Plan
+
+### Phase 1: Foundation (3-4 months)
+
+**Goals:**
+- TOSCA parser and validator
+- Basic node type definitions
+- YAML import/export functionality
+- Documentation and tutorials
+
+**Deliverables:**
+- GNS3 TOSCA schema specification
+- YAML parser integration
+- Import/export CLI tools
+- Getting started guide
+
+### Phase 2: GUI Integration (2-3 months)
+
+**Goals:**
+- Bi-directional YAML ↔ GUI editing
+- Real-time validation feedback
+- Visual topology preview
+- Template browser
+
+**Deliverables:**
+- Integrated YAML editor in GNS3 GUI
+- Live validation indicators
+- Template library interface
+- User documentation
+
+### Phase 3: Advanced Features (3-4 months)
+
+**Goals:**
+- Template inheritance and composition
+- Workflow orchestration
+- Testing and validation tools
+- CI/CD integration
+
+**Deliverables:**
+- Template marketplace prototype
+- Automated testing framework
+- Git integration features
+- Best practices guide
+
+### Phase 4: Ecosystem (Ongoing)
+
+**Goals:**
+- Community templates
+- Third-party integrations
+- Advanced tooling
+- Industry partnerships
+
+**Deliverables:**
+- Public template repository
+- Plugin architecture
+- Partner integrations
+- Success stories and case studies
+
+---
+
+## Migration Strategy
+
+### For Users
+
+#### Option 1: Gradual Migration
+
+1. Continue using `.gns3` files
+2. Experiment with YAML for new projects
+3. Convert existing topologies as needed
+4. Fully migrate when comfortable
+
+#### Option 2: Dual-Mode Workflow
+
+1. Edit in YAML for complex topologies
+2. Use GUI for visual adjustments
+3. Export both formats as needed
+4. Choose preferred workflow
+
+#### Option 3: Full Adoption
+
+1. Convert all topologies to YAML
+2. Use YAML as primary format
+3. Export to `.gns3` only when required
+4. Leverage full TOSCA ecosystem
+
+### For Developers
+
+#### Extension Points
+
+- **Custom node types**: Define specialized devices
+- **Validation rules**: Enforce organizational standards
+- **Template libraries**: Share within organization
+- **Tooling integration**: Custom automation scripts
+
+---
+
+## Success Metrics
+
+### User Adoption
+
+- **3 months**: 10% of users try YAML format
+- **6 months**: 30% use YAML regularly
+- **12 months**: 50% adopt YAML as primary format
+- **24 months**: 70%+ adoption
+
+### Quality Improvements
+
+- **Error rate**: 80% reduction in topology errors
+- **Creation time**: 5-10x faster for complex topologies
+- **Documentation**: 100% of topologies self-documenting
+- **Consistency**: Significant improvement in standards compliance
+
+### Ecosystem Growth
+
+- **Template library**: 100+ community templates
+- **Integrations**: 5+ major tool integrations
+- **Case studies**: 10+ published success stories
+- **Community**: Active contributor base
+
+---
+
+## Risk Assessment
+
+### Technical Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Parser complexity | Medium | Use proven libraries |
+| Performance overhead | Low | Optimized parsing |
+| Schema evolution | Medium | Version management |
+| Backward compatibility | Low | Dual format support |
+
+### Adoption Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| User resistance | Medium | Comprehensive training |
+| Learning curve | Medium | Documentation and examples |
+| Tooling gaps | Low | Leverage existing ecosystem |
+| Vendor lock-in | Low | Open standard |
+
+---
+
+## Competitive Analysis
+
+### Similar Approaches
+
+#### Cisco CML (VIRL)
+
+**Strengths:**
+- YAML-based topology definition
+- Mature template system
+- Enterprise features
+
+**Weaknesses:**
+- Proprietary format (not standard TOSCA)
+- Vendor lock-in
+- Limited ecosystem
+
+#### Mininet
+
+**Strengths:**
+- Python API for topology definition
+- SDN research community
+
+**Weaknesses:**
+- Scripting required (no YAML)
+- Limited to Linux networking
+- Not enterprise-ready
+
+#### Our Positioning
+
+**GNS3 with TOSCA:**
+- ✅ Open standard (TOSCA)
+- ✅ Multi-vendor support
+- ✅ Rich ecosystem
+- ✅ Community-driven
+- ✅ Enterprise-ready
+
+---
+
+## Conclusion
+
+### Strategic Value
+
+Adopting TOSCA for GNS3 topology description represents a **significant strategic opportunity**:
+
+1. **Modernization**: Align with industry best practices
+2. **Ecosystem**: Tap into TOSCA toolchain and community
+3. **Collaboration**: Enable team-based workflows
+4. **Portability**: Cross-platform topology definitions
+5. **Scalability**: Support enterprise use cases
+
+### Vision
+
+**"Model once, deploy anywhere"** - A GNS3 topology defined in TOSCA can be:
+- Developed locally
+- Tested in simulation
+- Validated automatically
+- Deployed to multiple environments
+- Shared across teams
+- Evolved through version control
+
+### Call to Action
+
+This initiative represents a **fundamental improvement** to how users interact with GNS3. It requires:
+
+- **Community feedback**: Validate requirements and priorities
+- **Contributor participation**: Build open-source solution
+- **Patience**: Phased rollout over 12-18 months
+- **Investment**: Significant development effort
+
+**Expected outcome:** GNS3 becomes the **de facto standard** for network topology definition, education, and automation.
+
+---
+
+## References
+
+### Standards and Specifications
+
+- [OASIS TOSCA Specification](https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.3)
+- [TOSCA Primer](https://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cspr02.html)
+- [YANG Data Modeling Language (RFC 7950)](https://datatracker.ietf.org/doc/html/rfc7950)
+- [OpenConfig Network Models](https://openconfig.net/)
+
+### Tools and Resources
+
+- [Cloudify TOSCA Orchestrator](https://cloudify.co)
+- [OpenStack Heat](https://docs.openstack.org/heat/latest/)
+- [TOSCA GmbH](https://github.com/oasis-tcs/tosca-governance)
+- [YangCatalog](https://www.yangcatalog.org/)
+
+### Related Projects
+
+- [GNS3 Server](https://github.com/GNS3/gns3-server)
+- [GNS3 documentation](https://docs.gns3.com/)
+- [Network To Code initiatives](https://www.networktocode.com/)
+
+---
+
+**Document Status:** 📋 Design Proposal
+**Category:** Feature Design
+**Priority:** High
+**Complexity:** High
+**Estimated Timeline:** 12-18 months
+
+---
+
+*Last Updated: 2025-03-11*