bakery-ia/docs/04-development/tilt-vs-skaffold.md

# Skaffold vs Tilt - Which to Use?

**Quick Decision Guide**

---

## 🏆 Recommendation: **Use Tilt**

For the Bakery IA platform with the new security features, **Tilt is recommended** for local development.

---

## 📊 Comparison

| Feature | Tilt | Skaffold |
|---------|------|----------|
| **Security Setup** | ✅ Automatic local resource | ✅ Pre-deployment hooks |
| **Speed** | ⚡ Faster (selective rebuilds) | 🐢 Slower (full rebuilds) |
| **Live Updates** | ✅ Hot reload (no rebuild) | ⚠️ Full rebuild only |
| **UI Dashboard** | ✅ Built-in (localhost:10350) | ❌ None (CLI only) |
| **Resource Grouping** | ✅ Labels (databases, services, etc.) | ❌ Flat list |
| **TLS Verification** | ✅ Built-in verification step | ❌ Manual verification |
| **PVC Verification** | ✅ Built-in verification step | ❌ Manual verification |
| **Debugging** | ✅ Easy (visual dashboard) | ⚠️ Harder (CLI only) |
| **Learning Curve** | 🟢 Easy | 🟢 Easy |
| **Memory Usage** | 🟡 Moderate | 🟢 Light |
| **Python Hot Reload** | ✅ Instant (kill -HUP) | ❌ Full rebuild |
| **Shared Code Sync** | ✅ Automatic | ❌ Full rebuild |
| **CI/CD Ready** | ⚠️ Not recommended | ✅ Yes |

---

## 🚀 Use Tilt When:

