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.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Related prompts
-
Kubernetes Gateway API HTTPRoute Traffic Splitting Prompt
Design HTTPRoute weighted backendRefs, header-based routing, and canary/blue-green splits, then verify status conditions before shifting production traffic.
-
Kubernetes CSI Driver Development Prompt
Design and build a custom CSI driver — controller vs node plugin split, the gRPC identity/controller/node services, sidecar wiring (provisioner, attacher, resizer, snapshotter), and the idempotency rules that keep volumes from leaking.
-
Kubernetes Gateway API Design & Debug Prompt
Design and debug Gateway API resources — GatewayClass, Gateway, HTTPRoute, ReferenceGrant — and migrate from Ingress to Gateway API.
-
Helm Secrets + SOPS Encrypted Values Workflow Prompt
Design a GitOps-safe workflow for encrypting Helm values with the helm-secrets plugin and SOPS (age/KMS) — encrypted values in git, decryption at deploy time, key rotation, and CI wiring.
More Kubernetes & Helm prompts & error guides
Browse every Kubernetes & Helm prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.