[TT-10496] extra docs for gRPC high availability

[andrei-tyk]

User description

Added extra docs around gRPC high availability and DNS protocol for gRPC.

Preview Link

Checklist

• Added a preview link
• Reviewed AI PR Agent suggestions
• For Tyk Members - Added Jira DX PR ticket to the subject
• For Tyk Members - Added the appropriate release labels (for fixes add the latest release)

New Contributors

• Make sure you have started your change off our latest master.
• I have reviewed the guidelines for contributing to this repository.
• I have read the technical guidelines for contributing to this repository.

---

PR Type

Documentation

---

Description

• Added detailed documentation on highly available gRPC servers in Kubernetes

• Provided Go example for health checks and graceful shutdown

• Included Kubernetes deployment YAML with probes for gRPC middleware

• Documented DNS-based load balancing for gRPC in Tyk 5.8.2+

---

Changes walkthrough 📝

Relevant files

Documentation

advance-config.md Add gRPC high availability and DNS protocol documentation tyk-docs/content/api-management/plugins/advance-config.md Added a comprehensive section on deploying highly available gRPC servers in Kubernetes Provided Go code example for readiness/liveness probes and graceful shutdown Included example Kubernetes deployment and service YAML with health probes Explained DNS-based load balancing for gRPC servers in Tyk 5.8.2+ +232/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[github-actions]

⚠️ Deploy preview for PR #6462 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Documentation Accuracy Ensure that the provided Go code example for health checks and graceful shutdown is accurate, idiomatic, and aligns with best practices for production gRPC servers in Kubernetes environments. ```go package main import ( "context" "log" "net" "net/http" "os" "os/signal" "sync/atomic" "syscall" "time" "github.com/TykTechnologies/tyk/coprocess" "google.golang.org/grpc" ) const ( ListenAddress = ":50051" HealthAddress = ":8080" ) func main() { // Track server readiness var isReady int32 // Start HTTP server for health checks go func() { mux := http.NewServeMux() // Readiness probe endpoint mux.HandleFunc("/ready", func(w http.ResponseWriter, r *http.Request) { if atomic.LoadInt32(&isReady) == 1 { w.WriteHeader(http.StatusOK) w.Write([]byte("Ready")) } else { w.WriteHeader(http.StatusServiceUnavailable) w.Write([]byte("Not ready")) } }) // Liveness probe endpoint mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) w.Write([]byte("Healthy")) }) if err := http.ListenAndServe(HealthAddress, mux); err != nil { log.Fatalf("Failed to start health server: %v", err) } }() lis, err := net.Listen("tcp", ListenAddress) if err != nil { log.Fatalf("Failed to listen: %v", err) } log.Printf("starting grpc server on %v", ListenAddress) s := grpc.NewServer() coprocess.RegisterDispatcherServer(s, &Dispatcher{}) // Channel to listen for errors coming from the listener. serverErrors := make(chan error, 1) // Start the service listening for requests. go func() { // Mark as ready once server is initialized atomic.StoreInt32(&isReady, 1) log.Printf("gRPC server is ready to accept connections") serverErrors <- s.Serve(lis) }() // Channel to listen for an interrupt or terminate signal from the OS. shutdown := make(chan os.Signal, 1) signal.Notify(shutdown, os.Interrupt, syscall.SIGTERM) // Blocking main and waiting for shutdown. select { case err := <-serverErrors: atomic.StoreInt32(&isReady, 0) log.Fatalf("Server error: %v", err) case sig := <-shutdown: atomic.StoreInt32(&isReady, 0) log.Printf("Received signal: %v", sig) // Give outstanding requests 5 seconds to complete. ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() stopped := make(chan struct{}) go func() { s.GracefulStop() close(stopped) }() select { case <-ctx.Done(): log.Printf("Graceful shutdown timed out") s.Stop() case <-stopped: log.Printf("Graceful shutdown completed") } } } Kubernetes YAML Validity Validate that the Kubernetes deployment and service YAML manifests are correct, follow best practices, and are suitable for real-world use, including proper probe configuration and resource naming. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: tyk-grpc-coprocess labels: app: tyk-grpc-coprocess spec: replicas: 3 strategy: type: RollingUpdate rollingUpdate: maxUnavailable: 1 maxSurge: 1 selector: matchLabels: app: tyk-grpc-coprocess template: metadata: labels: app: tyk-grpc-coprocess spec: containers: - name: grpc-server image: your-registry/tyk-grpc-coprocess:latest ports: - containerPort: 50051 name: grpc - containerPort: 8080 name: http-health # Readiness probe - determines when pod is ready for traffic readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10 timeoutSeconds: 5 failureThreshold: 3 successThreshold: 1 # Liveness probe - determines when to restart pod livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 15 periodSeconds: 20 timeoutSeconds: 5 failureThreshold: 3 # Startup probe - gives more time for initial startup startupProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 10 periodSeconds: 5 timeoutSeconds: 5 failureThreshold: 30 --- apiVersion: v1 kind: Service metadata: name: tyk-grpc-coprocess-service spec: selector: app: tyk-grpc-coprocess ports: - name: grpc port: 50051 targetPort: 50051 protocol: TCP - name: http-health port: 8080 targetPort: 8080 protocol: TCP type: ClusterIP </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/6462/files#diff-517d04be047e137f2e1aebfe8f230d24fb8d2abfc76d0fd5b7dd382a2b008f09R609-R611'><strong>DNS Protocol Usage Clarity</strong></a> Confirm that the documentation for using the dns:/// protocol with gRPC and the associated environment variable is clear, accurate, and does not introduce ambiguity for users configuring Tyk 5.8.2+. </summary> ```markdown Starting with Tyk 5.8.2, you can also put your gRPC servers behind a load balancer and use the dns:/// (yes, triple slash) protocol in the ENV VAR "TYK_GW_COPROCESSOPTIONS_COPROCESSGRPCSERVER" in order to evenly distribute traffic. For more info please visit https://github.com/grpc/grpc/blob/master/doc/naming.md.

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	470cad4
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/6875469097c0a7000874090c
😎 Deploy Preview	https://deploy-preview-6462--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sharadregoti]

