feat: add Delve remote debugging support

CONTRIBUTING.md

@@ -16,6 +16,33 @@ If your repo has certain guidelines for contribution, put them here ahead of the
 - [Kubernetes Contributor Guide](https://k8s.dev/guide) - Main contributor documentation, or you can just jump directly to the [contributing page](https://k8s.dev/docs/guide/contributing/)
 - [Contributor Cheat Sheet](https://k8s.dev/cheatsheet) - Common resources for existing developers
 
+## Debugging the Controller in a Cluster
+
+You can debug the controller running inside a Kubernetes cluster using [Delve](https://github.com/go-delve/delve).
+
+### Build and Deploy
+
+```bash
+make docker-build-debug IMG=<your-registry/your-image:tag>
+make docker-push IMG=<your-registry/your-image:tag>
+make deploy-debug IMG=<your-registry/your-image:tag>
+```
+
+### Connect Your Debugger
+
+Forward the Delve port to your local machine:
+
+```bash
+kubectl port-forward -n mcp-lifecycle-operator-system deploy/mcp-lifecycle-operator-controller-manager 40000:40000
+```
+
+Then connect your IDE's remote debugger to `localhost:40000`.
+
+**Path mapping:** Configure your IDE to map your local source root to `/workspace` inside the container.
+
+- **GoLand:** Run > Edit Configurations > Go Remote > Path mappings: local project root → `/workspace`
+- **VS Code:** In `launch.json`, set `"substitutePath"` with `"from"` as your local project root and `"to"` as `"/workspace"`
+
 ## Mentorship
 
 - [Mentoring Initiatives](https://k8s.dev/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers!

Dockerfile

@@ -24,11 +24,34 @@ COPY . .
 # by leaving it empty we can ensure that the container and binary shipped on it will have the same platform.
 RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o manager ./cmd
 
+# Build the manager binary with debug symbols
+FROM golang:1.26.3 AS debug-builder
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /workspace
+COPY go.mod go.mod
+COPY go.sum go.sum
+RUN go mod download
+
+COPY . .
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -gcflags="all=-N -l" -o manager ./cmd
+
 # Use distroless as minimal base image to package the manager binary
 # Refer to https://github.com/GoogleContainerTools/distroless for more details
-FROM gcr.io/distroless/static:nonroot
+FROM gcr.io/distroless/static:nonroot AS production
 WORKDIR /
 COPY --from=builder /workspace/manager .
 USER 65532:65532
 
 ENTRYPOINT ["/manager"]
+
+# Debug image with Delve
+FROM golang:1.26.3 AS debug
+RUN go install github.com/go-delve/delve/cmd/dlv@latest
+WORKDIR /
+COPY --from=debug-builder /workspace/manager .
+USER 65532:65532
+
+ENTRYPOINT ["dlv", "exec", "/manager", "--headless", "--listen=:40000", "--api-version=2", "--accept-multiclient", "--"]

Makefile

@@ -167,7 +167,11 @@ run: manifests generate fmt vet ## Run a controller from your host.
 # More info: https://docs.docker.com/develop/develop-images/build_enhancements/
 .PHONY: docker-build
 docker-build: ## Build docker image with the manager.
-	$(CONTAINER_TOOL) build -t ${IMG} .
+	$(CONTAINER_TOOL) build --target production -t ${IMG} .
+
+.PHONY: docker-build-debug
+docker-build-debug: ## Build docker image with Delve for remote debugging.
+	$(CONTAINER_TOOL) build --target debug -t ${IMG} .
 
 .PHONY: docker-push
 docker-push: ## Push docker image with the manager.
@@ -238,6 +242,11 @@ deploy: manifests kustomize ## Deploy controller to the K8s cluster specified in
 	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
 	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" apply -f -
 
+.PHONY: deploy-debug
+deploy-debug: manifests kustomize ## Deploy controller with Delve for remote debugging.
+	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
+	"$(KUSTOMIZE)" build config/manager-debug | "$(KUBECTL)" apply -f -
+
 .PHONY: undeploy
 undeploy: kustomize ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
 	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" delete --ignore-not-found=$(ignore-not-found) -f -

config/manager-debug/disable_leader_election.yaml

@@ -0,0 +1,13 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+spec:
+  template:
+    spec:
+      containers:
+      - name: manager
+        args:
+        - --metrics-bind-address=:8443
+        - --health-probe-bind-address=:8081

config/manager-debug/increase_resources.yaml

@@ -0,0 +1,15 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+spec:
+  template:
+    spec:
+      containers:
+      - name: manager
+        resources:
+          limits:
+            memory: 1Gi
+          requests:
+            memory: 512Mi

config/manager-debug/kustomization.yaml

@@ -0,0 +1,11 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+- ../default
+
+patches:
+- path: remove_probes.yaml
+- path: disable_leader_election.yaml
+- path: override_entrypoint.yaml
+- path: increase_resources.yaml

config/manager-debug/override_entrypoint.yaml

@@ -0,0 +1,11 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+spec:
+  template:
+    spec:
+      containers:
+      - name: manager
+        command: null

config/manager-debug/remove_probes.yaml

@@ -0,0 +1,12 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+spec:
+  template:
+    spec:
+      containers:
+      - name: manager
+        livenessProbe: null
+        readinessProbe: null