|
| 1 | +--- |
| 2 | +title: Streamlining Node Access with K9s and kubectl-node-shell |
| 3 | +date: 2025-11-19 |
| 4 | +authors: |
| 5 | + - japerezjr |
| 6 | +slug: k9s-node-shell-integration |
| 7 | +description: Learn how to integrate kubectl-node-shell with K9s for seamless node access and debugging in Kubernetes clusters |
| 8 | +categories: |
| 9 | + - Kubernetes |
| 10 | + - DevOps |
| 11 | + - Tooling |
| 12 | +--- |
| 13 | + |
| 14 | +# Streamlining Node Access with K9s and kubectl-node-shell |
| 15 | + |
| 16 | +Debugging Kubernetes clusters often requires direct access to nodes. There are several ways to access your nodes... ssh, iLO/DRAC, `kubectl debug`, etc. I love shortcuts, aliases, functions, and scripts that can help me quickly gather data and help with my troubleshooting. I have found K9s, a powerful terminal UI for Kubernetes, and how to enhance it with kubectl-node-shell for seamless node access. This quick blog will hopefully give you another tool you can use with your kubernetes clusters. |
| 17 | + |
| 18 | +<!-- more --> |
| 19 | + |
| 20 | +## What is K9s? |
| 21 | + |
| 22 | +[K9s](https://k9scli.io/) is a terminal-based UI for managing Kubernetes clusters. Quoting directly from their site: |
| 23 | + |
| 24 | +> K9s is a terminal based UI to interact with your Kubernetes clusters. The aim of this project is to make it easier to navigate, observe and manage your deployed applications in the wild. K9s continually watches Kubernetes for changes and offers subsequent commands to interact with your observed resources. |
| 25 | +
|
| 26 | +K9s supports custom plugins, which makes it incredibly extensible. |
| 27 | + |
| 28 | +## What is kubectl-node-shell? |
| 29 | + |
| 30 | +[kubectl-node-shell](https://github.com/kvaps/kubectl-node-shell) is a kubectl plugin that opens an interactive shell on any node in your cluster. Unlike `kubectl debug`, it provides direct access to the node's root filesystem and processes, making it ideal for troubleshooting and system-level debugging. |
| 31 | + |
| 32 | +### Installation |
| 33 | + |
| 34 | +First, install kubectl-node-shell: |
| 35 | + |
| 36 | +```bash |
| 37 | +git clone https://github.com/kvaps/kubectl-node-shell.git |
| 38 | +cd kubectl-node-shell |
| 39 | +sudo cp kubectl-node_shell /usr/local/bin/ |
| 40 | +``` |
| 41 | + |
| 42 | +or using curl: |
| 43 | + |
| 44 | +```bash |
| 45 | +curl -LO https://github.com/kvaps/kubectl-node-shell/raw/master/kubectl-node_shell |
| 46 | +chmod +x ./kubectl-node_shell |
| 47 | +sudo mv ./kubectl-node_shell /usr/local/bin/kubectl-node_shell |
| 48 | +``` |
| 49 | + |
| 50 | +Verify the installation: |
| 51 | + |
| 52 | +```bash |
| 53 | +kubectl node-shell --help |
| 54 | +``` |
| 55 | + |
| 56 | +I encourage you to look at the other options possible with kubectl-node-shell. There is even support for Talos |
| 57 | + |
| 58 | +## Integrating with K9s |
| 59 | + |
| 60 | +K9s allows you to define custom commands and plugins through a `plugins.yaml` configuration file. This enables you to launch kubectl-node-shell directly from K9s without leaving the UI. |
| 61 | + |
| 62 | +### Step 1: Locate K9s Configuration |
| 63 | + |
| 64 | +K9s stores its configuration in: |
| 65 | + |
| 66 | +- **macOS/Linux**: `~/.config/k9s/` |
| 67 | +- **Windows**: `%APPDATA%\k9s\` |
| 68 | + |
| 69 | +### Step 2: Create or Edit plugins.yaml |
| 70 | + |
| 71 | +Create or edit `~/.config/k9s/plugins.yaml`: |
| 72 | + |
| 73 | +```yaml |
| 74 | +plugins: |
| 75 | + node-shell: |
| 76 | + shortCut: Shift-S |
| 77 | + description: Node Shell |
| 78 | + scopes: |
| 79 | + - node |
| 80 | + command: kubectl |
| 81 | + background: false |
| 82 | + confirm: false |
| 83 | + args: |
| 84 | + - node-shell |
| 85 | + - $NAME |
| 86 | +``` |
| 87 | +
|
| 88 | +### Step 3: Restart K9s |
| 89 | +
|
| 90 | +Exit and restart K9s for the plugin to load. |
| 91 | +
|
| 92 | +## Using the Integration |
| 93 | +
|
| 94 | +1. Launch K9s: `k9s` |
| 95 | +2. Navigate to the Nodes view (press `:nodes` or use the menu) |
| 96 | +3. Select a node |
| 97 | +4. Press `Shift-S` to open a shell on that node |
| 98 | +5. You now have direct access to the node's filesystem and processes |
| 99 | + |
| 100 | + |
| 101 | +## Common Use Cases |
| 102 | + |
| 103 | +### Debugging Network Issues |
| 104 | + |
| 105 | +```bash |
| 106 | +# Inside the node shell |
| 107 | +ip addr show |
| 108 | +netstat -tulpn |
| 109 | +iptables -L -n |
| 110 | +``` |
| 111 | + |
| 112 | +### Checking Disk Space |
| 113 | + |
| 114 | +```bash |
| 115 | +df -h |
| 116 | +du -sh /var/lib/kubelet/* |
| 117 | +``` |
| 118 | + |
| 119 | +### Inspecting Container Runtime |
| 120 | + |
| 121 | +```bash |
| 122 | +# For containerd |
| 123 | +ctr containers list |
| 124 | +ctr images list |
| 125 | +
|
| 126 | +# For Docker |
| 127 | +docker ps |
| 128 | +docker images |
| 129 | +
|
| 130 | +# For crictl |
| 131 | +crictl pods |
| 132 | +crictl images |
| 133 | +crictl ps |
| 134 | +``` |
| 135 | + |
| 136 | +### Viewing System Logs |
| 137 | + |
| 138 | +```bash |
| 139 | +journalctl -u kubelet -n 50 -f |
| 140 | +dmesg | tail -20 |
| 141 | +``` |
| 142 | + |
| 143 | +## Tips and Best Practices |
| 144 | + |
| 145 | +- **Use read-only access when possible**: If you only need to view logs or check status, consider using `kubectl debug` with read-only access first |
| 146 | +- **Document your findings**: When debugging issues, keep notes of what you discover for future reference |
| 147 | +- **Clean up after yourself**: Exit node shells properly and don't leave processes running |
| 148 | +- **Use K9s shortcuts**: Learn K9s keyboard shortcuts to navigate faster (`:help` shows all available commands) |
| 149 | +- **Combine with other tools**: Use tools like `htop`, `iotop`, and `tcpdump` within the node shell for deeper analysis |
| 150 | + |
| 151 | +## Troubleshooting |
| 152 | + |
| 153 | +**Plugin not appearing in K9s:** |
| 154 | +- Ensure `plugins.yaml` is in the correct directory |
| 155 | +- Check the YAML syntax (use a YAML validator if needed) |
| 156 | +- Restart K9s completely |
| 157 | + |
| 158 | +**kubectl node-shell command not found:** |
| 159 | +- Verify the plugin is in your PATH: `which kubectl-node_shell` |
| 160 | +- Ensure it has execute permissions: `chmod +x /usr/local/bin/kubectl-node_shell` |
| 161 | + |
| 162 | +**Permission denied errors:** |
| 163 | +- You need cluster admin privileges to access nodes |
| 164 | +- Check your kubeconfig and current context |
| 165 | + |
| 166 | +## Comparing Your Options |
| 167 | + |
| 168 | +When you need node access in Kubernetes, you have three main approaches other than physical access, iLO/DRAC, or ssh. Let's compare them: |
| 169 | + |
| 170 | +### kubectl debug |
| 171 | + |
| 172 | +**Pros:** |
| 173 | +- Built into kubectl, no additional installation required |
| 174 | +- Works on any cluster with the debug API enabled |
| 175 | +- Creates temporary debug containers, leaving the node untouched |
| 176 | +- Supports read-only access for safer exploration |
| 177 | +- Good for RBAC-restricted environments (can be limited to specific namespaces) |
| 178 | + |
| 179 | +**Cons:** |
| 180 | +- Slower startup time (creates a pod, then a container) |
| 181 | +- Limited to the container's filesystem and capabilities |
| 182 | +- Requires the node to be running and schedulable |
| 183 | +- Less direct access to node-level processes and system state |
| 184 | +- More verbose command syntax |
| 185 | + |
| 186 | +### K9s with K9S_FEATURE_GATE_NODE_SHELL=true |
| 187 | + |
| 188 | +**Pros:** |
| 189 | +- Built into K9s, no external plugins needed |
| 190 | +- Integrated directly into the K9s UI |
| 191 | +- Fast and convenient within the terminal UI |
| 192 | +- No additional dependencies to manage |
| 193 | + |
| 194 | +**Cons:** |
| 195 | +- Requires setting an environment variable before launching K9s |
| 196 | +- Less customizable than the plugin approach |
| 197 | +- May have limitations depending on K9s version |
| 198 | +- Still requires kubectl node-shell or similar backend to function |
| 199 | +- Feature gate may change or be removed in future K9s versions |
| 200 | + |
| 201 | +### kubectl-node-shell with K9s Plugin |
| 202 | + |
| 203 | +**Pros:** |
| 204 | +- Direct access to the node's root filesystem and all processes |
| 205 | +- Fastest execution (direct shell, no container overhead) |
| 206 | +- Full system-level debugging capabilities |
| 207 | +- Customizable through plugins.yaml for different workflows |
| 208 | +- Can chain multiple commands (journalctl, top, tcpdump, etc.) |
| 209 | +- Persistent across K9s sessions once configured |
| 210 | + |
| 211 | +**Cons:** |
| 212 | +- Requires additional installation and setup |
| 213 | +- Needs cluster admin privileges |
| 214 | +- Direct node access is a security consideration |
| 215 | +- Plugin configuration requires manual YAML editing |
| 216 | +- Less portable if you frequently switch clusters |
| 217 | + |
| 218 | +## Recommendation |
| 219 | + |
| 220 | +- **Use `kubectl debug`** for general troubleshooting in shared clusters or when you need RBAC compliance |
| 221 | +- **Use K9s Node Shell feature gate** if you want built-in node access without extra setup |
| 222 | +- **Use kubectl-node-shell plugin** when you need full system access and are working in environments where you have admin privileges |
| 223 | + |
| 224 | +For most users working with their own clusters or in DevOps roles, the kubectl-node-shell plugin integration offers the best balance of speed, functionality, and convenience. |
| 225 | + |
| 226 | +## Conclusion |
| 227 | + |
| 228 | +Hopefully you will find that combining K9s with kubectl-node-shell creates a powerful workflow for Kubernetes cluster management and debugging. Personally, I perfer to use k9s vs kubectl and this integration has helped me reduce context switching and makes node access as simple as pressing a keyboard shortcut. Whether you're troubleshooting network issues, checking disk space, or inspecting system logs, this setup will save you time and improve your debugging efficiency. |
| 229 | + |
| 230 | +Choose the approach that best fits your security requirements and workflow. Start using K9s with node-shell integration today and streamline your Kubernetes operations. |
0 commit comments