Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
deplyoment: add debug build / container / docs (#1513)
- Loading branch information
1 parent
f4d5594
commit 0b14722
Showing
6 changed files
with
190 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,118 @@ | ||
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
FROM golang:latest as build | ||
WORKDIR /go/src/github.com/pomerium/pomerium | ||
|
||
RUN apt-get update \ | ||
&& apt-get -y install zip | ||
|
||
# cache depedency downloads | ||
COPY go.mod go.sum ./ | ||
RUN go mod download | ||
COPY . . | ||
|
||
# build | ||
RUN make build-deps | ||
RUN make build-debug NAME=pomerium | ||
RUN make build-debug NAME=pomerium-cli | ||
RUN touch /config.yaml | ||
RUN go get github.com/go-delve/delve/cmd/dlv | ||
|
||
FROM alpine:latest | ||
ENV AUTOCERT_DIR /data/autocert | ||
WORKDIR /pomerium | ||
RUN apk add --no-cache ca-certificates | ||
COPY --from=build /go/src/github.com/pomerium/pomerium/bin/* /bin/ | ||
COPY --from=build /config.yaml /pomerium/config.yaml | ||
COPY --from=build /go/bin/dlv /bin | ||
COPY scripts/debug-entrypoint.sh / | ||
ENTRYPOINT [ "/bin/pomerium" ] | ||
CMD ["-config","/pomerium/config.yaml"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
#!/bin/sh | ||
|
||
DEBUG_PORT="${DEBUG_PORT:-9999}" | ||
DEBUG_ADDRESS="${DEBUG_ADDRESS:-127.0.0.1}" | ||
/bin/dlv exec /bin/pomerium --api-version=2 --headless --listen="${DEBUG_ADDRESS}:${DEBUG_PORT}" --log --accept-multiclient -- "$@" |