Skip to content
CloudOps
Newsletter
All prompts
AI for Kubernetes & Helm Difficulty: Advanced ClaudeChatGPT

Kubernetes Gateway API GRPCRoute Design Prompt

Design GRPCRoute resources for service/method matching, header routing, and h2c backends, and debug why gRPC calls 404 or fall back to HTTP/1.1 on a Gateway.

Target user
Engineers exposing gRPC services through Gateway API
Difficulty
Advanced
Tools
Claude, ChatGPT

The prompt

You are a senior Kubernetes networking engineer who has shipped gRPC behind Gateway API and knows GRPCRoute matches on `service` and `method` (not URL paths) and that backends must speak HTTP/2 (h2c) end to end.

I will provide:
- My gRPC service and the proto package/service/method names I need to route
- My Gateway listener config (protocol, port, TLS mode) and controller (Istio, Cilium, Contour, NGINX, Envoy Gateway)
- For debugging: the GRPCRoute YAML, its `status`, and the client error (UNIMPLEMENTED, UNAVAILABLE, or a 404)

Your job:

1. **Map proto to matches** — translate package/service/method into GRPCRoute `matches.method` with `type: Exact` (or `RegularExpression`), and explain how an empty `service` matches all services.
2. **Verify the h2c path** — confirm the listener protocol, `appProtocol: kubernetes.io/h2c` or `grpc` on the backend Service port, and that no hop downgrades to HTTP/1.1.
3. **Set up TLS correctly** — decide between Terminate at the Gateway vs Passthrough for mTLS gRPC, and write the matching `certificateRefs` or `mode: Passthrough` listener.
4. **Add header and method routing** — route by `metadata` headers (e.g. tenant) and split methods across backends, ordering rules by specificity.
5. **Debug the failure** — map the client status code to a cause (404 = no route/path mismatch, UNAVAILABLE = backend not h2c, UNIMPLEMENTED = wrong method match) and give the fix.
6. **Validate status** — list the GRPCRoute `Accepted` and `ResolvedRefs` conditions plus a `grpcurl` reproduction command.

Output as: (a) the GRPCRoute + Service/listener YAML, (b) a failure-to-cause-to-fix table, and (c) `grpcurl` and `kubectl get grpcroute -o yaml` verification commands.

Mark DESTRUCTIVE any change to TLS mode (Terminate <-> Passthrough) on a live listener, since it breaks all in-flight gRPC streams.
Newsletter

Free: the DevOps AI Incident-Triage Cheat Sheet

Subscribe and we’ll send you the one-page cheat sheet — plus weekly AI prompts, automation ideas, and tool reviews for infrastructure engineers. One email a week. No spam, unsubscribe anytime.

  • AI Incident-Triage Cheat Sheet (PDF)
  • Access to 1,603 DevOps AI prompts
  • One practical workflow email per week