# GAL v1.3.0 - Implementierungsplan

**Target Release:** Q2 2026
**Focus:** Import/Migration & Provider Portability
**Estimated Effort:** 12 Wochen

---

## 🎯 Mission

**Provider Lock-in brechen:** Ermögliche Migration bestehender Gateway-Konfigurationen zu GAL und damit zu jedem anderen Provider.

### Vision

Unternehmen mit bestehenden Gateway-Deployments (Nginx, HAProxy, Kong, etc.) können ihre Konfigurationen **automatisch zu GAL konvertieren** und damit:
1. **Portabilität gewinnen** - Wechsel zu anderem Provider in Minuten statt Wochen
2. **Vendor Lock-in vermeiden** - Nicht mehr an einen Provider gebunden
3. **Multi-Provider nutzen** - Gleiche Config auf verschiedenen Providern
4. **Migration vereinfachen** - Nginx → HAProxy, Kong → Envoy, etc.

---

## 📋 Feature Overview

| # | Feature | Priority | Status | Effort | Dependencies |
|---|---------|----------|--------|--------|--------------|
| 1 | Envoy Import (YAML Parser) | 🔴 High | 🔄 Pending | 1 Woche | - |
| 2 | Kong Import (YAML Parser) | 🔴 High | 🔄 Pending | 1 Woche | Feature 1 |
| 3 | APISIX Import (JSON/YAML Parser) | 🔴 High | 🔄 Pending | 1 Woche | Features 1-2 |
| 4 | Traefik Import (YAML Parser) | 🔴 High | 🔄 Pending | 1 Woche | Features 1-3 |
| 5 | Nginx Import (Custom Parser) | 🔴 High | 🔄 Pending | 2 Wochen | Features 1-4 |
| 6 | HAProxy Import (Custom Parser) | 🔴 High | 🔄 Pending | 2 Wochen | Features 1-5 |
| 7 | Compatibility Checker & Comparison | 🟡 Medium | 🔄 Pending | 2 Wochen | Features 1-6 |
| 8 | Migration Assistant (Interactive CLI) | 🟡 Medium | 🔄 Pending | 2 Wochen | Features 1-7 |

**Total Estimated Effort:** 12 Wochen
**Progress:** 0/8 Features completed (0%)

**Release Strategy:**
- **v1.3.0-alpha1** (Week 2): Envoy + Kong Import ✅
- **v1.3.0-alpha2** (Week 4): + APISIX + Traefik Import ✅
- **v1.3.0-beta1** (Week 6): + Nginx Import ✅
- **v1.3.0-beta2** (Week 8): + HAProxy Import ✅
- **v1.3.0-rc1** (Week 10): + Compatibility Checker ✅
- **v1.3.0 Final** (Week 12): + Migration Assistant ✅

---

## 🎯 Shared Infrastructure (All Features)

### Provider Interface Extension

**File:** `gal/provider.py`

```python
from abc import ABC, abstractmethod
from typing import List, Dict, Any

class Provider(ABC):
    """Abstract base class for all gateway providers."""

    @abstractmethod
    def parse(self, provider_config: str) -> Config:
        """Parse provider-specific config to GAL (NEU!)."""
        pass

    def get_import_warnings(self) -> List[str]:
        """Return warnings from last parse operation."""
        return []

    def get_import_report(self) -> Dict[str, Any]:
        """Return detailed import report."""
        return {
            "features_mapped": [],
            "features_skipped": [],
            "warnings": [],
            "provider_specific": {}
        }
```

### CLI Command: `gal import`

```bash
# Import provider config to GAL
gal import --provider nginx --input nginx.conf --output gal-config.yaml

# Dry-run to preview
gal import --provider envoy --input envoy.yaml --dry-run

# With import report
gal import --provider haproxy --input haproxy.cfg --output gal.yaml --report import-report.json
```

### Feature Mapping Matrix

| GAL Feature | Envoy | Kong | APISIX | Traefik | Nginx | HAProxy |
|-------------|-------|------|--------|---------|-------|---------|
| Routing (path_prefix) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Methods (GET, POST) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Upstream (targets) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Load Balancing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Rate Limiting | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Basic Auth | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ |
| JWT Auth | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | ⚠️ |
| Headers | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| CORS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Health Checks | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ |

