{"id":13521626,"url":"https://github.com/aylei/kubectl-debug","last_synced_at":"2025-05-15T06:08:18.856Z","repository":{"id":41081503,"uuid":"162127381","full_name":"aylei/kubectl-debug","owner":"aylei","description":"This repository is no longer maintained, please checkout https://github.com/JamesTGrant/kubectl-debug.","archived":false,"fork":false,"pushed_at":"2023-10-19T02:52:57.000Z","size":2258,"stargazers_count":2306,"open_issues_count":61,"forks_count":303,"subscribers_count":55,"default_branch":"master","last_synced_at":"2025-04-14T10:42:40.097Z","etag":null,"topics":["debug","kubectl","kubectl-plugins","kubernetes","troubleshooting"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aylei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-17T12:28:48.000Z","updated_at":"2025-04-12T16:48:46.000Z","dependencies_parsed_at":"2024-01-10T07:03:16.485Z","dependency_job_id":"644e40c3-411a-429a-aa9c-af3d7c2b47bb","html_url":"https://github.com/aylei/kubectl-debug","commit_stats":{"total_commits":81,"total_committers":23,"mean_commits":"3.5217391304347827","dds":0.4814814814814815,"last_synced_commit":"33caedd99cd440dccd7800e10b04cad6293b2dfa"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aylei%2Fkubectl-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aylei%2Fkubectl-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aylei%2Fkubectl-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aylei%2Fkubectl-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aylei","download_url":"https://codeload.github.com/aylei/kubectl-debug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283350,"owners_count":22045141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","kubectl","kubectl-plugins","kubernetes","troubleshooting"],"created_at":"2024-08-01T06:00:36.584Z","updated_at":"2025-05-15T06:08:18.789Z","avatar_url":"https://github.com/aylei.png","language":"Go","readme":"# Deprecation Notice\n\nThis repository is no longer maintained, please checkout https://github.com/JamesTGrant/kubectl-debug.\n\n# Kubectl-debug\n\n![license](https://img.shields.io/hexpm/l/plug.svg)\n[![travis](https://travis-ci.org/aylei/kubectl-debug.svg?branch=master)](https://travis-ci.org/aylei/kubectl-debug)\n[![Go Report Card](https://goreportcard.com/badge/github.com/aylei/kubectl-debug)](https://goreportcard.com/report/github.com/aylei/kubectl-debug)\n[![docker](https://img.shields.io/docker/pulls/aylei/debug-agent.svg)](https://hub.docker.com/r/aylei/debug-agent)\n\n[简体中文](/docs/zh-cn.md)\n\n# Overview\n\n`kubectl-debug` is an out-of-tree solution for [troubleshooting running pods](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/node/troubleshoot-running-pods.md), which allows you to run a new container in running pods for debugging purpose ([examples](/docs/examples.md)). The new container will join the `pid`, `network`, `user` and `ipc` namespaces of the target container, so you can use arbitrary trouble-shooting tools without pre-installing them in your production container image.\n\n- [Kubectl-debug](#kubectl-debug)\n- [Overview](#overview)\n- [Screenshots](#screenshots)\n- [Quick Start](#quick-start)\n  - [Install the kubectl debug plugin](#install-the-kubectl-debug-plugin)\n  - [(Optional) Install the debug agent DaemonSet](#optional-install-the-debug-agent-daemonset)\n  - [Debug instructions](#debug-instructions)\n- [Build from source](#build-from-source)\n- [port-forward mode And agentless mode(Default opening)](#port-forward-mode-and-agentless-modedefault-opening)\n- [Configuration](#configuration)\n- [Authorization](#authorization)\n- [Roadmap](#roadmap)\n- [Contribute](#contribute)\n- [Acknowledgement](#acknowledgement)\n\n# Screenshots\n\n![gif](/docs/kube-debug.gif)\n\n# Quick Start\n\n## Install the kubectl debug plugin\n\nHomebrew:\n```shell\nbrew install aylei/tap/kubectl-debug\n```\n\nDownload the binary:\n```bash\nexport PLUGIN_VERSION=0.1.1\n# linux x86_64\ncurl -Lo kubectl-debug.tar.gz https://github.com/aylei/kubectl-debug/releases/download/v${PLUGIN_VERSION}/kubectl-debug_${PLUGIN_VERSION}_linux_amd64.tar.gz\n# macos\ncurl -Lo kubectl-debug.tar.gz https://github.com/aylei/kubectl-debug/releases/download/v${PLUGIN_VERSION}/kubectl-debug_${PLUGIN_VERSION}_darwin_amd64.tar.gz\n\ntar -zxvf kubectl-debug.tar.gz kubectl-debug\nsudo mv kubectl-debug /usr/local/bin/\n```\n\nFor windows users, download the latest archive from the [release page](https://github.com/aylei/kubectl-debug/releases/tag/v0.1.1), decompress the package and add it to your PATH.\n\n## (Optional) Install the debug agent DaemonSet\n\n`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.(Turn on agentless mode by default)\n\nWhile convenient, creating pod before debugging can be time consuming. You can install the debug agent DaemonSet and use --agentless=false params in advance to skip this:\n\n```bash\n# if your kubernetes version is v1.16 or newer\nkubectl apply -f https://raw.githubusercontent.com/aylei/kubectl-debug/master/scripts/agent_daemonset.yml\n# if your kubernetes is old version(\u003cv1.16), you should change the apiVersion to extensions/v1beta1, As follows\nwget https://raw.githubusercontent.com/aylei/kubectl-debug/master/scripts/agent_daemonset.yml\nsed -i '' '1s/apps\\/v1/extensions\\/v1beta1/g' agent_daemonset.yml\nkubectl apply -f agent_daemonset.yml\n# or using helm\nhelm install kubectl-debug -n=debug-agent ./contrib/helm/kubectl-debug\n# use daemonset agent mode(close agentless mode)\nkubectl debug --agentless=false POD_NAME\n```\n\n## Debug instructions\n\nTry it out!\n\n```bash\n# kubectl 1.12.0 or higher\nkubectl debug -h\n# if you installed the debug agent's daemonset, you can use --agentless=false to speed up the startup.\n# the default agentless mode will be used in following commands\nkubectl debug POD_NAME\n\n# in case of your pod stuck in `CrashLoopBackoff` state and cannot be connected to,\n# you can fork a new pod and diagnose the problem in the forked pod\nkubectl debug POD_NAME --fork\n\n# in fork mode, if you want the copied pod retains the labels of the original pod, you can use the --fork-pod-retain-labels parameter to set(comma separated, and spaces are not allowed)\n# Example is as follows\n# If not set, this parameter is empty by default (Means that any labels of the original pod are not retained, and the labels of the copied pods are empty.)\nkubectl debug POD_NAME --fork --fork-pod-retain-labels=\u003clabelKeyA\u003e,\u003clabelKeyB\u003e,\u003clabelKeyC\u003e\n\n# in order to enable node without public IP or direct access (firewall and other reasons) to access, port-forward mode is enabled by default.\n# if you don't need to turn on port-forward mode, you can use --port-forward false to turn off it.\nkubectl debug POD_NAME --port-forward=false --agentless=false --daemonset-ns=kube-system --daemonset-name=debug-agent\n\n# old versions of kubectl cannot discover plugins, you may execute the binary directly\nkubectl-debug POD_NAME\n\n# use primary docker registry, set registry kubernets secret to pull image\n# the default registry-secret-name is kubectl-debug-registry-secret, the default namespace is default\n# please set the secret data source as {Username: \u003cusername\u003e, Password: \u003cpassword\u003e}\nkubectl-debug POD_NAME --image calmkart/netshoot:latest --registry-secret-name \u003ck8s_secret_name\u003e --registry-secret-namespace \u003cnamespace\u003e\n# in default agentless mode, you can set the agent pod's resource limits/requests, for example:\n# default is not set\nkubectl-debug POD_NAME --agent-pod-cpu-requests=250m --agent-pod-cpu-limits=500m --agent-pod-memory-requests=200Mi --agent-pod-memory-limits=500Mi\n```\n\n* You can configure the default arguments to simplify usage, refer to [Configuration](#configuration)\n* Refer to [Examples](/docs/examples.md) for practical debugging examples\n\n## (Optional) Create a Secret for Use with Private Docker Registries\n\nYou can use a new or existing [Kubernetes `dockerconfigjson` secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials). For example:\n\n```bash\n# Be sure to run \"docker login\" beforehand.\nkubectl create secret generic kubectl-debug-registry-secret \\\n    --from-file=.dockerconfigjson=\u003cpath/to/.docker/config.json\u003e \\\n    --type=kubernetes.io/dockerconfigjson\n```\n\nAlternatively, you can create a secret with the key `authStr` and a JSON payload containing a `Username` and `Password`. For example:\n\n```bash\necho -n '{\"Username\": \"calmkart\", \"Password\": \"calmkart\"}' \u003e ./authStr\nkubectl create secret generic kubectl-debug-registry-secret --from-file=./authStr\n```\n\nRefer to [the official Kubernetes documentation on Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) for more ways to create them.\n\n# Build from source\n\nClone this repo and:\n```bash\n# make will build plugin binary and debug-agent image\nmake\n# install plugin\nmv kubectl-debug /usr/local/bin\n\n# build plugin only\nmake plugin\n# build agent only\nmake agent-docker\n```\n\n# port-forward mode And agentless mode(Default opening)\n\n- `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`.\n\n- `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.\n\n# Configuration\n\n`kubectl-debug` uses [nicolaka/netshoot](https://github.com/nicolaka/netshoot) as the default image to run debug container, and use `bash` as default entrypoint.\n\nYou can override the default image and entrypoint with cli flag, or even better, with config file `~/.kube/debug-config`:\n\n```yaml\n# debug agent listening port(outside container)\n# default to 10027\nagentPort: 10027\n\n# whether using agentless mode\n# default to true\nagentless: true\n# namespace of debug-agent pod, used in agentless mode\n# default to 'default'\nagentPodNamespace: default\n# prefix of debug-agent pod, used in agentless mode\n# default to  'debug-agent-pod'\nagentPodNamePrefix: debug-agent-pod\n# image of debug-agent pod, used in agentless mode\n# default to 'aylei/debug-agent:latest'\nagentImage: aylei/debug-agent:latest\n\n# daemonset name of the debug-agent, used in port-forward\n# default to 'debug-agent'\ndebugAgentDaemonset: debug-agent\n# daemonset namespace of the debug-agent, used in port-forwad\n# default to 'default'\ndebugAgentNamespace: kube-system\n# whether using port-forward when connecting debug-agent\n# default true\nportForward: true\n# image of the debug container\n# default as showed\nimage: nicolaka/netshoot:latest\n# start command of the debug container\n# default ['bash']\ncommand:\n- '/bin/bash'\n- '-l'\n# private docker registry auth kuberntes secret\n# default registrySecretName is kubectl-debug-registry-secret\n# default registrySecretNamespace is default\nregistrySecretName: my-debug-secret\nregistrySecretNamespace: debug\n# in agentless mode, you can set the agent pod's resource limits/requests:\n# default is not set\nagentCpuRequests: \"\"\nagentCpuLimits: \"\"\nagentMemoryRequests: \"\"\nagentMemoryLimits: \"\"\n# in fork mode, if you want the copied pod retains the labels of the original pod, you can change this params\n# format is []string\n# If not set, this parameter is empty by default (Means that any labels of the original pod are not retained, and the labels of the copied pods are empty.)\nforkPodRetainLabels: []\n# You can disable SSL certificate check when communicating with image registry by \n# setting registrySkipTLSVerify to true.\nregistrySkipTLSVerify: false\n# You can set the log level with the verbosity setting\nverbosity : 0\n```\n\nIf the debug-agent is not accessible from host port, it is recommended to set `portForward: true` to using port-forawrd mode.\n\nPS: `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).\n\n# Authorization\n\nCurrently, `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.\n\n# Auditing / Security\n\nSome teams may want to limit what debug image users are allowed to use and to have an audit record for each command they run in the debug container.\n\nYou can use the environment variable ```KCTLDBG_RESTRICT_IMAGE_TO``` restrict the agent to using a specific container image.   For example putting the following in the container spec section of your daemonset yaml will force the agent to always use the image ```docker.io/nicolaka/netshoot:latest``` regardless of what the user specifies on the kubectl-debug command line \n```\n          env : \n            - name: KCTLDBG_RESTRICT_IMAGE_TO\n              value: docker.io/nicolaka/netshoot:latest\n```\nIf ```KCTLDBG_RESTRICT_IMAGE_TO``` is set and as a result agent is using an image that is different than what the user requested then the agent will log to standard out a message that announces what is happening.   The message will include the URI's of both images.\n\nAuditing can be enabled by placing \n```audit: true```\nin the agent's config file.  \n\nThere are 3 settings related to auditing.\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003eaudit\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003eBoolean value that indicates whether auditing should be enabled or not.  Default value is \u003ccode\u003efalse\u003c/code\u003e\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003eaudit_fifo\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003eTemplate of path to a FIFO that will be used to exchange audit information from the debug container to the agent.  The default value is \u003ccode\u003e/var/data/kubectl-debug-audit-fifo/KCTLDBG-CONTAINER-ID\u003c/code\u003e.   If auditing is enabled then the agent will :\n\u003col\u003e\n\u003cli\u003ePrior to creating the debug container, create a fifo based on the value of \u003ccode\u003eaudit_fifo\u003c/code\u003e.  The agent will replace \u003ccode\u003eKCTLDBG-CONTAINER-ID\u003c/code\u003e with the id of the debug container it is creating.\u003c/li\u003e\n\u003cli\u003eCreate a thread that reads lines of text from the FIFO and then writes log messages to standard out, where the log messages look similar to example below \u003cbr/\u003e\n\u003ccode\u003e\n2020/05/22 17:59:58 runtime.go:717: audit - user: USERNAME/885cbd0506868985a6fc491bb59a2d3c debugee: 48107cbdacf4b478cbf1e2e34dbea6ebb48a2942c5f3d1effbacf0a216eac94f exec: 265   execve(\"/bin/tar\", [\"tar\", \"--help\"], 0x55a8d0dfa6c0 /* 7 vars */) = 0\n\u003c/code\u003e\u003cbr/\u003e\nWhere USERNAME is the kubernetes user as determined by the client that launched the debug container and debuggee is the container id of the container being debugged.\n\u003c/li\u003e\n\u003cli\u003eBind mount the fifo it creates to the debugger container.  \u003c/li\u003e\n\u003c/ol\u003e\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003eaudit_shim\u003c/code\u003e\n\u003cdd\u003eString array that will be placed before the command that will be run in the debug container.  The default value is \u003ccode\u003e{\"/usr/bin/strace\", \"-o\", \"KCTLDBG-FIFO\", \"-f\", \"-e\", \"trace=/exec\"}\u003c/code\u003e.  The agent will replace KCTLDBG-FIFO with the fifo path ( see above )  If auditing is enabled then agent will use the concatenation of the array specified by \u003ccode\u003eaudit_shim\u003c/code\u003e and the original command array it was going to use.\u003c/dd\u003e\n\u003c/dl\u003e\n\nThe easiest way to enable auditing is to define a config map in the yaml you use to deploy the deamonset.   You can do this by place \n```\napiVersion : v1\nkind: ConfigMap \nmetadata: \n  name : kubectl-debug-agent-config\ndata: \n  agent-config.yml: |  \n    audit: true\n---    \n```\nat the top of the file, adding a ```configmap``` volume like so\n```\n        - name: config\n          configMap:\n            name: kubectl-debug-agent-config\n```\nand a volume mount like so\n```\n            - name: config\n              mountPath: \"/etc/kubectl-debug/agent-config.yml\"\n              subPath: agent-config.yml\n```\n.\n\n\n# Roadmap\n\n`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`.\n\n- [ ] Security: currently, `kubectl-debug` do authorization in the client-side, which should be moved to the server-side (debug-agent)\n- [ ] More unit tests\n- [ ] More real world debugging example\n- [ ] e2e tests\n\nIf you are interested in any of the above features, please file an issue to avoid potential duplication.\n\n# Contribute\n\nFeel free to open issues and pull requests. Any feedback is highly appreciated!\n\n# Acknowledgement\n\nThis project would not be here without the effort of [our contributors](https://github.com/aylei/kubectl-debug/graphs/contributors), thanks!\n","funding_links":[],"categories":["K8S-Tools","Go","CLI tools","Tools and Libraries","kubectl Plugins","Debug"],"sub_categories":["Testing and Troubleshooting","Installing plugins via awesome-kubectl-plugins","[Jenkins](#jenkins)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faylei%2Fkubectl-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faylei%2Fkubectl-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faylei%2Fkubectl-debug/lists"}