This is an automated email from the ASF dual-hosted git repository.
wilfred-s pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/yunikorn-site.git
The following commit(s) were added to refs/heads/master by this push:
new 52f75300f8 [YUNIKORN-3266] Add remote container debugging guide to
developer docs (#569)
52f75300f8 is described below
commit 52f75300f8e9aa92e4ca976a43c5bc8553095cc9
Author: kaijaytu <[email protected]>
AuthorDate: Tue Aug 25 14:14:10 2026 +1000
[YUNIKORN-3266] Add remote container debugging guide to developer docs
(#569)
Add a new "Debug scheduler in a remote cluster" section to the
developer guide (env_setup.md). The section covers building a
debug-enabled scheduler image with Delve, pushing to a container
registry, deploying to a remote cluster, and attaching a debugger
from GoLand or VS Code via port-forwarding.
Generated by GitHub Copilot (Claude Opus 4.7)
Closes: #569
Signed-off-by: Wilfred Spiegelenburg <[email protected]>
---
docs/developer_guide/env_setup.md | 112 ++++++++++++++++++++++++++++++++++++++
1 file changed, 112 insertions(+)
diff --git a/docs/developer_guide/env_setup.md
b/docs/developer_guide/env_setup.md
index 63390d18fe..7debe554c8 100644
--- a/docs/developer_guide/env_setup.md
+++ b/docs/developer_guide/env_setup.md
@@ -255,3 +255,115 @@ Or follow these simplified steps:
More documentation can be found
[here](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
+
+## Debug scheduler in a remote cluster
+
+This section explains how to deploy a debug-enabled scheduler image to a
remote cluster and attach a debugger from your local machine using
[Delve](https://github.com/go-delve/delve).
+
+### Prerequisites
+
+- A remote Kubernetes cluster accessible via `kubectl` (see
[above](#access-remote-kubernetes-cluster))
+- A container registry you can push to (Docker Hub, private registry, etc.)
+- [Delve](https://github.com/go-delve/delve) installed locally:
+ ```shell script
+ go install github.com/go-delve/delve/cmd/dlv@latest
+ ```
+
+### Build a debug image
+
+Compile the scheduler with optimizations and inlining disabled so that the
debugger can map breakpoints correctly:
+
+```shell script
+cd yunikorn-k8shim
+CGO_ENABLED=0 go build -gcflags="all=-N -l" -o _output/shim ./pkg/cmd/shim
+```
+
+Build flags:
+
+- `CGO_ENABLED=0`: produce a statically linked binary so it can run inside the
minimal debug image without extra libc dependencies.
+- `-gcflags="all=-N -l"`: applied to all packages; `-N` disables optimizations
and `-l` disables inlining, so Delve can map source lines to instructions and
breakpoints hit reliably.
+- `-o _output/shim`: output path that matches the `COPY _output/shim
/scheduler` line in the Dockerfile below.
+
+Create a Dockerfile for the debug image. This installs Delve and uses it as
the entrypoint:
+
+```dockerfile
+FROM golang:1.26 AS dlv-builder
+RUN go install github.com/go-delve/delve/cmd/dlv@latest
+
+FROM ubuntu:22.04
+COPY --from=dlv-builder /go/bin/dlv /usr/local/bin/dlv
+COPY _output/shim /scheduler
+EXPOSE 2345
+ENTRYPOINT ["dlv", "exec", "/scheduler", "--headless", "--listen=:2345",
"--api-version=2", "--accept-multiclient"]
+```
+
+Build and tag the image:
+
+```shell script
+docker build -t <your-registry>/yunikorn:scheduler-debug -f Dockerfile.debug .
+```
+
+### Push image to registry
+
+If the local image is not already tagged for your target registry, retag it
first, then push:
+
+```shell script
+docker tag yunikorn:scheduler-debug <your-registry>/yunikorn:scheduler-debug
+docker push <your-registry>/yunikorn:scheduler-debug
+```
+
+### Deploy to remote cluster
+
+Update the scheduler Deployment (or Helm values) to use the debug image and
expose port 2345:
+
+```yaml
+spec:
+ containers:
+ - name: yunikorn-scheduler
+ image: <your-registry>/yunikorn:scheduler-debug
+ ports:
+ - containerPort: 2345
+ name: dlv
+ protocol: TCP
+```
+
+Deploy using Helm or `kubectl apply`. Ensure the Pod has sufficient
permissions (the same ServiceAccount used for normal scheduler deployment).
+
+### Attach debugger from local machine
+
+Port-forward the debug port:
+
+```shell script
+kubectl port-forward <scheduler-pod> 2345:2345
+```
+
+#### GoLand
+
+1. Run → Edit Configurations → "+" → **Go Remote**
+2. Set **Host**: `localhost`, **Port**: `2345`
+3. Click **Debug** and set breakpoints in the `yunikorn-k8shim` or
`yunikorn-core` source
+
+#### VS Code
+
+Add to `.vscode/launch.json`:
+
+```json
+{
+ "name": "Attach to Remote Scheduler",
+ "type": "go",
+ "request": "attach",
+ "mode": "remote",
+ "host": "localhost",
+ "port": 2345
+}
+```
+
+Then press F5 to attach.
+
+### Cleanup
+
+:::caution
+Debug images disable compiler optimizations and include debug symbols,
resulting in significantly larger binaries. Do not deploy debug images to
production.
+:::
+
+When done, remove the port-forward and redeploy with a normal scheduler image.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