---

## 📦 Feature 1: Envoy Import (YAML Parser)

**Status:** 🔄 Pending | **Effort:** 1 Woche | **Release:** v1.3.0-alpha1

### Scope

Parse Envoy `envoy.yaml` → GAL `Config`

**Mapping:**
- `static_resources.listeners` → `global_config` (host, port)
- `static_resources.clusters` → `services` mit `upstream`
- `route_config.virtual_hosts.routes` → `routes`
- `load_assignment` → `upstream.targets`

**Implementation:**
```python
class EnvoyProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        envoy_config = yaml.safe_load(provider_config)
        return Config(
            version="1.0",
            provider="envoy",
            global_config=self._parse_global(envoy_config),
            services=self._parse_services(envoy_config)
        )
```

**Tests:** 50+ tests für alle Features

**📖 Detail-Dokumentation:** [docs/import/envoy.md](import/envoy.md)

---

## 📦 Feature 2: Kong Import (YAML Parser)

**Status:** 🔄 Pending | **Effort:** 1 Woche | **Release:** v1.3.0-alpha1

### Scope

Parse Kong `kong.yaml` → GAL `Config`

**Mapping:**
- `services[]` → GAL `services[]`
- `routes[]` → GAL `routes[]`
- `upstreams[]` → GAL `upstream.targets[]`
- `plugins[]` → GAL features (rate_limit, auth, headers, cors)

**Implementation:**
```python
class KongProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        kong_config = yaml.safe_load(provider_config)
        return Config(
            version="1.0",
            provider="kong",
            services=self._parse_kong_services(kong_config)
        )
```

**Tests:** 40+ tests für Services, Routes, Upstreams, Plugins

**📖 Detail-Dokumentation:** [docs/import/kong.md](import/kong.md)

---

## 📦 Feature 3: APISIX Import (JSON/YAML Parser)

**Status:** 🔄 Pending | **Effort:** 1 Woche | **Release:** v1.3.0-alpha2

### Scope

Parse APISIX `apisix.json` oder `apisix.yaml` → GAL `Config`

**Mapping:**
- `routes[]` → GAL `routes[]`
- `services[]` → GAL `services[]`
- `upstreams[]` → GAL `upstream.targets[]`
- `plugins[]` → GAL features

**Implementation:**
```python
class APISIXProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        # Support both JSON and YAML
        try:
            apisix_config = json.loads(provider_config)
        except:
            apisix_config = yaml.safe_load(provider_config)

        return Config(
            version="1.0",
            provider="apisix",
            services=self._parse_apisix_services(apisix_config)
        )
```

**Tests:** 45+ tests für JSON und YAML Format

**📖 Detail-Dokumentation:** [docs/import/apisix.md](import/apisix.md)

---

## 📦 Feature 4: Traefik Import (YAML Parser)

**Status:** 🔄 Pending | **Effort:** 1 Woche | **Release:** v1.3.0-alpha2

### Scope

Parse Traefik `traefik.yaml` → GAL `Config`

**Mapping:**
- `http.routers` → GAL `routes[]`
- `http.services` → GAL `services[]`
- `http.services.loadBalancer.servers` → GAL `upstream.targets[]`
- `http.middlewares` → GAL features (rate_limit, auth, headers, cors)

**Implementation:**
```python
class TraefikProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        traefik_config = yaml.safe_load(provider_config)
        http_config = traefik_config.get("http", {})

        return Config(
            version="1.0",
            provider="traefik",
            services=self._parse_traefik_services(http_config)
        )
```

**Tests:** 40+ tests für Routers, Services, Middlewares

**📖 Detail-Dokumentation:** [docs/import/traefik.md](import/traefik.md)

---

## 📦 Feature 5: Nginx Import (Custom Parser)

**Status:** 🔄 Pending | **Effort:** 2 Wochen | **Release:** v1.3.0-beta1

### Scope

Parse Nginx `nginx.conf` (non-YAML!) → GAL `Config`

