Usage Guide

Web Interface

The web interface provides an interactive way to convert Ingress resources with a modern UI.

Getting Started

Start the server
```
i2g serve --port 8000
```
Open the browser at http://localhost:8000
Paste your Ingress YAML in the left editor panel
Select your provider from the dropdown (Istio, Envoy, Contour, etc.)
Click “Convert” to generate Gateway API resources
Download or copy the output using the toolbar buttons

Web UI Features

Dark/Light Theme: Toggle between themes using the button in the header
Provider Selection: Choose your Gateway API implementation
Conversion Mode: Switch between Ingress→Gateway and Gateway→Ingress
gRPC Detection: Enable automatic detection of gRPC backends
Validation: Toggle input/output validation
Diff Summary: View field mappings between Ingress and Gateway API
Warnings Tab: See conversion warnings and unsupported features
Download Options:
- Single YAML file
- Separate files (ZIP)
- Kustomize structure (ZIP)
- Migration report (Markdown)

Example Workflow

Load an example or paste your Ingress YAML
Select “Istio” as the provider
Enable “Detect gRPC” if you have gRPC services
Click “Convert”
Review the Diff Summary tab to understand the mapping
Check the Warnings tab for any manual steps needed
Download as Kustomize for production use

CLI Usage

Basic Conversion

# Convert single file
i2g convert ingress.yaml -o gateway.yaml

# Convert with provider preset
i2g convert ingress.yaml -o gateway.yaml -p envoy

# Convert with gRPC detection
i2g convert ingress.yaml -o gateway.yaml --grpc

Multi-Document YAML

The tool supports YAML files with multiple Ingress resources:

# multi-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app1-ingress
spec:
  rules:
    - host: app1.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app1
                port:
                  number: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app2-ingress
spec:
  rules:
    - host: app2.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app2
                port:
                  number: 80

i2g convert multi-ingress.yaml -o gateway.yaml

Migration Reports

Generate detailed migration reports:

i2g convert ingress.yaml -o gateway.yaml --report migration.md

The report includes:

Summary of converted resources
Field mapping details
Warnings and unsupported features
Manual steps required
Useful kubectl commands

Reverse Conversion

Convert Gateway API resources back to Ingress:

i2g reverse gateway.yaml -o ingress.yaml

This is useful for:

Migration rollback
Understanding the reverse mapping
Testing bidirectional conversion

Validation

Validate Ingress files before conversion:

i2g validate ingress.yaml

Output shows errors and warnings:

✓ Ingress is valid

Warnings:
  • spec.rules[0].http: Consider adding explicit pathType

REST API

Convert Endpoint

POST /api/convert

curl -X POST http://localhost:8000/api/convert \
  -H "Content-Type: application/json" \
  -d '{
    "ingress_yaml": "apiVersion: networking.k8s.io/v1\nkind: Ingress...",
    "provider": "istio",
    "detect_grpc": false
  }'

Response:

{
  "gateway_yaml": "apiVersion: gateway.networking.k8s.io/v1\nkind: Gateway...",
  "gateway": { ... },
  "httproutes": [ ... ],
  "grpcroutes": [ ... ],
  "warnings": [ ... ],
  "diff_summary": { ... }
}

Reverse Endpoint

POST /api/reverse

curl -X POST http://localhost:8000/api/reverse \
  -H "Content-Type: application/json" \
  -d '{"gateway_yaml": "..."}'

Validate Endpoint

POST /api/validate

curl -X POST http://localhost:8000/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "yaml_content": "...",
    "resource_type": "ingress"
  }'

Response:

{
  "valid": true,
  "errors": [],
  "warnings": ["spec.rules[0].http: No paths defined"]
}

Download Endpoints

POST /api/download/single - Single YAML file

POST /api/download/separate - Separate files in ZIP

POST /api/download/kustomize - Kustomize structure in ZIP

Report Endpoint

POST /api/report

curl -X POST http://localhost:8000/api/report \
  -H "Content-Type: application/json" \
  -d '{"ingress_yaml": "..."}' \
  -o migration-report.md

Providers Endpoint

GET /api/providers

curl http://localhost:8000/api/providers

Response:

[
  {
    "id": "istio",
    "name": "Istio",
    "gateway_class": "istio",
    "supports_grpc": true,
    "supports_tcp": true
  },
  ...
]

Health Check

GET /health

curl http://localhost:8000/health
# {"status": "healthy"}

OpenAPI Documentation

Interactive API documentation is available at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Python API

Basic Usage

from ingress2gateway import (
    convert_ingress_to_gateway,
    parse_ingress,
    resources_to_yaml,
)

# Load Ingress YAML
with open("ingress.yaml") as f:
    yaml_content = f.read()

# Parse and convert
ingress = parse_ingress(yaml_content)
resources = convert_ingress_to_gateway(ingress)

# Output as YAML
output = resources_to_yaml(resources)
print(output)

With Provider Defaults

from ingress2gateway import (
    convert_ingress_to_gateway,
    parse_ingress,
    apply_provider_defaults,
)

ingress = parse_ingress(yaml_content)
resources = convert_ingress_to_gateway(ingress)

# Apply Istio defaults
resources["gateway"] = apply_provider_defaults(resources["gateway"], "istio")

With Validation

from ingress2gateway import (
    parse_ingress,
    validate_ingress,
    validate_gateway,
)

ingress = parse_ingress(yaml_content)

# Validate input
result = validate_ingress(ingress)
if not result.is_valid:
    for error in result.errors:
        print(f"Error at {error.path}: {error.message}")

With Annotations

from ingress2gateway import parse_annotations, get_annotation_warnings

annotations = ingress.get("metadata", {}).get("annotations", {})
parsed = parse_annotations(annotations)

# Get filters to apply to HTTPRoute
filters = parsed.get("filters", [])

# Get warnings about unsupported annotations
warnings = get_annotation_warnings(parsed)

Generate Migration Report

from ingress2gateway import generate_migration_report

report = generate_migration_report(
    ingress=ingress,
    gateway=resources["gateway"],
    httproutes=resources["httproutes"],
    warnings=warnings,
)

with open("migration.md", "w") as f:
    f.write(report)