STAGE6_QUICKSTART.md

# Stage 6 - Quick Start Guide

## ✅ Installation Complete

**Libraries Installed:**
```bash
pip install netmiko>=4.0.0 napalm>=5.0.0 jinja2>=3.1.0
```

**Test Results:** ✅ 23/23 tests passing

---

## 🚀 Quick Start Examples

### 1. List Available Devices
```bash
python examples/deploy_to_gns3_lab.py --list
```

### 2. Dry-Run Deployment (Safe Testing)
```bash
# Test single device (no changes made)
python examples/deploy_to_gns3_lab.py --device R1 --dry-run

# Test all devices
python examples/deploy_to_gns3_lab.py --all --dry-run
```

### 3. Production Deployment
```bash
# Deploy to single device (REAL CHANGES!)
python examples/deploy_to_gns3_lab.py --device R1 --production

# Deploy to all devices
python examples/deploy_to_gns3_lab.py --all --production
```

### 4. Custom Credentials
```bash
python examples/deploy_to_gns3_lab.py --device SW1 \
  --username admin \
  --password mysecret \
  --dry-run
```

---

## 📝 Before First Deployment

### Update Device Inventory

Edit `examples/deploy_to_gns3_lab.py` and update the `GNS3_DEVICES` list with your actual device IPs:

```python
GNS3_DEVICES = [
    {
        'name': 'R1',
        'hostname': '192.168.1.1',  # ← UPDATE THIS
        'device_type': DeviceType.CISCO_IOS,
        'vendor': 'cisco',
        'model': '7200',
        'role': 'router',
        'description': 'Core Router 1'
    },
    # ... add more devices
]
```

### Find Your GNS3 Device IPs

**Option 1 - From GNS3 Web UI:**
1. Go to http://lab.grahampaasch.com:3080
2. Open the "overgrowth" project
3. Right-click each device → "Console"
4. Run `show ip interface brief` to get management IP

**Option 2 - Use GNS3 API:**
```bash
# List all nodes in project
curl http://lab.grahampaasch.com:3080/v2/projects

# Get device details
curl http://lab.grahampaasch.com:3080/v2/projects/<project-id>/nodes
```

---

## 🧪 Run Tests

```bash
# Run all Stage 6 tests
python -m pytest tests/test_deployment_engine.py -v

# Run specific test
python -m pytest tests/test_deployment_engine.py::TestDeviceDriver::test_cisco_ios_connection -v

# Run with detailed output
python tests/test_deployment_engine.py
```

---

## 🔧 Programmatic Usage

### Example 1: Deploy with Template
```python
from agent.deployment_engine import DeploymentEngine
from agent.device_driver import DeviceType

engine = DeploymentEngine(use_napalm=True)

device = {
    'name': 'SW1',
    'vendor': 'cisco',
    'model': 'catalyst',
    'role': 'switch',
    'mgmt_ip': '192.168.1.10',
    'interfaces': []
}

network_context = {
    'vlans': [
        {'id': 10, 'name': 'Data'},
        {'id': 20, 'name': 'Voice'}
    ],
    'domain_name': 'lab.local',
    'ntp_servers': ['192.168.1.1'],
    'dns_servers': ['8.8.8.8', '8.8.4.4']
}

credentials = {
    'username': 'admin',
    'password': 'cisco',
    'device_type': DeviceType.CISCO_IOS
}

# Generate config from template and deploy
result = engine.generate_and_deploy(
    device=device,
    network_context=network_context,
    credentials=credentials,
    dry_run=True,  # Set to False for production
    pre_checks=['command:show version'],
    post_checks=['interface:GigabitEthernet0/1']
)

print(f"Status: {result.status.value}")
print(f"Config deployed: {len(result.config_deployed)} chars")
```

### Example 2: Deploy Custom Config
```python
from agent.deployment_engine import DeploymentEngine, DeploymentTask
from agent.device_driver import DeviceType

engine = DeploymentEngine(use_napalm=True)

config = """
hostname R1
!
interface GigabitEthernet0/0
 ip address 10.0.0.1 255.255.255.252
 no shutdown
!
router ospf 1
 network 10.0.0.0 0.0.0.3 area 0
!
end
"""

task = DeploymentTask(
    device_id="R1",
    device_type=DeviceType.CISCO_IOS,
    hostname="192.168.1.1",
    username="admin",
    password="cisco",
    config=config,
    dry_run=False,  # Production deployment
    pre_checks=["ping:192.168.1.1"],
    post_checks=["command:show ip interface brief"]
)

result = engine.deploy_single_device(task)
```