**Challenge:** Nginx config ist **kein structured format**!

**Lösung:** Custom Parser mit Library (z.B. `crossplane`)

**Mapping:**
- `http.upstream` → GAL `upstream.targets[]`
- `http.server.location` → GAL `routes[]`
- `limit_req_zone` → GAL `rate_limit`
- `proxy_set_header` → GAL `headers`

**Implementation:**
```python
from gal.parsers.nginx_parser import NginxConfigParser

class NginxProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        parser = NginxConfigParser()
        nginx_blocks = parser.parse(provider_config)

        return Config(
            version="1.0",
            provider="nginx",
            services=self._parse_nginx_services(nginx_blocks)
        )
```

**Custom Parser:** `gal/parsers/nginx_parser.py`
```python
class NginxConfigParser:
    """Parse nginx.conf using crossplane library."""

    def parse(self, config_text: str) -> dict:
        import crossplane
        parsed = crossplane.parse(config_text)
        return self._normalize(parsed)
```

**Tests:** 60+ tests für nginx.conf Format, Upstreams, Locations

**📖 Detail-Dokumentation:** [docs/import/nginx.md](import/nginx.md)

---

## 📦 Feature 6: HAProxy Import (Custom Parser)

**Status:** 🔄 Pending | **Effort:** 2 Wochen | **Release:** v1.3.0-beta2

### Scope

Parse HAProxy `haproxy.cfg` (non-YAML!) → GAL `Config`

**Challenge:** HAProxy config ist **section-based format**!

**Lösung:** Custom Parser (simpler als Nginx - section-basiert)

**Mapping:**
- `frontend` → Routing ACLs → GAL `routes[]`
- `backend` → Servers → GAL `services[]`, `upstream.targets[]`
- `stick-table` → GAL `rate_limit`
- `http-request set-header` → GAL `headers`

**Implementation:**
```python
from gal.parsers.haproxy_parser import HAProxyConfigParser

class HAProxyProvider(Provider):
    def parse(self, provider_config: str) -> Config:
        parser = HAProxyConfigParser()
        haproxy_config = parser.parse(provider_config)

        return Config(
            version="1.0",
            provider="haproxy",
            services=self._parse_haproxy_services(haproxy_config)
        )
```

**Custom Parser:** `gal/parsers/haproxy_parser.py`
```python
class HAProxyConfigParser:
    """Parse haproxy.cfg section-based format."""

    def parse(self, config_text: str) -> dict:
        sections = {}
        for line in config_text.split('\n'):
            # Parse global, defaults, frontend, backend sections
            pass
        return sections
```

**Tests:** 55+ tests für haproxy.cfg Format, Frontends, Backends, ACLs

**📖 Detail-Dokumentation:** [docs/import/haproxy.md](import/haproxy.md)

---

## ✅ Feature 7: Compatibility Checker & Comparison

**Status:** 🔄 Pending | **Effort:** 2 Wochen | **Release:** v1.3.0-rc1 | **Dependencies:** Features 1-6

### Motivation

Nach Import muss der Nutzer wissen:
- Funktioniert die GAL-Config auf dem Ziel-Provider?
- Welche Features werden unterstützt?
- Welcher Provider ist am besten geeignet?

### CLI Commands

**Check Compatibility:**
```bash
gal validate --config gal-config.yaml --target-provider haproxy

# Output:
# ✓ Config is compatible with HAProxy
# ⚠ Warnings:
#   - JWT authentication requires Lua scripting
#   - Active health checks fully supported
#
# Compatibility: 95% (19/20 features supported)
```

**Compare Providers:**
```bash
gal compare --config gal-config.yaml --providers envoy,kong,nginx,haproxy

# Output (table):
# Feature           | Envoy | Kong | Nginx | HAProxy
# ------------------|-------|------|-------|--------
# Rate Limiting     | ✅    | ✅   | ✅    | ✅
# JWT Auth          | ✅    | ✅   | ⚠️    | ⚠️
# Active HC         | ✅    | ✅   | ❌    | ✅
# Load Balancing    | ✅    | ✅   | ✅    | ✅
#
# Recommendation: Use Envoy or Kong for full compatibility
```

