Add agentless mode document, add agentless to configuration option and fix bug when users debug pods which are on the same host,simultaneously. (#33)

Author: tkanng

README.md

@@ -14,6 +14,7 @@
 - [screenshots](#screenshots)
 - [quick start](#quick-start)
 - [build from source](#build-from-source)
+- [port-forward and agentless](#port-forward-mode-And-agentless-mode)
 - [configuration](#configurations)
 - [future works](#future-works)
 - [implementation details](#details)
@@ -96,16 +97,38 @@ make plugin
 make agent-docker
 ```
 
+# port-forward mode And agentless mode
+
+- `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`.
+
+
+- `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.
+
+
 # Configurations
 
 `kubectl-debug` uses [nicolaka/netshoot](https://github.com/nicolaka/netshoot) as the default image to run debug container, and use `bash` as default entrypoint.
 
 You can override the default image and entrypoint with cli flag, or even better, with config file `~/.kube/debug-config`:
 
 ```yaml
-# debug agent listening port
+# debug agent listening port(outside container)
 # default to 10027
 agentPort: 10027
+
+# whether using agentless mode
+# default to false
+agentless: true
+# namespace of debug-agent pod, used in agentless mode
+# default to 'default'
+agentPodNamespace: default
+# prefix of debug-agent pod, used in agentless mode
+# default to  'debug-agent-pod'
+agentPodNamePrefix: debug-agent-pod
+# image of debug-agent pod, used in agentless mode
+# default to 'aylei/debug-agent:latest'
+agentImage: aylei/debug-agent:latest
+
 # daemonset name of the debug-agent, used in port-forward
 # default to 'debug-agent'
 debugAgentDaemonset: debug-agent

docs/zh-cn.md

@@ -57,14 +57,36 @@ kubect-debug POD_NAME
 
 Any trouble? [file and issue for help](https://github.com/aylei/kubectl-debug/issues/new)
 
+
+# port-forward 模式和 agentless 模式
+
+- `port-foward`模式：默认情况下，`kubectl-debug`会直接与目标宿主机建立连接。当`kubectl-debug`无法与目标宿主机直连时，可以开启`port-forward`模式。`port-forward`模式下，本机会监听localhost:agentPort，并将数据转发至目标Pod的agentPort端口。
+
+- `agentless`模式： 默认情况下，`debug-agent`需要预先部署在集群每个节点上，会一直消耗集群资源，然而调试 Pod 是低频操作。为避免集群资源损失，在[#31](https://github.com/aylei/kubectl-debug/pull/31)增加了`agentless`模式。`agentless`模式下，`kubectl-debug`会先在目标Pod所在宿主机上启动`debug-agent`，然后再启动调试容器。用户调试结束后，`kubectl-debug`会依次删除调试容器和在目的主机启动的`degbug-agent`。
+
+
 # 默认镜像和 Entrypoint
 
 `kubectl-debug` 使用 [nicolaka/netshoot](https://github.com/nicolaka/netshoot) 作为默认镜像. 默认镜像和指令都可以通过命令行参数进行覆盖. 考虑到每次都指定有点麻烦, 也可以通过文件配置的形式进行覆盖, 编辑 `~/.kube/debug-config` 文件:
 
 ```yaml
-# debug-agent 的端口
+# debug-agent 映射到宿主机的端口
 # 默认 10027
 agentPort: 10027
+
+# 是否开启ageless模式
+# 默认 false
+agentless: true
+# agentPod 的 namespace, agentless模式可用
+# 默认 default
+agentPodNamespace: default
+# agentPod 的名称前缀，后缀是目的主机名, agentless模式可用
+# 默认 debug-agent-pod
+agentPodNamePrefix: debug-agent-pod
+# agentPod 的镜像, agentless模式可用
+# 默认 aylei/debug-agent:latest
+agentImage: aylei/debug-agent:latest
+
 # debug-agent DaemonSet 的名字, port-forward 模式时会用到
 # 默认 'debug-agent'
 debugAgentDaemonset: debug-agent
@@ -84,6 +106,4 @@ command:
 - '-l
 ```
 
-当 debug-agent 无法直连时, 可以开启 port-forward 模式来绕过
-
 > `kubectl-debug` 会将容器的 entrypoint 直接覆盖掉, 这是为了避免在 debug 时不小心启动非 shell 进程.

pkg/plugin/cmd.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"github.com/aylei/kubectl-debug/version"
 	"io"
 	"net/http"
 	"net/url"
@@ -14,6 +13,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/aylei/kubectl-debug/version"
+
 	"k8s.io/apimachinery/pkg/labels"
 
 	term "github.com/aylei/kubectl-debug/pkg/util"
@@ -70,7 +71,7 @@ You may set default configuration such as image and command in the config file,
 	usageError = "expects 'debug POD_NAME' for debug command"
 
 	defaultAgentImage         = "aylei/debug-agent:latest"
-	defaultAgentPodNamePrefix = "debug-agent-pod-"
+	defaultAgentPodNamePrefix = "debug-agent-pod"
 	defaultAgentPodNamespace  = "default"
 )
 
@@ -285,6 +286,10 @@ func (o *DebugOptions) Complete(cmd *cobra.Command, args []string, argsLenAtDash
 	if config.PortForward {
 		o.PortForward = true
 	}
+	if config.Agentless {
+		o.AgentLess = true
+	}
+
 	o.Ports = []string{strconv.Itoa(o.AgentPort)}
 	o.Config, err = configLoader.ClientConfig()
 	if err != nil {
@@ -332,8 +337,7 @@ func (o *DebugOptions) Run() error {
 	var agentPod *corev1.Pod
 	if o.AgentLess {
 		o.AgentPodNode = pod.Spec.NodeName
-		// add node name as suffix
-		o.AgentPodName = o.AgentPodName + o.AgentPodNode
+		o.AgentPodName = fmt.Sprintf("%s-%s", o.AgentPodName, uuid.NewUUID())
 		agentPod = o.getAgentPod()
 		agentPod, err = o.launchPod(agentPod)
 		if err != nil {

pkg/plugin/config.go

@@ -13,6 +13,7 @@ type Config struct {
 	DebugAgentNamespace string   `yaml:"debugAgentNamespace,omitempty"`
 	Command             []string `yaml:"command,omitempty"`
 	PortForward         bool     `yaml:"portForward,omitempty"`
+	Agentless           bool     `yaml:"agentless,omitempty"`
 	AgentPodNamePrefix  string   `yaml:"agentPodNamePrefix,omitempty"`
 	AgentPodNamespace   string   `yaml:"agentPodNamespace,omitempty"`
 	AgentImage          string   `yaml:"agentImage,omitempty"`