### Example 3: Deploy to Multiple Devices
```python
from agent.deployment_engine import DeploymentEngine, DeploymentTask
from agent.device_driver import DeviceType

engine = DeploymentEngine(use_napalm=True)

tasks = [
    DeploymentTask(
        device_id="R1",
        device_type=DeviceType.CISCO_IOS,
        hostname="192.168.1.1",
        username="admin",
        password="cisco",
        config="hostname R1",
        dry_run=True
    ),
    DeploymentTask(
        device_id="R2",
        device_type=DeviceType.CISCO_IOS,
        hostname="192.168.1.2",
        username="admin",
        password="cisco",
        config="hostname R2",
        dry_run=True
    ),
]

results = engine.deploy_multiple_devices(tasks, parallel=False)

for result in results:
    print(f"{result.device_id}: {result.status.value}")
```

---

## 📚 Available Templates

1. **cisco_ios_l2_switch** - Cisco IOS L2 access switch
2. **cisco_ios_l3_router** - Cisco IOS L3 router with routing
3. **cisco_ios_router** - Basic Cisco IOS router
4. **arista_eos** - Arista EOS switch/router
5. **juniper_junos** - Juniper JunOS device

See `DEPLOYMENT_GUIDE.md` for template details and variables.

---

## 🔍 Validation Checks

### Pre-Deployment Checks (before config is applied)
- `ping:192.168.1.1` - Verify device is reachable
- `command:show version` - Verify device responds
- `interface:GigabitEthernet0/1` - Check interface exists

### Post-Deployment Checks (after config is applied)
- `command:show running-config | include hostname` - Verify config
- `interface:Vlan10` - Verify new VLAN interface exists
- `ping:10.0.0.1` - Verify routing works

---

## ⚠️ Troubleshooting

### Connection Timeout
```
ERROR - Cannot connect to 192.168.1.1
```
**Solution:** 
- Verify device IP is correct
- Check device is powered on in GNS3
- Verify SSH is enabled: `ip ssh version 2`
- Check firewall/network connectivity

### Authentication Failed
```
ERROR - Authentication failed
```
**Solution:**
- Verify username/password are correct
- Check device AAA configuration
- Try with enable password: `credentials={'secret': 'enable-password'}`

### Template Not Found
```
WARNING - No specific template for vendor model
```
**Solution:**
- Check device vendor/model fields
- Use explicit template: `engine.render_template('cisco_ios_l2_switch', context)`

### Dry-Run Mode Not Working
**Solution:** Dry-run is enabled by default for safety. Use `--production` flag to actually deploy.

---

## 📖 Next Steps

1. **Update Device IPs** in `examples/deploy_to_gns3_lab.py`
2. **Run Dry-Run Test** to verify connectivity
3. **Deploy to Test Device** (one device first)
4. **Verify Deployment** via console or SSH
5. **Deploy to Remaining Devices**
6. **Setup Rollback Testing** (Todo #4)
7. **Test Parallel Deployment** (Todo #5)

---

## 🎯 Current Status

✅ **Todo 1:** Install netmiko, napalm, jinja2  
✅ **Todo 2:** Create test suite (23/23 passing)  
🔄 **Todo 3:** Test with GNS3 lab devices (ready - need to update IPs)  
⏳ **Todo 4:** Verify rollback functionality  
⏳ **Todo 5:** Test parallel deployment  

---

## 📞 Support

- **Full Documentation:** `DEPLOYMENT_GUIDE.md`
- **Test Suite:** `tests/test_deployment_engine.py`
- **Example Script:** `examples/deploy_to_gns3_lab.py`
- **Source Code:** `agent/deployment_engine.py`, `agent/device_driver.py`, `agent/config_templates.py`

**For questions, check the test suite - it demonstrates all features!**