You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For windows users, download the latest archive from the [release page](https://github.com/aylei/kubectl-debug/releases/tag/v0.1.0), decompress the package and add it to your PATH.
64
49
50
+
## (Optional) Install the debug agent DaemonSet
51
+
52
+
`kubectl-debug` requires an agent pod to communicate with the container runtime. In the [agentless mode](#port-forward-mode-And-agentless-mode), the agent pod can be created when a debug session starts and to be cleaned up when the session ends.
53
+
54
+
While convenient, creating pod before debugging can be time consuming. You can install the debug agent DaemonSet in advance to skip this:
# old versions of kubectl cannot discover plugins, you may execute the binary directly
79
81
kubect-debug POD_NAME
80
-
81
82
```
82
83
83
-
Any trouble? [file and issue for help](https://github.com/aylei/kubectl-debug/issues/new)
84
+
* You can configure the default arguments to simplify usage, refer to [Configuration](#configuration)
85
+
* Refer to [Examples](/docs/examples.md) for practical debugging examples
84
86
85
87
# Build from source
86
88
@@ -101,11 +103,10 @@ make agent-docker
101
103
102
104
-`port-foward` mode: By default, `kubectl-debug` will directly connect with the target host. When `kubectl-debug` cannot connect to `targetHost:agentPort`, you can enable `port-forward` mode. In `port-forward` mode, the local machine listens on `localhost:agentPort` and forwards data to/from `targetPod:agentPort`.
103
105
104
-
105
106
-`agentless` mode: By default, `debug-agent` needs to be pre-deployed on each node of the cluster, which consumes cluster resources all the time. Unfortunately, debugging Pod is a low-frequency operation. To avoid loss of cluster resources, the `agentless` mode has been added in [#31](https://github.com/aylei/kubectl-debug/pull/31). In `agentless` mode, `kubectl-debug` will first start `debug-agent` on the host where the target Pod is located, and then `debug-agent` starts the debug container. After the user exits, `kubectl-debug` will delete the debug container and `kubectl-debug` will delete the `debug-agent` pod at last.
106
107
107
108
108
-
# Configurations
109
+
# Configuration
109
110
110
111
`kubectl-debug` uses [nicolaka/netshoot](https://github.com/nicolaka/netshoot) as the default image to run debug container, and use `bash` as default entrypoint.
111
112
@@ -152,35 +153,25 @@ If the debug-agent is not accessible from host port, it is recommended to set `p
152
153
153
154
PS: `kubectl-debug`will always override the entrypoint of the container, which is by design to avoid users running an unwanted service by mistake(of course you can always do this explicitly).
154
155
155
-
# Roadmap
156
-
157
-
`kubectl-debug`is supposed to be just a troubleshooting helper, and is going be replaced by the native `kubectl debug` command when [this proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/troubleshoot-running-pods.md) is implemented and merged in the future kubernetes release. But for now, there is still some works to do to improve `kubectl-debug`.
158
-
159
-
If you are interested in any of following features, please file an issue to avoid potential duplication.
160
-
161
-
- [ ] Security. `kubectl-debug` runs privileged agent on every node, and client talks to the agent directly. A possible solution is introducing a central apiserver to do RBAC, which integrates to the kube apiserver using [aggregation layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
162
-
- [ ] Protocol. `kubectl-debug` vendor the SPDY wrapper from `client-go`. SPDY is deprecated now, websockets may be a better choice
163
-
- [ ] e2e tests.
156
+
# Authorization
164
157
165
-
# Details
158
+
Currently, `kubectl-debug` reuse the privilege of the `pod/exec` sub resource to do authorization, which means that it has the same privilege requirements with the `kubectl exec` command.
166
159
167
-
`kubectl-debug` consists of 2 components:
160
+
# Roadmap
168
161
169
-
* the kubectl plugin: a cli client of `node agent`, serves `kubectl debug` command,
170
-
* the node agent: responsible for manipulating the "debug container"; node agent will also act as a websockets relay for remote tty
162
+
`kubectl-debug`is supposed to be just a troubleshooting helper, and is going be replaced by the native `kubectl debug` command when [this proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/troubleshoot-running-pods.md) is implemented and merged in the future kubernetes release. But for now, there is still some works to do to improve `kubectl-debug`.
171
163
172
-
When user run `kubectl debug target-pod -c <container-name> /bin/bash`:
164
+
- [ ] Security: Currently, `kubectl-debug` do authorization in the client-side, which should be moved to the server-side (debug-agent)
165
+
- [ ] More unit tests
166
+
- [ ] More real world debugging example
167
+
- [ ] e2e tests
173
168
174
-
1. The plugin gets the pod info from apiserver and extract the `hostIP`, if the target container does not exist or is not currently running, an error is raised.
175
-
2. The plugin sends an HTTP request to the specific node agent running on the `hostIP`, which includes a protocol upgrade from HTTP to SPDY.
176
-
3. The agent runs a container in the pod's namespaces (ipc, pid, network, etc) with the STDIN stay open (`-i` flag).
177
-
4. The agent checks if the target container is actively running, if not, write an error to client.
178
-
5. The agent runs a `debug container` with `tty` and `stdin` opened, the `debug container` will join the `pid`, `network`, `ipc` and `user` namespace of the target container.
179
-
6. The agent pipes the connection into the `debug container` using `attach`
180
-
7. **Debug in the debug container**.
181
-
8. Job is done, user closes the SPDY connection.
182
-
9. The node agent closes the SPDY connection, then waits for the `debug container` to exit and do the cleanup.
169
+
If you are interested in any of the above features, please file an issue to avoid potential duplication.
183
170
184
171
# Contribute
185
172
186
173
Feel free to open issues and pull requests. Any feedback is highly appreciated!
174
+
175
+
# Acknowledgement
176
+
177
+
This project would not be here without the effort of [our contributors](https://github.com/aylei/kubectl-debug/graphs/contributors), thanks!
* the kubectl plugin: a cli client of `node agent`, serves `kubectl debug` command,
6
+
* the node agent: responsible for manipulating the "debug container"; node agent will also act as a websockets relay for remote tty
7
+
8
+
When user run `kubectl debug target-pod -c <container-name> /bin/bash`:
9
+
10
+
1. The plugin gets the pod info from apiserver and extract the `hostIP`, if the target container does not exist or is not currently running, an error is raised.
11
+
2. The plugin sends an HTTP request to the specific node agent running on the `hostIP`, which includes a protocol upgrade from HTTP to SPDY.
12
+
3. The agent runs a container in the pod's namespaces (ipc, pid, network, etc) with the STDIN stay open (`-i` flag).
13
+
4. The agent checks if the target container is actively running, if not, write an error to client.
14
+
5. The agent runs a `debug container` with `tty` and `stdin` opened, the `debug container` will join the `pid`, `network`, `ipc` and `user` namespace of the target container.
15
+
6. The agent pipes the connection into the `debug container` using `attach`
16
+
7.**Debug in the debug container**.
17
+
8. Job is done, user closes the SPDY connection.
18
+
9. The node agent closes the SPDY connection, then waits for the `debug container` to exit and do the cleanup.
#old versions of kubectl cannot discover plugins, you may execute the binary directly
78
+
#老版本的 kubectl 无法自动发现插件, 需要直接调用 binary
54
79
kubect-debug POD_NAME
55
-
56
80
```
57
81
58
-
Any trouble? [file and issue for help](https://github.com/aylei/kubectl-debug/issues/new)
82
+
# 构建项目
59
83
84
+
克隆仓库, 然后执行:
85
+
```bash
86
+
# make will build plugin binary and debug-agent image
87
+
make
88
+
# install plugin
89
+
mv kubectl-debug /usr/local/bin
90
+
91
+
# build plugin only
92
+
make plugin
93
+
# build agent only
94
+
make agent-docker
95
+
```
60
96
61
97
# port-forward 模式和 agentless 模式
62
98
@@ -65,7 +101,7 @@ Any trouble? [file and issue for help](https://github.com/aylei/kubectl-debug/is
65
101
-`agentless`模式： 默认情况下，`debug-agent`需要预先部署在集群每个节点上，会一直消耗集群资源，然而调试 Pod 是低频操作。为避免集群资源损失，在[#31](https://github.com/aylei/kubectl-debug/pull/31)增加了`agentless`模式。`agentless`模式下，`kubectl-debug`会先在目标Pod所在宿主机上启动`debug-agent`，然后再启动调试容器。用户调试结束后，`kubectl-debug`会依次删除调试容器和在目的主机启动的`degbug-agent`。
0 commit comments