Debuggers are an invaluable part of many development workflows. When you’re running your app(s) in Kubernetes, using debuggers suddenly gets much harder, but Tilt’s port forwarding functionality makes it easy again.
In this guide, we’ll walk you through an example of how to connect a Python debugger to a container in a Tilt env. Debuggers in most languages use these patterns.
This repository contains some examples of how to use various remote debuggers against Tilt. We’ll examine the
remote-pdb case in detail below (see this directory), but the bulk of these steps apply when setting up Tilt with any remote debugger, and only the very end of this guide varies based on your choice of tool.
Debugging your project with Tilt and a remote debugger
To prepare your project for remote debugging, follow these steps:
- Decide what port you’ll expose the debugger on. This example uses
- Add your debugger of choice in requirements.txt.
- Expose your chosen port as a
containerPortin the Kubernetes YAML of the Deployment or Pod that you want to debug (in addition to any ports you’re already exposing for normal development):
kind: Deployment ... spec: spec: containers: - name: example-python image: example-python-image ports: - containerPort: 8000 # the app itself - containerPort: 5555 # debugger
- In the Tiltfile, tell Tilt to forward that port (again, in addition to any ports you’re already forwarding for normal development):
k8s_resource('example-python', port_forwards=[ 8000, # app 5555, # debugger ])
You’re ready to debug!
Congrats, now you can add breakpoints with your chosen debugger, and connect to it at your chosen port however is appropriate. For
remote-pdb, the steps are as follows:
- Insert the breakpoint. In the example repo, there’s already a breakpoint inserted in app.py:
from remote_pdb import RemotePdb RemotePdb('127.0.0.1', 5555).set_trace()
- Trip the breakpoint you set. In the example repo, this means hitting
localhost:8000. (You’ll see the request hang—this is expected! It means that execution of your app paused at the breakpoint.)
- Connect to your debugger. For
remote-pdb, this means opening a TCP connection on 5555. We recommend using Netcat:
nc 127.0.0.1 5555
(The remote-pdb guide has some other connection options, if you prefer.)
- Debug to your heart’s content!
(If you’d prefer to access your debugger in a browser instead of in your terminal/via TCP connection, check out our
Remember to wait for your debugger
Some debuggers start listening on their port as soon as the app starts, and you can connect immediately. With the approach described here, the debugger doesn’t start until the first
set_trace call, so don’t try to connect until then, or you’ll just see a bunch of errors.
remote-pdb, the log line that tells you that your debugger is active is:
CRITICAL:root:RemotePdb session open at 127.0.0.1:5555, waiting for connection … RemotePdb session open at 127.0.0.1:5555, waiting for connection …
(See this interactive snapshot for a closer look.)
Connecting Your Own Debugger
Tilt itself does not have any code for connecting to a particular debugger. None of the examples in this guide use “magic” primitives.
Instead, Tilt provides a standardized API for coordinating any debugger with your dev environment.
Do you use a debugger that’s not listed here?
local_resource to spin it up.
Once you’ve got it running, consider packaging it up as a Tilt extension for others to use.