mirror of
https://github.com/pomerium/pomerium.git
synced 2025-04-28 18:06:34 +02:00
118 lines
2.8 KiB
Markdown
118 lines
2.8 KiB
Markdown
Instructions for remotely debugging pomerium. Especially useful in container deployments.
|
|
|
|
- [Building](#building)
|
|
- [Binary](#binary)
|
|
- [Container](#container)
|
|
- [Running](#running)
|
|
- [Kubernetes](#kubernetes)
|
|
- [Docker Compose](#docker-compose)
|
|
- [Debugging](#debugging)
|
|
- [VSCode](#vscode)
|
|
|
|
# Building
|
|
|
|
## Binary
|
|
|
|
If you are building a binary to run outside of a container:
|
|
|
|
```
|
|
make build-debug
|
|
```
|
|
|
|
## Container
|
|
|
|
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 .`
|
|
|
|
# Running
|
|
|
|
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.
|
|
|
|
## Kubernetes
|
|
|
|
Patch your deployment as follows:
|
|
|
|
patch.yaml
|
|
```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:
|
|
|
|
```bash
|
|
kubectl patch deployments.apps pomerium-authorize --patch "$(cat patch.yaml)"
|
|
```
|
|
|
|
Port forward to the service:
|
|
|
|
```bash
|
|
DEPLOYMENT=pomerium-authorize
|
|
kubectl port-forward $(kubectl get pods -l app.kubernetes.io/name=${DEPLOYMENT} -o jsonpath="{.items[0].metadata.name}") 9999
|
|
```
|
|
|
|
## Docker Compose
|
|
|
|
Set/override the following parameters in your compose file:
|
|
|
|
```yaml
|
|
services:
|
|
pomerium:
|
|
entrypoint: /debug-entrypoint.sh
|
|
cap_add:
|
|
- SYS_PTRACE
|
|
ports:
|
|
- "9999:9999"
|
|
|
|
```
|
|
|
|
# Debugging
|
|
|
|
## VSCode
|
|
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
|
|
[1]: https://github.com/microsoft/vscode-go/issues/941
|
|
[2]: https://github.com/microsoft/vscode-go/issues/2010
|