Instructions for remotely debugging pomerium. Especially useful in container deployments.
If you are building a binary to run outside of a container:
make build-debug
The published pomerium/pomerium:debug
image contains an entrypoint and environment appropriate for debugging purposes. It can be run in docker by itself, or in kubernetes. It will not run the debugger by default - set the entrypoint to /debug-entrypoint.sh
.
It can be rebuilt via:
docker build -t pomerium/pomerium:debug -f Dockerfile.debug .
To run the container in debug mode you must:
- Set your entrypoint to
/debug-entrypoint.sh
- Add the
SYS_PTRACE
capability - Attach your debugger to the
dlv
port (9999 by default)
Override DEBUG_PORT
or DEBUG_ADDRESS
env vars to change listening ports and addresses.
Patch your deployment as follows:
patch.yaml
spec:
replicas: 1
template:
spec:
containers:
- name: pomerium
# this can be changed in helm chart or use a custom/local build
image: pomerium/pomerium:debug
securityContext:
capabilities:
add:
- SYS_PTRACE
command:
- /debug-entrypoint.sh
# Disable health checks
livenessProbe: null
readinessProbe: null
Patch the deployment:
kubectl patch deployments.apps pomerium-authorize --patch "$(cat patch.yaml)"
Port forward to the service:
DEPLOYMENT=pomerium-authorize
kubectl port-forward $(kubectl get pods -l app.kubernetes.io/name=${DEPLOYMENT} -o jsonpath="{.items[0].metadata.name}") 9999
Set/override the following parameters in your compose file:
services:
pomerium:
entrypoint: /debug-entrypoint.sh
cap_add:
- SYS_PTRACE
ports:
- "9999:9999"
Use remote debugging support. Set up a launch configuration as follows:
NOTE The remotePath must precisely match the directory the code was built in. See references: 1 2. The directory does not need to actually exist in the running container.
{
"name": "Connect to server",
"type": "go",
"request": "attach",
"mode": "remote",
"remotePath": "/go/src/github.com/pomerium/pomerium/",
"port": 9999,
"host": "127.0.0.1",
}
Running the launch configuration should attach to the running process.