Workflow: NGINX to Traefik Migration

Migrate from NGINX Ingress Controller to Traefik with zero-downtime cutovers, full annotation translation, and AI-powered handling of breaking legacy configs.

---

When to Use

• You're running NGINX Ingress Controller and want to move to Traefik.
• Your Ingresses use complex NGINX annotations (CORS, sticky sessions, auth-url).
• You need a phased approach with rollback capability and automated syntax rewrites.

---

Tool & Resource Architecture

Tool: traefik_nginx_migration (action=apply / generate / revert) Resources: nginx-ingress-scan + nginx-ingress-analyze + nginx-runbook (cluster-wide and namespace-scoped variants)
Ingress Flow: Legacy NGINX Controller → Traefik Controller + Generated Middlewares

Tool Pipeline

read_resource nginx-ingress-scan[/{ns}]     → Inventory + paths + nginx annotation values
read_resource nginx-ingress-analyze[/{ns}]  → Full compatibility check (use for agent reasoning)
read_resource nginx-runbook[/{ns}]          → Default runbook with inline YAML (read-only review)

traefik_nginx_migration (action=apply)      → Apply cluster mutations
traefik_nginx_migration (action=generate)   → Preview with agent overrides
traefik_nginx_migration (action=revert)     → Single Ingress rollback

---

Prerequisites & Environment Setup

Component	Status
Kubernetes cluster	Accessible via kubeconfig
NGINX Ingress	Running with existing Ingress resources deployed

Verify NGINX is running:

kubectl get svc -n ingress-nginx | grep ingress-nginx-controller
kubectl get ingressclass nginx
kubectl get ingress --all-namespaces

---

Lifecycle Scenarios

Scenario A: Discovery Scan

Use resources to map the cluster landscape.

Step	Action	Expected
1	Read traefik://migration/nginx-ingress-scan	Digest JSON: controller, summary, ingresses[] with complexity per ref
2	Read traefik://migration/nginx-ingress-scan/{ns}	Same shape, scoped strictly to one namespace
3	Read traefik://migration/nginx-ingress-analyze	Same as analyze resource: ingressReports and summary; breaking → breakingAnnotations
4	Verify complexity	From resource: complexity on each Ingress; snippet-based → unsupported when present

Scenario B: Annotation Analysis

Validate Traefik compatibility mappings.

Step	Action	Expected
1	Analyze for target	Each annotation mapped with status + target resource + note
2	Check metrics	Total, fully compatible, needs workaround, has unsupported — all accurate
3	Verify breaking	overallStatus: breaking flags non-empty breakingAnnotations (unsupported mappings, e.g. snippets)

Scenario C: Full Migration (Read-only Runbook)

Generates the comprehensive migration guide and reviewable YAML without cluster actions.

Step	Action	Expected
1	Read traefik://migration/nginx-runbook/{ns}	Returns a markdown runbook mapping out all phases
2	Verify YAML	Phase 2 Step 1 maps middleware: CORS → Headers; rate-limit → RateLimit; IP Allowlist → IPAllowList
3	Verify Ingress	Phase 2 Step 2: NGINX annotations stripped; router.middlewares Traefik annotation injected

Scenario D: End-to-end Migration (Tool Apply)

Prerequisite: Server must be started with MCP_ALLOW_WRITE=true.

Step	Action	Expected
1	Tool action=apply	Middleware CRDs created; Ingress strategic-merge patched (annotations + spec rules, class, TLS)
2	Verify CRDs	kubectl get middleware -A shows automatically generated middlewares
3	Verify Ingress	kubectl get ingress <name> -o yaml shows Traefik middleware injected
4	Check Status	Response returns apply_result.summary showing successful mutation counts

---

Natural Language Prompts

You can use these exact natural language prompts with the MCP Server to drive migration workflows seamlessly.

Scan & Analyze

"Scan my cluster for all NGINX Ingress resources and tell me what you find — controller type, how many Ingresses, and their complexity level."

"Analyze all my NGINX Ingresses for Traefik compatibility. Which annotations are fully supported, which need workarounds, and which are unsupported?"

"Check if my Ingresses in the 'ecommerce' namespace can be migrated to Traefik without any breaking changes."

Runbook Generation

"Read the Traefik migration runbook for all my NGINX Ingresses. Don't apply anything yet — I want to review the generated YAML first."

"Read the migration runbook for the 'ecommerce' namespace to review the Middleware CRDs, updated Ingresses, install scripts, and verification steps."

Execution

"Migrate all my NGINX Ingresses to Traefik and apply the changes directly to the cluster — create the Middleware CRDs and patch the Ingress annotations."

"We've fully migrated. What manual cleanup steps remain — specifically, when can I safely delete the old Ingress objects?"

---

Agentic Override Workflow (Supervised Autonomy)

This is the end-to-end workflow for an Agent to discover a breaking change, create a custom fix, and execute the migration using a strategic override combining the tool and resources.

1. Discovery & Analysis

   • Prompt: "Analyze the ecommerce namespace for NGINX to Traefik migration and tell me if there are any breaking annotations. Don't migrate yet."
   • Action: Agent reads traefik://migration/nginx-ingress-analyze/ecommerce.

2. Custom Primitive Creation

   • Prompt: "I see auth-signin is unsupported. Please create a custom Traefik ForwardAuth middleware named agent-custom-auth in the ecommerce namespace pointing to http://auth.internal to replace it."
   • Action: Agent executes traefik_manage_middleware(action="create", middleware_type="forward_auth", middleware_name="agent-custom-auth", forward_auth_address="http://auth.internal").

3. Intelligent Payload Execution

   • Prompt: "Now run the full migration for the ecommerce namespace with apply enabled. Make sure to ignore the auth-signin annotation, and explicitly inject the agent-custom-auth middleware we just created into the ecommerce-admin ingress routing."
   • Action: Agent uses traefik_nginx_migration and dynamically injects the migration_plan payload:

     {
       "action": "apply",
       "namespace": "ecommerce",
       "migration_plan": {
         "ecommerce-admin": {
           "ignore_annotations": ["auth-signin"],
           "inject_middlewares": ["agent-custom-auth"]
         }
       }
     }

---

Post-migration Cleanup

The MCP tool does not abruptly delete legacy Ingress controllers to prevent outage gaps.

When safe to remove:

• Traefik is running and serving all traffic
• DNS has been cut over to Traefik's LoadBalancer
• You've verified all routes (e.g. via the 04-verify.sh payload in the runbook)

Steps:

1. Confirm Traefik routes are authoritative (via curl or dashboard).
2. Remove legacy routes from Git or run kubectl delete ingress <name> -n <ns>.
3. Optionally remove the NGINX operator and ingressClass per the 06-cleanup payload in the generated runbook.

---

Next Steps

• Traffic Management — Set up canary routes after migration.
• Shadow Launch — Validate new routes with zero user impact.
• TCP Routing — Route non-HTTP protocols through Traefik.