From 7f00b13e85d1cb0d0092a29d5b9ca8424573e9e1 Mon Sep 17 00:00:00 2001 From: Tayler Geiger Date: Fri, 14 Feb 2025 13:43:51 -0600 Subject: [PATCH] Add documentation on setting up live debugging (#1653) Adds a short doc on how to set up breakpoints with VSCode through Tilt. Also expands on the existing podman local environment document. Signed-off-by: Tayler Geiger --- dev/local-debugging-with-tilt-and-vscode.md | 48 +++++++++++ dev/podman/setup-local-env-podman.md | 91 ++++++++++++++++----- 2 files changed, 118 insertions(+), 21 deletions(-) create mode 100644 dev/local-debugging-with-tilt-and-vscode.md diff --git a/dev/local-debugging-with-tilt-and-vscode.md b/dev/local-debugging-with-tilt-and-vscode.md new file mode 100644 index 000000000..b74678b5b --- /dev/null +++ b/dev/local-debugging-with-tilt-and-vscode.md @@ -0,0 +1,48 @@ +# Local Debugging in VSCode with Tilt + +This tutorial will show you how to connect the go debugger in VSCode to your running +kind cluster with Tilt for live debugging. + +* Follow the instructions in [this document](podman/setup-local-env-podman.md) to set up your local kind cluster and image registry. +* Next, execute `tilt up` to start the Tilt service (if using podman, you might need to run `DOCKER_BUILDKIT=0 tilt up`). + +Press space to open the web UI where you can monitor the current status of operator-controller and catalogd inside Tilt. + +Create a `launch.json` file in your operator-controller repository if you do not already have one. +Add the following configurations: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug operator-controller via Tilt", + "type": "go", + "request": "attach", + "mode": "remote", + "port": 30000, + "host": "localhost", + "cwd": "${workspaceFolder}", + "trace": "verbose" + }, + { + "name": "Debug catalogd via Tilt", + "type": "go", + "request": "attach", + "mode": "remote", + "port": 20000, + "host": "localhost", + "cwd": "${workspaceFolder}", + "trace": "verbose" + }, + ] +} +``` + +This creates two "Run and debug" entries in the Debug panel of VSCode. + +Now you can start either debug configuration depending on which component you want to debug. +VSCode will connect the debugger to the port exposed by Tilt. + +Breakpoints should now be fully functional. The debugger can even maintain its +connection through live code updates. \ No newline at end of file diff --git a/dev/podman/setup-local-env-podman.md b/dev/podman/setup-local-env-podman.md index 3328caac0..5cbb16837 100644 --- a/dev/podman/setup-local-env-podman.md +++ b/dev/podman/setup-local-env-podman.md @@ -1,32 +1,36 @@ -## The following are Podman specific steps used to set up on a MacBook (Intel or Apple Silicon) +# Configuring Podman for Tilt -### Verify installed tools (install if needed) +The following tutorial explains how to set up a local development environment using Podman and Tilt on a Linux host. +A few notes on achieving the same result for MacOS are included at the end, but you will likely need to do some +tinkering on your own. + +## Verify installed tools (install if needed) + +Ensure you have installed [Podman](https://podman.io/), [Kind](https://github.com/kubernetes-sigs/kind/), and [Tilt](https://tilt.dev/). ```sh $ podman --version podman version 5.0.1 $ kind version -kind v0.23.0 go1.22.3 darwin/arm64 - -(optional) +kind v0.26.0 go1.23.4 linux/amd64 $ tilt version -v0.33.12, built 2024-03-28 +v0.33.15, built 2024-05-31 ``` -### Start Kind with a local registry -Use this [helper script](./kind-with-registry-podman.sh) to create a local single-node Kind cluster with an attached local image registry. +## Start Kind with a local registry -#### Disable secure access on the local kind registry: +Use this [helper script](./kind-with-registry-podman.sh) to create a local single-node Kind cluster with an attached local image registry. -`podman inspect kind-registry --format '{{.NetworkSettings.Ports}}'` -With the port you find for 127.0.0.1 edit the Podman machine's config file: +## Disable secure access on the local kind registry: -`podman machine ssh` +Verify the port used by the image registry: -`sudo vi /etc/containers/registries.conf.d/100-kind.conf` +```sh +podman inspect kind-registry --format '{{.NetworkSettings.Ports}}' +``` -Should look like: +Edit `/etc/containers/registries.conf.d/100-kind.conf` so it contains the following, substituting 5001 if your registry is using a different port: ```ini [[registry]] @@ -34,21 +38,66 @@ location = "localhost:5001" insecure = true ``` -### export DOCKER_HOST +## Configure the Podman socket -`export DOCKER_HOST=unix:///var/run/docker.sock` +Tilt needs to connect to the Podman socket to initiate image builds. The socket address can differ +depending on your host OS and whether you want to use rootful or rootless Podman. If you're not sure, +you should use rootless. +You can start the rootless Podman socket by running `podman --user start podman.socket`. +If you would like to automatically start the socket in your user session, you can run +`systemctl --user enable --now podman.socket`. -### Optional - Start tilt with the tilt file in the parent directory +Find the location of your user socket with `systemctl --user status podman.socket`: -`DOCKER_BUILDKIT=0 tilt up` +```sh +● podman.socket - Podman API Socket + Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: disabled) + Active: active (listening) since Tue 2025-01-28 11:40:50 CST; 7s ago + Invocation: d9604e587f2a4581bc79cbe4efe9c7e7 + Triggers: ● podman.service + Docs: man:podman-system-service(1) + Listen: /run/user/1000/podman/podman.sock (Stream) + CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/podman.socket +``` -### Optional troubleshooting +The location of the socket is shown in the `Listen` section, which in the example above +is `/run/user/1000/podman/podman.sock`. -In some cases it may be needed to do +Set `DOCKER_HOST` to a unix address at the socket location: + +```sh +export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock ``` -sudo podman-mac-helper install + +Some systems might symlink the Podman socket to a docker socket, in which case +you might need to try something like: + +```sh +export DOCKER_HOST=unix:///var/run/docker.sock ``` + +## Start Tilt + +Running Tilt with a container engine other than Docker requires setting `DOCKER_BUILDKIT=0`. +You can export this, or just run: + +```sh +DOCKER_BUILDKIT=0 tilt up ``` + +## MacOS Troubleshooting + +The instructions above are written for use on a Linux system. You should be able to create +the same or a similar configuration on MacOS, but specific steps will differ. + +In some cases you might need to run: + +```sh +sudo podman-mac-helper install + podman machine stop/start ``` + +When disabling secure access to the registry, you will need to first enter the Podman virtual machine: +`podman machine ssh`