Debugging a Java Rate Limiter Service using Telepresence and IntelliJ IDEA
Several readers following along with the Ambassador API Gateway Rate Limiting series have asked how best to debug the Java Rate Limiter service when it is running in a remote Kubernetes cluster, and so I’ve created this post and video in order to provide some guidance.
Debugging Locally Against a Remote Kubernetes Cluster using Telepresence
If you haven’t bumped into the open source Telepresence tool for developing and debugging locally against a remote Kubernetes cluster, then please do take a moment to have a look at the documentation on the website: https://www.telepresence.io/
The fundamental benefit of Telepresence is that it provides a two-way proxy between your local machine and the remote cluster. This means that you can run a service locally (and all of your local debug tooling) and have this service interact with all the other services in the remote cluster. This allows you to make a request against a service running (and exposed) in the remote cluster and proxy a call to a downstream dependent service to your local machine. You can then inspect and modify the request before providing the response from your local machine back into the calling remote service.
A Brief Video Guide
The video below provides more information, and also demonstrates how to debug a locally run Rate Limiter service (that is integrated with a remotely deployed Ambassador API Gateway) via Telepresence and IntelliJ IDEA. All of the example code can be found in my Docker Java Shopping sample microservices-based application on GitHub.
Video Instruction TL;DR
Once you have provisioned a remote Kubernetes cluster you will need to provide your user account with the “cluster-admin” RBAC role and then deploy all of the services configurations within the kubernetes-ambassador-telepresence directory. I’ve included my example kubectl commands below (which are executed against a remote Kubernetes cluster running via Google’s GKE):
$ # Assume Kubernetes cluster has been successfully provisioned
$ #
$ kubectl create clusterrolebinding my-cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud info --format="value(config.account)")
$ #
$ git clone git@github.com:danielbryantuk/oreilly-docker-java-shopping.git
$ cd oreilly-docker-java-shopping/kubernetes-ambassador-telepresence
$ kubectl apply -f .When all of the services have been deployed successfully, you can use Telepresence to “swap” the remotely running ratelimiter deployment with a proxy that will forward all network communications to/from the service that you will run locally:
$ telepresence --swap-deployment ratelimiter --env-json ratelimit_env.jsonYou’ll notice that I have specified the env-json argument with a filename, which generates aratelimit_env.json file that contains all the relevant Kubernetes cluster environment variables you will need for local debugging.
Configuring IntelliJ with Telepresence
In order to load the generated Env File into IntelliJ, you will need to install the Env File plugin. This can be downloaded and installed via the JetBrains website, or you can also install it via the “Preferences -> Plugins” configuration of the IDE itself.
With the plugin installed, you can now clone the Ambassador Java Rate Limiter Java code from GitHub and open this in IntelliJ. The video shows exactly how to configure IntelliJ IDEA, but the primary task is to modify the Run/Debug Configuration to load the Env File that was generated during the Telepresence swap-deployment command:
With the configuration updated, you can now start the local instance of the RateLimiter service in debug mode, and make a request against the remote Kubernetes cluster Shopfront endpoint. Once the request is made then the first breakpoint you have set should be triggered! From here you can debug the locally running service as if it was running within the remote Kubernetes cluster.
You can find more information in the Telepresence documentation, and please do reach out to me via twitter (@ danielbryantuk) or the Ambassador Gitter.
Looking for More Info on Rate Limiting with Ambassador and Kubernetes?
You can continue reading the other articles in this four part series:
Part 1: Rate Limiting: A Useful Tool with Distributed Systems
Part 2: Rate Limiting for API Gateways
Part 3: Implementing a Java Rate Limiting Service for the Ambassador API Gateway
Part 4: Designing a Rate Limiting Service for Ambassador
If you have any questions, please do reach out via the Ambassador Gitter or Datawire OSS Slack.
