Skip to content

Latest commit

 

History

History
118 lines (85 loc) · 2.76 KB

DEBUG.MD

File metadata and controls

118 lines (85 loc) · 2.76 KB
Raw

Instructions for remotely debugging pomerium. Especially useful in container deployments.

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

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

Docker Compose

Set/override the following parameters in your compose file:

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.

    {
      "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.