Debugging Java Microservices Running in Kubernetes Using Telepresence and IntelliJ

If you’re migrating to the cloud and adopting a microservices-based architecture for your Java applications, there’s a good chance you’re deploying to the Kubernetes container orchestrator. This is a great framework for running services in production, but how to you debug a Java service that’s running on a remote cluster? Using the open source tool Telepresence is one option.

The fundamental benefit of Telepresence is that it provides a two-way proxy between your local machine and a Kubernetes remote cluster. You can run a service locally (plus your IDE and all 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 web page or an API endpoint exposed within the remote cluster and proxy the call to an upstream dependent service running on 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.

Getting Started with the Docker Java Shopping App

I’ve provided example code for debugging a remote Kubernetes Service in my Docker Java Shopping sample microservices-based application that is hosted on GitHub. I assume you’ve already provisioned a remote Kubernetes cluster, but you need to provide your user account with the “cluster-admin” RBAC role and then deploy all the services configurations within the kubernetes-ambassador-telepresence directory.

Here are my example kubectl commands (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 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’ll run locally:

$ telepresence --swap-deployment ratelimiter --env-json ratelimit_env.json

Note that I’ve specified the env-json argument with a filename, which generates aratelimit_env.json file that contains all the relevant Kubernetes cluster environment variables you’ll need for local debugging.

Configuring IntelliJ with Telepresence

To load the generated Env File into IntelliJ, download and install the Env File plugin, which you can do either via the JetBrains website or 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. I’ve recorded a video that 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. Then the first breakpoint you’ve set should be triggered! From here you can debug the locally running service as if it were running within the remote Kubernetes cluster. Just be careful and watch out for any side-effects you may cause by modifying data locally!