Add documentation on setting up live debugging

Adds a short doc on how to set up breakpoints with VSCode through Tilt. Also expands on the existing podman local environment document with instructions that apply to both Linux and MacOS installations. Signed-off-by: Tayler Geiger <[email protected]>
operator-framework · Jan 28, 2025 · 6557fc5 · 6557fc5
1 parent a46ff7d
commit 6557fc5
Show file tree

Hide file tree

Showing 2 changed files with 108 additions and 18 deletions.
diff --git a/dev/local-debugging-with-tilt-and-vscode.md 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.
diff --git a/dev/podman/setup-local-env-podman.md b/dev/podman/setup-local-env-podman.md
@@ -1,54 +1,96 @@
-## 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)
+## 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)
 $ tilt version
 v0.33.12, built 2024-03-28
 ```
 
-### Start Kind with a local registry
+## 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.
 
-#### Disable secure access on the local kind registry:
 
-`podman inspect kind-registry --format '{{.NetworkSettings.Ports}}'`
+## Disable secure access on the local kind registry:
 
-With the port you find for 127.0.0.1 edit the Podman machine's config file:
+Verify the port used by the image registry:
 
-`podman machine ssh`
+```sh
+podman inspect kind-registry --format '{{.NetworkSettings.Ports}}'
+```
 
-`sudo vi /etc/containers/registries.conf.d/100-kind.conf`
+If your host is a Mac, first run:
+`podman machine ssh`
 
-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]]
 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/[email protected]/app.slice/podman.socket
+```
+
+The location of the socket is shown in the `Listen` section, which in the example above
+is `/run/user/1000/podman/podman.sock`.
 
-### Optional troubleshooting
+Set `DOCKER_HOST` to a unix address at the socket location:
 
-In some cases it may be needed to do
+```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
+
+In some cases you might need to run: 
+
+```sh
+sudo podman-mac-helper install
+
 podman machine stop/start
 ```