Skip to main content

Connect to a Node

Use debug Pods to troubleshoot issues

This guide provides detailed instructions on how to connect to a Node using a debug Pod for troubleshooting purposes. This approach is particularly useful for diagnosing and resolving issues with a Node that is not functioning as expected. Common scenarios for connecting to a Node include investigating problems with the Node's network connectivity or local storage.

Prerequisites​

Before you begin, ensure you have:

  • An active CoreWeave account
  • kubectl installed locally
  • A Kubeconfig with access to the desired Node

About debug Pods​

To connect to a Node, you need to create a debug Pod that runs on the Node you want to troubleshoot. The debug Pod allows you to interact with the Node's filesystem and network interfaces, and run diagnostic commands such as ip, ifconfig, nc, ping, and ps. Additional tools, such as mtr, tcpdump, and curl, can be installed using the Node's package manager. When using a debug Pod, note that:

  • kubectl debug automatically creates a new Pod name based on the Node name.
  • The root filesystem of the Node is mounted at /host.
  • Debug Pods are not privileged, so commands such as chroot /host that are restricted to superusers will fail. If you need a privileged pod, create it manually or use the --profile=sysadmin flag.
  • You can set specific properties such as securityContext to a debugging Pod by applying Debugging Profiles.

Connect to a Node​

To connect to a Node, use kubectl debug node. The following example creates a debug Pod on a Node named mynode with the ubuntu image and an interactive shell:

Example
$
kubectl debug node/mynode -i -t --image=ubuntu



Creating debugging Pod `node-debugger-mynode-pdx84` with container debugger on Node `mynode`.

If you don't see a command prompt, try pressing enter.

root@mynode:/#

Use this shell to run diagnostic commands and troubleshoot issues on the Node.

Command line explanation​

  • kubectl debug node/mynode: Create a debug Pod on the Node named mynode.
  • -i: Keep stdin open on the container(s) in the pod, even if nothing is attached.
  • -t: Allocate a TTY for the debugging container.
  • --image=ubuntu: Use the Ubuntu container image for the debug Pod.

Clean up​

When the debug Pod is no longer needed, delete it:

Example
$
kubectl get pods



NAME                          READY   STATUS       RESTARTS   AGE

node-debugger-mynode-pdx84    0/1     Completed    0          8m1s



# Use your Pod's name

$
kubectl delete pod node-debugger-mynode-pdx84 --now



 Pod "node-debugger-mynode-pdx84" deleted

More options​

kubectl debug node offers many other command-line options to customize the debug Pod's namespace, container name, and image. You can also issue commands to the Pod or copy an existing Pod's configuration. Use --help for a full list of options with examples:

Example
$
kubectl debug node --help

Other references​

To learn more, see Debugging Kubernetes Nodes With Kubectl in the Kubernetes documentation.

Last updated on