Questions:

1. Does our gRPC client enable health checking, as shown in this example?

[andrei-tyk]

Questions:

1. Does our gRPC client enable health checking, as shown in this example?

No, currently we don't support that but I guess we could in the future.

[andyo-tyk]

Suggested change

	When deploying gRPC servers as Tyk Gateway coprocess middlewares in Kubernetes, implementing proper health checks is crucial for achieving high availability and enabling seamless rolling updates. Not having them could lead to situations in which your calls that are going through Tyk erroring out due to the gRPC client being unable to connect and correctly execute the coprocessing middleware.
	When deploying gRPC servers to host [rich plugins]({{< ref "api-management/plugins/rich-plugins#using-grpc" >}}) in Kubernetes, implementing proper health checks is crucial so that you can achieve high availability and enable seamless rolling updates. If Tyk is unable to reach the gRPC server, then it will be unable to correctly execute the plugins, leading to API requests failing.

[andyo-tyk]

Suggested change

	For Tyk Gateway coprocess middlewares, this is especially important since the gateway depends on these gRPC services to process requests.
	For Tyk Gateway rich plugins this is especially important since the Gateway depends on these gRPC services to process requests.

[andyo-tyk]

What do you mean by "modified" example? Is this the example above? Modified from what reference?

[andyo-tyk]

Please can you add something here to explain what you are implementing and where this should be hosted?

[andyo-tyk]

Is this the description for the preceding code? If so, please can you bring it together? I suggest moving the "benefits of gRPC Health Probes" section under "Why health probes matter"

[andyo-tyk]

Is this part of the preceding "Implementation"?

[andyo-tyk]

This section should also sit in the descriptive part, before the example.

[andyo-tyk]

Suggested change

	### How to do load balancing
	### Load balancing between multiple gRPC servers

[lghiur]

@andyo-tyk is this tested?

[andyo-tyk]

This was originally @andrei-tyk's content - I just restructured, so I believe it will be correct.