Workflow: TCP Routing

Route non-HTTP protocols (PostgreSQL, Redis, MQTT, or custom TCP services) through Traefik with optional SNI-based routing, TLS passthrough, and IP allowlisting.

---

When to Use

• You need to route database traffic (PostgreSQL, Redis) through Traefik
• You want IP-based access control for TCP services
• You need TLS passthrough for encrypted TCP connections

Important Notes

1. CRDs: IngressRouteTCP and MiddlewareTCP are required and included in standard Traefik Helm charts.
2. Entry Points: The entry_points passed to tools (e.g., postgresql) must be predefined in Traefik's static configuration or Helm values. Traefik cannot dynamically open new ports via Kubernetes resources.
3. SNI vs Plain TCP: Utilizing sni_match (e.g., HostSNI(`redis.example.com`)) only applies if the client performs TLS with SNI upstream. For plain raw TCP clients, you must use sni_match="*" (the default).

---

Workflow Scenarios (Tools & Resources)

Scenario A: Secure TCP Routing (IP Allowlist)

Tests traefik_configure_tcp_middleware and traefik_manage_tcp_routing for secure TCP routing.

(Note: Executing action=create on an existing route or middleware performs a seamless in-place patch without traffic gaps.)

Step	Action	Tool / Resource
1	Create IP allowlist middleware	Tool: traefik_configure_tcp_middleware (middleware_name=db-allowlist, middleware_type=ip_allowlist, source_ranges='["192.168.1.0/24", "10.0.0.1"]', namespace=default)
2	Create TCP route	Tool: traefik_manage_tcp_routing (action=create, route_name=postgres-route, service_name=postgres, service_port=5432, entry_points=["postgresql"], middlewares=["db-allowlist"], namespace=default)
3	Verify route exists	Resource: traefik://traffic/tcp/list (Lists IngressRouteTCPs; each rule shows targets and attached MiddlewareTCP details.)
4	Patch in place (same names)	Tool: traefik_configure_tcp_middleware (create again with new source_ranges JSON) → updated without delete. Tool: traefik_manage_tcp_routing (create again with new service_name/sni_match/etc) → updated without delete.
5	Delete middleware	Tool: traefik_configure_tcp_middleware (action=delete, namespace=default). Detach from routes first if required.
6	Delete TCP route	Tool: traefik_manage_tcp_routing (action=delete, route_name=postgres-route, namespace=default)

Scenario B: Generator (YAML for GitOps)

Tests traefik_generate_routing_manifest for offline YAML output.

Step	Action	Tool / Resource
1	Generate IngressRouteTCP YAML	Tool: traefik_generate_routing_manifest (manifest_type=ingress_route_tcp, name=postgres-route, service_name=postgres, service_port=5432, namespace=default)
2	Generate MiddlewareTCP YAML	Tool: traefik_generate_routing_manifest (manifest_type=middleware_tcp, name=db-allowlist, source_ranges='["192.168.1.0/24"]', namespace=default)
3	Verify YAML	Review offline, apply with kubectl apply -f, and test connectivity.

Scenario C: TLS Passthrough (e.g. Redis)

Tests TCP route with TLS passthrough enabled for encrypted backends.

Step	Action	Tool / Resource
1	Create TCP route with TLS passthrough	Tool: traefik_manage_tcp_routing (action=create, route_name=redis-route, service_port=6379, entry_points=["redis"], sni_match="redis.example.com", tls_passthrough=True)
2	Cleanup	Tool: traefik_manage_tcp_routing (action=delete, route_name=redis-route)

---

Natural Language Prompts

Use these exact prompts with your AI Agent to execute these workflows seamlessly.

(Note: traefik_manage_tcp_routing only exposes create and delete. Running create a second time with the same name acts as an in-place patch.)

General TCP Routing

"Create a TCP IP allowlist middleware 'db-allowlist' in 'default' allowing 192.168.1.0/24 and 10.0.0.1."

"Create a TCP route 'postgres-route' in 'default' for Kubernetes service 'postgres' on port 5432, entry point 'postgresql', with middleware 'db-allowlist'."

"List all TCP IngressRoutes and middleware attachments by reading the resource traefik://traffic/tcp/list."

"Delete the TCP route 'postgres-route' in 'default'."

Seamless In-Place Updates (Upserts)

"Update the existing TCP route 'postgres-route' in 'default' to use backend service 'hello-world' on port 80, entry point 'postgresql', SNI host 'tcp-example.com', keeping middleware 'postgres-tcp-allowlist'."

"Update middleware 'db-allowlist' in 'default' to allow only ['10.0.0.0/8', '172.16.0.1']."

"Patch TCP route 'postgres-route' in 'default' with backend 'hello-world' port 80, SNI 'tcp-example.com', entry point 'postgresql', middlewares ['postgres-tcp-allowlist']."

TLS Passthrough

"Create IngressRouteTCP 'mcp-tcp-tls-pass' in 'default' for service 'hello-world' on port 80, entry point 'postgresql', SNI 'tls-passthrough-mcp.example.com', with TLS passthrough enabled."

"Create TCP route 'redis-route' in 'default' for 'redis' on port 6379, entry point 'redis', SNI 'redis.example.com', tls_passthrough true."

Generator (Dry Run / YAML)

"Generate an IngressRouteTCP YAML for route name 'postgres-route' targeting Kubernetes service 'postgres' on port 5432 in namespace 'default'. Use entry point 'postgresql' and catch-all HostSNI (*) for plain TCP clients."

"Generate a MiddlewareTCP ipAllowList YAML 'db-allowlist' allowing 192.168.1.0/24 and 10.0.0.1."

---

Next Steps

• Traffic Management — HTTP weighted routing & middleware
• NGINX Migration — Migrate from NGINX to Traefik
• Shadow Launch — Test with zero user impact