### Implementation

**File:** `gal/compatibility.py`

```python
class CompatibilityChecker:
    """Check config compatibility with providers."""

    def check_provider(self, config: Config, target_provider: str) -> CompatibilityReport:
        """Check if config works on target provider."""
        provider = get_provider(target_provider)

        report = CompatibilityReport(
            provider=target_provider,
            compatible=True,
            features_supported=[],
            features_unsupported=[],
            warnings=[]
        )

        # Check each feature
        for service in config.services:
            self._check_service_features(service, provider, report)

        return report

    def compare_providers(self, config: Config, providers: List[str]) -> Dict[str, CompatibilityReport]:
        """Compare config compatibility across providers."""
        results = {}
        for provider_name in providers:
            results[provider_name] = self.check_provider(config, provider_name)
        return results
```

**Tests:** 40+ tests für Compatibility Checking, Provider Comparison

**📖 Detail-Dokumentation:** [docs/import/compatibility.md](import/compatibility.md)

---

## 🔀 Feature 8: Migration Assistant (Interactive CLI)

**Status:** 🔄 Pending | **Effort:** 2 Wochen | **Release:** v1.3.0 Final | **Dependencies:** Features 1-7

### Motivation

Migration sollte geführt, einfach und sicher sein:
- Interaktive Prompts
- Automatische Validierung
- Migration Report (Markdown)
- Recommendations & Next Steps

### Interactive Workflow

```bash
gal migrate

# Interactive prompts:
? Source Provider: nginx
? Source Config: /etc/nginx/nginx.conf
? Target Provider: haproxy
? Output Directory: ./migration/

[1/5] Reading Nginx config...
[2/5] Parsing and analyzing...
[3/5] Converting to GAL format...
[4/5] Validating compatibility with HAProxy...
[5/5] Generating HAProxy config...

✓ Migration complete!

Files created:
  - ./migration/gal-config.yaml (GAL format)
  - ./migration/haproxy.cfg (HAProxy config)
  - ./migration/migration-report.md (Migration report)

Compatibility: 95% (19/20 features)
Warnings: 2
  - JWT auth requires Lua (see docs)
  - Passive health checks use fall/rise thresholds

Next steps:
  1. Review migration-report.md
  2. Test haproxy.cfg in staging
  3. Deploy to production
```

### Migration Report Format

**File:** `migration/migration-report.md`

```markdown
# Migration Report: Nginx → HAProxy

**Date:** 2026-04-15
**Source:** /etc/nginx/nginx.conf
**Target:** HAProxy 2.8

## Summary

- **Compatibility:** 95% (19/20 features)
- **Services Migrated:** 3
- **Routes Migrated:** 12
- **Warnings:** 2

## Features Migrated

✅ **Load Balancing**
- Algorithm: Round Robin → roundrobin
- Targets: 6 backends

✅ **Rate Limiting**
- IP-based: 100 req/s
- Converted to stick-table

⚠️ **Authentication**
- Basic Auth: ✅ Supported
- JWT Auth: ⚠️ Requires Lua scripting

## Warnings & Recommendations

1. **JWT Authentication**
   - Nginx uses OpenResty/Lua
   - HAProxy requires Lua scripting or external auth
   - **Recommendation:** Use Kong or Envoy for native JWT

2. **Passive Health Checks**
   - Nginx: max_fails, fail_timeout
   - HAProxy: fall, rise thresholds
   - **Action:** Review and adjust thresholds

## Testing Checklist

- [ ] Test in staging environment
- [ ] Verify all 12 routes
- [ ] Check load balancing distribution
- [ ] Validate rate limiting behavior
- [ ] Monitor backend health
- [ ] Performance comparison

## Next Steps

1. ✅ Review this report
2. ⏳ Test in staging
3. ⏳ Adjust JWT authentication
4. ⏳ Deploy to production
5. ⏳ Monitor and validate
```

**Tests:** 30+ tests für Interactive Workflow, Report Generation

**📖 Detail-Dokumentation:** [docs/import/migration.md](import/migration.md)