- ✅ **Local development** (daily work)
- ✅ **Frequent code changes** (hot reload saves time)
- ✅ **Working on multiple services** (visual dashboard helps)
- ✅ **Debugging** (easier to see what's happening)
- ✅ **Security testing** (built-in verification)

**Commands:**
```bash
# Start development
tilt up -f Tiltfile.secure

# View dashboard
open http://localhost:10350

# Work on specific services only
tilt up auth-service inventory-service
```

---

## 🏗️ Use Skaffold When:

- ✅ **CI/CD pipelines** (automation)
- ✅ **Production-like testing** (full rebuilds ensure consistency)
- ✅ **Integration testing** (end-to-end flows)
- ✅ **Resource-constrained environments** (uses less memory)
- ✅ **Minimal tooling** (no dashboard needed)

**Commands:**
```bash
# Development mode
skaffold dev -f skaffold-secure.yaml

# Production build
skaffold run -f skaffold-secure.yaml -p prod

# Debug mode with port forwarding
skaffold dev -f skaffold-secure.yaml -p debug
```

---

## 📈 Performance Comparison

### Tilt (Secure Mode)

**First Start:**
- Security setup: ~5 seconds
- Database pods: ~30 seconds
- Services: ~60 seconds
- **Total: ~95 seconds**

**Code Change (Python):**
- Sync code: instant
- Restart uvicorn: 1-2 seconds
- **Total: ~2 seconds** ✅

**Shared Library Change:**
- Sync to all services: instant
- Restart all services: 5-10 seconds
- **Total: ~10 seconds** ✅

### Skaffold (Secure Mode)

**First Start:**
- Security hooks: ~5 seconds
- Build all images: ~5 minutes
- Deploy: ~60 seconds
- **Total: ~6 minutes**

**Code Change (Python):**
- Rebuild image: ~30 seconds
- Redeploy: ~15 seconds
- **Total: ~45 seconds** 🐢

**Shared Library Change:**
- Rebuild all services: ~5 minutes
- Redeploy: ~60 seconds
- **Total: ~6 minutes** 🐢

---

## 🎯 Real-World Scenarios

### Scenario 1: Fixing a Bug in Auth Service

**With Tilt:**
```bash
1. Edit services/auth/app/api/endpoints/login.py
2. Save file
3. Wait 2 seconds for hot reload
4. Test in browser
✅ Total time: 2 seconds
```

**With Skaffold:**
```bash
1. Edit services/auth/app/api/endpoints/login.py
2. Save file
3. Wait 30 seconds for rebuild
4. Wait 15 seconds for deployment
5. Test in browser
⏱️ Total time: 45 seconds
```

### Scenario 2: Adding Feature to Shared Library

**With Tilt:**
```bash
1. Edit shared/database/base.py
2. Save file
3. All services reload automatically (10 seconds)
4. Test across services
✅ Total time: 10 seconds
```

**With Skaffold:**
```bash
1. Edit shared/database/base.py
2. Save file
3. All services rebuild (5 minutes)
4. All services redeploy (1 minute)
5. Test across services
⏱️ Total time: 6 minutes
```

### Scenario 3: Testing TLS Configuration

**With Tilt:**
```bash
1. Start Tilt: tilt up -f Tiltfile.secure
2. View dashboard
3. Check "security-setup" resource (green = success)
4. Check "verify-tls" resource (manual trigger)
5. See verification results in UI
✅ Visual feedback at every step
```

**With Skaffold:**
```bash
1. Start Skaffold: skaffold dev -f skaffold-secure.yaml
2. Watch terminal output
3. Manually run: kubectl exec ... (to test TLS)
4. Check logs manually
⏱️ More manual steps, no visual feedback
```

---

## 🔐 Security Features Comparison

### Tilt (Tiltfile.secure)

**Security Setup:**
```python
# Automatic local resource runs first
local_resource('security-setup',
    cmd='kubectl apply -f infrastructure/kubernetes/base/secrets.yaml ...',
    labels=['security'],
    auto_init=True)

# All databases depend on security-setup
k8s_resource('auth-db', resource_deps=['security-setup'], ...)
```

**Built-in Verification:**
```python
# Automatic TLS verification
local_resource('verify-tls',
    cmd='Check if TLS certs are mounted...',
    resource_deps=['auth-db', 'redis'])

# Automatic PVC verification
local_resource('verify-pvcs',
    cmd='Check if PVCs are bound...')
```

**Benefits:**
- ✅ Security runs before anything else
- ✅ Visual confirmation in dashboard
- ✅ Automatic verification
- ✅ Grouped by labels (security, databases, services)

### Skaffold (skaffold-secure.yaml)

**Security Setup:**
```yaml
deploy:
  kubectl:
    hooks:
      before:
        - host:
            command: ["kubectl", "apply", "-f", "secrets.yaml"]
        # ... more hooks
```

**Verification:**
- ⚠️ Manual verification required
- ⚠️ No built-in checks
- ⚠️ Rely on CLI output

**Benefits:**
- ✅ Runs before deployment
- ✅ Simple hook system
- ✅ CI/CD friendly

---

## 💡 Best of Both Worlds

**Recommended Workflow:**

1. **Daily Development:** Use Tilt
   ```bash
   tilt up -f Tiltfile.secure
   ```

2. **Integration Testing:** Use Skaffold
   ```bash
   skaffold run -f skaffold-secure.yaml
   ```

3. **CI/CD:** Use Skaffold
   ```bash
   skaffold run -f skaffold-secure.yaml -p prod
   ```

---

## 📝 Migration Guide

### Switching from Skaffold to Tilt

**Current setup:**
```bash
skaffold dev
```

**New setup:**
```bash
# Install Tilt (if not already)
brew install tilt-dev/tap/tilt  # macOS
# or download from: https://tilt.dev

# Use secure Tiltfile
tilt up -f Tiltfile.secure

# View dashboard
open http://localhost:10350
```

**No code changes needed!** Both use the same Kubernetes manifests.

### Keeping Skaffold for CI/CD

```yaml
# .github/workflows/deploy.yml
- name: Deploy to staging
  run: |
    skaffold run -f skaffold-secure.yaml -p prod
```

---

## 🎓 Learning Resources

### Tilt
- Documentation: https://docs.tilt.dev
- Tutorial: https://docs.tilt.dev/tutorial.html
- Examples: https://github.com/tilt-dev/tilt-example-python

### Skaffold
- Documentation: https://skaffold.dev/docs/
- Tutorial: https://skaffold.dev/docs/tutorials/
- Examples: https://github.com/GoogleContainerTools/skaffold/tree/main/examples

---

## 🏁 Conclusion

**For Bakery IA development:**

| Use Case | Tool | Reason |
|----------|------|--------|
| Daily development | **Tilt** | Fast hot reload, visual dashboard |
| Quick fixes | **Tilt** | 2-second updates vs 45-second rebuilds |
| Multi-service work | **Tilt** | Labels and visual grouping |
| Security testing | **Tilt** | Built-in verification steps |
| CI/CD | **Skaffold** | Simpler, more predictable |
| Production builds | **Skaffold** | Industry standard for CI/CD |

**Bottom line:** Use Tilt for development, Skaffold for CI/CD.

---

**Last Updated:** October 18, 2025