Add node debug tool with tests

Author: harche

README.md

@@ -19,6 +19,7 @@ A powerful and flexible Kubernetes [Model Context Protocol (MCP)](https://blog.m
     - **Top** gets resource usage metrics for all pods or a specific pod in the specified namespace.
     - **Exec** into a pod and run a command.
     - **Run** a container image in a pod and optionally expose it.
+    - **Node debug** run privileged commands directly on cluster nodes via a managed debug pod.
 - **✅ Namespaces**: List Kubernetes Namespaces.
 - **✅ Events**: View Kubernetes events in all namespaces or in a specific namespace.
 - **✅ Projects**: List OpenShift Projects.
@@ -220,6 +221,24 @@ List all the Kubernetes namespaces in the current cluster
 
 **Parameters:** None
 
+### `nodes_debug_exec`
+
+Run commands on an OpenShift node by creating a short-lived privileged debug pod that automatically chroots into the host filesystem. Output is limited to the latest 100 log lines, so use filtering (e.g., `grep`, `journalctl --since`, etc.) for high-volume commands.
+
+**Parameters:**
+- `node` (`string`, required)
+    - Name of the node to target (for example `worker-0`)
+- `command` (`string[]`, required)
+    - Command and arguments to run inside the node's host filesystem
+    - Example: `["systemctl", "status", "kubelet"]`
+- `namespace` (`string`, optional)
+    - Namespace used for the temporary debug pod
+    - Defaults to the configured namespace or `default`
+- `image` (`string`, optional)
+    - Override the container image used for the debug pod
+- `timeout_seconds` (`integer`, optional)
+    - Maximum time to wait for the command to finish (defaults to 300 seconds)
+
 ### `pods_delete`
 
 Delete a Kubernetes Pod in the current or provided namespace with the provided name

pkg/kubernetes/kubernetes.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"k8s.io/apimachinery/pkg/runtime"
+	corev1client "k8s.io/client-go/kubernetes/typed/core/v1"
 
 	"github.com/fsnotify/fsnotify"
 
@@ -38,7 +39,8 @@ const (
 type CloseWatchKubeConfig func() error
 
 type Kubernetes struct {
-	manager *Manager
+	manager          *Manager
+	podClientFactory func(namespace string) (corev1client.PodInterface, error)
 }
 
 type Manager struct {
@@ -209,6 +211,16 @@ func (m *Manager) Derived(ctx context.Context) (*Kubernetes, error) {
 	return derived, nil
 }
 
+func (k *Kubernetes) podsClient(namespace string) (corev1client.PodInterface, error) {
+	if k.podClientFactory != nil {
+		return k.podClientFactory(namespace)
+	}
+	if k.manager == nil || k.manager.accessControlClientSet == nil {
+		return nil, errors.New("kubernetes manager is not initialized")
+	}
+	return k.manager.accessControlClientSet.Pods(namespace)
+}
+
 func (k *Kubernetes) NewHelm() *helm.Helm {
 	// This is a derived Kubernetes, so it already has the Helm initialized
 	return helm.NewHelm(k.manager)

pkg/kubernetes/nodes.go

@@ -0,0 +1,240 @@
+package kubernetes
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/containers/kubernetes-mcp-server/pkg/version"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/utils/ptr"
+)
+
+const (
+	// defaultNodeDebugImage is a lightweight image that provides the tooling required to run chroot.
+	defaultNodeDebugImage = "quay.io/fedora/fedora:latest"
+	// nodeDebugContainerName is the name used for the debug container, matching oc debug defaults.
+	nodeDebugContainerName = "debug"
+	// defaultNodeDebugTimeout is the maximum time to wait for the debug pod to finish executing.
+	defaultNodeDebugTimeout = 5 * time.Minute
+)
+
+// NodesDebugExec mimics `oc debug node/<name> -- <command...>` by creating a privileged pod on the target
+// node, running the provided command within a chroot of the host filesystem, collecting its output, and
+// removing the pod afterwards.
+//
+// When namespace is empty, the configured namespace (or "default" if none) is used. When image is empty the
+// default debug image is used. Timeout controls how long we wait for the pod to complete.
+func (k *Kubernetes) NodesDebugExec(
+	ctx context.Context,
+	namespace string,
+	nodeName string,
+	image string,
+	command []string,
+	timeout time.Duration,
+) (string, error) {
+	if nodeName == "" {
+		return "", errors.New("node name is required")
+	}
+	if len(command) == 0 {
+		return "", errors.New("command is required")
+	}
+
+	ns := k.NamespaceOrDefault(namespace)
+	if ns == "" {
+		ns = "default"
+	}
+	debugImage := image
+	if debugImage == "" {
+		debugImage = defaultNodeDebugImage
+	}
+	if timeout <= 0 {
+		timeout = defaultNodeDebugTimeout
+	}
+
+	podsClient, err := k.podsClient(ns)
+	if err != nil {
+		return "", fmt.Errorf("failed to get pod client for namespace %s: %w", ns, err)
+	}
+
+	sanitizedNode := sanitizeForName(nodeName)
+	hostPathType := corev1.HostPathDirectory
+
+	debugPod := &corev1.Pod{
+		ObjectMeta: metav1.ObjectMeta{
+			GenerateName: fmt.Sprintf("node-debug-%s-", sanitizedNode),
+			Namespace:    ns,
+			Labels: map[string]string{
+				AppKubernetesManagedBy: version.BinaryName,
+				AppKubernetesComponent: "node-debug",
+				AppKubernetesName:      fmt.Sprintf("node-debug-%s", sanitizedNode),
+			},
+		},
+		Spec: corev1.PodSpec{
+			AutomountServiceAccountToken: ptr.To(false),
+			NodeName:                     nodeName,
+			RestartPolicy:                corev1.RestartPolicyNever,
+			SecurityContext: &corev1.PodSecurityContext{
+				RunAsUser: ptr.To[int64](0),
+			},
+			Tolerations: []corev1.Toleration{
+				{Operator: corev1.TolerationOpExists},
+				{Operator: corev1.TolerationOpExists, Effect: corev1.TaintEffectNoSchedule},
+				{Operator: corev1.TolerationOpExists, Effect: corev1.TaintEffectNoExecute},
+			},
+			Volumes: []corev1.Volume{
+				{
+					Name: "host-root",
+					VolumeSource: corev1.VolumeSource{
+						HostPath: &corev1.HostPathVolumeSource{
+							Path: "/",
+							Type: &hostPathType,
+						},
+					},
+				},
+			},
+			Containers: []corev1.Container{
+				{
+					Name:            nodeDebugContainerName,
+					Image:           debugImage,
+					ImagePullPolicy: corev1.PullIfNotPresent,
+					Command:         append([]string{"chroot", "/host"}, command...),
+					SecurityContext: &corev1.SecurityContext{
+						Privileged: ptr.To(true),
+						RunAsUser:  ptr.To[int64](0),
+					},
+					VolumeMounts: []corev1.VolumeMount{
+						{Name: "host-root", MountPath: "/host"},
+					},
+				},
+			},
+		},
+	}
+
+	created, err := podsClient.Create(ctx, debugPod, metav1.CreateOptions{})
+	if err != nil {
+		return "", fmt.Errorf("failed to create debug pod: %w", err)
+	}
+
+	// Ensure the pod is deleted regardless of completion state.
+	defer func() {
+		deleteCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		grace := int64(0)
+		_ = podsClient.Delete(deleteCtx, created.Name, metav1.DeleteOptions{GracePeriodSeconds: &grace})
+	}()
+
+	pollCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	var (
+		lastPod    *corev1.Pod
+		terminated *corev1.ContainerStateTerminated
+		waitMsg    string
+	)
+
+	for {
+		select {
+		case <-pollCtx.Done():
+			return "", fmt.Errorf("timed out waiting for debug pod %s to complete: %w", created.Name, pollCtx.Err())
+		default:
+		}
+
+		current, getErr := podsClient.Get(pollCtx, created.Name, metav1.GetOptions{})
+		if getErr != nil {
+			return "", fmt.Errorf("failed to get debug pod status: %w", getErr)
+		}
+		lastPod = current
+
+		if status := containerStatusByName(current.Status.ContainerStatuses, nodeDebugContainerName); status != nil {
+			if status.State.Waiting != nil {
+				waitMsg = fmt.Sprintf("container waiting: %s", status.State.Waiting.Reason)
+				// Image pull issues should fail fast.
+				if status.State.Waiting.Reason == "ErrImagePull" || status.State.Waiting.Reason == "ImagePullBackOff" {
+					return "", fmt.Errorf("debug container failed to start (%s): %s", status.State.Waiting.Reason, status.State.Waiting.Message)
+				}
+			}
+			if status.State.Terminated != nil {
+				terminated = status.State.Terminated
+				break
+			}
+		}
+
+		if current.Status.Phase == corev1.PodFailed {
+			break
+		}
+
+		select {
+		case <-pollCtx.Done():
+			return "", fmt.Errorf("timed out waiting for debug pod %s to complete: %w", created.Name, pollCtx.Err())
+		case <-ticker.C:
+		}
+	}
+
+	logCtx, logCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer logCancel()
+	logs, logErr := k.PodsLog(logCtx, ns, created.Name, nodeDebugContainerName, false, 0)
+	if logErr != nil {
+		return "", fmt.Errorf("failed to retrieve debug pod logs: %w", logErr)
+	}
+	logs = strings.TrimSpace(logs)
+
+	if terminated != nil {
+		if terminated.ExitCode != 0 {
+			errMsg := fmt.Sprintf("command exited with code %d", terminated.ExitCode)
+			if terminated.Reason != "" {
+				errMsg = fmt.Sprintf("%s (%s)", errMsg, terminated.Reason)
+			}
+			if terminated.Message != "" {
+				errMsg = fmt.Sprintf("%s: %s", errMsg, terminated.Message)
+			}
+			return logs, errors.New(errMsg)
+		}
+		return logs, nil
+	}
+
+	if lastPod != nil && lastPod.Status.Reason != "" {
+		return logs, fmt.Errorf("debug pod failed: %s", lastPod.Status.Reason)
+	}
+	if waitMsg != "" {
+		return logs, fmt.Errorf("debug container did not complete: %s", waitMsg)
+	}
+	return logs, errors.New("debug container did not reach a terminal state")
+}
+
+func sanitizeForName(name string) string {
+	lower := strings.ToLower(name)
+	var b strings.Builder
+	b.Grow(len(lower))
+	for _, r := range lower {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' {
+			b.WriteRune(r)
+			continue
+		}
+		b.WriteRune('-')
+	}
+	sanitized := strings.Trim(b.String(), "-")
+	if sanitized == "" {
+		sanitized = "node"
+	}
+	if len(sanitized) > 40 {
+		sanitized = sanitized[:40]
+	}
+	return sanitized
+}
+
+func containerStatusByName(statuses []corev1.ContainerStatus, name string) *corev1.ContainerStatus {
+	for idx := range statuses {
+		if statuses[idx].Name == name {
+			return &statuses[idx]
+		}
+	}
+	return nil
+}