---

## 🗓️ Timeline (12 Wochen)

### Phase 1: YAML Parsers (Weeks 1-4) → **v1.3.0-alpha1, alpha2**
- **Week 1:** Feature 1 - Envoy Import + Shared Infrastructure
- **Week 2:** Feature 2 - Kong Import → **Release v1.3.0-alpha1**
- **Week 3:** Feature 3 - APISIX Import
- **Week 4:** Feature 4 - Traefik Import → **Release v1.3.0-alpha2**

### Phase 2: Custom Parsers (Weeks 5-8) → **v1.3.0-beta1, beta2**
- **Weeks 5-6:** Feature 5 - Nginx Import (Custom Parser) → **Release v1.3.0-beta1**
- **Weeks 7-8:** Feature 6 - HAProxy Import (Custom Parser) → **Release v1.3.0-beta2**

### Phase 3: Compatibility & Migration (Weeks 9-12) → **v1.3.0-rc1, Final**
- **Weeks 9-10:** Feature 7 - Compatibility Checker → **Release v1.3.0-rc1**
- **Weeks 11-12:** Feature 8 - Migration Assistant → **Release v1.3.0 Final**

---

## 🎯 Use Cases

### Use Case 1: Nginx → HAProxy Migration

**Scenario:** E-Commerce mit Nginx möchte zu HAProxy wechseln.

```bash
# 1. Import Nginx config
gal import --provider nginx --input /etc/nginx/nginx.conf --output gal-config.yaml

# 2. Check compatibility
gal validate --config gal-config.yaml --target-provider haproxy

# 3. Generate HAProxy config
gal generate --config gal-config.yaml --provider haproxy --output haproxy.cfg
```

### Use Case 2: Kong → Envoy Migration

**Scenario:** Startup mit Kong möchte zu Envoy für Service Mesh.

```bash
# Interactive migration
gal migrate
# > Source: kong
# > Target: envoy
# > Creates migration report
```

### Use Case 3: Multi-Provider Deployment

**Scenario:** Großunternehmen will gleiche Config auf verschiedenen Providern.

```bash
# 1. Import production HAProxy config
gal import --provider haproxy --input haproxy-prod.cfg --output gal-config.yaml

# 2. Generate for all providers
gal generate-all --config gal-config.yaml

# Result: envoy.yaml, kong.yaml, apisix.json, traefik.yaml, nginx.conf, haproxy.cfg
```

---

## 📊 Success Metrics

### Deliverables

**Code:**
- ✅ Provider Interface Extension (parse method)
- ✅ 6 Provider Parser (envoy, kong, apisix, traefik, nginx, haproxy)
- ✅ 2 Custom Parsers (nginx_parser.py, haproxy_parser.py)
- ✅ CLI Commands: `import`, `validate --target-provider`, `compare`, `migrate`
- ✅ Compatibility Checker (compatibility.py)
- ✅ Tests: 350+ tests (50+50+45+40+60+55+40+30)

**Documentation:**
- ✅ docs/guides/IMPORT_MIGRATION.md (500+ lines, German)
- ✅ Migration Guides pro Provider (6 x 100+ lines)
- ✅ Feature Mapping Matrix
- ✅ Troubleshooting Guide

**Examples:**
- ✅ examples/import/ (6 Provider-Configs)
- ✅ examples/migration/ (3 Migration Workflows)

### Coverage Targets

- **Parser Coverage:** 95%+ für Standard-Konfigurationen
- **Feature Mapping:** 90%+ der v1.1.0/v1.2.0 Features
- **Test Coverage:** 350+ Tests für alle Parser

---

## 🚀 Next Steps

1. **Review & Approval:** Diskussion über Feature-Aufteilung
2. **Start Phase 1:** Envoy + Kong Import (Weeks 1-2)
3. **Alpha Release:** v1.3.0-alpha1 mit Envoy + Kong
4. **Community Feedback:** Beta Testing mit Real-World Configs

---

**Target Release:** Q2 2026
**Current Status:** Planning Phase
**Next Milestone:** Start Feature 1 (Envoy Import)
