Create debugging sessions for troubleshooting workloads and nodes.
Debug containers allow you to interactively troubleshoot running pods, create copies of pods with modified configuration, or attach a debug container to a node.
# Create an interactive debugging session in pod mypod and immediately attach to it.
ksail workload debug mypod -it --image=busybox
# Create an interactive debugging session for the pod in the file pod.yaml and immediately attach to it.
# (requires the EphemeralContainers feature to be enabled in the cluster)
ksail workload debug -f pod.yaml -it --image=busybox
# Create a debug container named debugger using a custom automated debugging image.
ksail workload debug --image=myproj/debug-tools -c debugger mypod
# Create a copy of mypod adding a debug container and attach to it
ksail workload debug mypod -it --image=busybox --copy-to=my-debugger
# Create a copy of mypod changing the command of mycontainer
ksail workload debug mypod -it --copy-to=my-debugger --container=mycontainer -- sh
# Create a copy of mypod changing all container images to busybox
ksail workload debug mypod --copy-to=my-debugger --set-image=*=busybox
# Create a copy of mypod adding a debug container and changing container images
ksail workload debug mypod -it --copy-to=my-debugger --image=debian --set-image=app=app:debug,sidecar=sidecar:debug
# Create an interactive debugging session on a node and immediately attach to it.
# The container will run in the host namespaces and the host's filesystem will be mounted at /host
ksail workload debug node/mynode -it --image=busybox
--arguments-only If specified, everything after -- will be passed to the new container as Args instead of Command.
--as string Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
--as-group stringArray Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
--as-uid string UID to impersonate for the operation.
--as-user-extra stringArray User extras to impersonate for the operation, this flag can be repeated to specify multiple values for the same key.
--attach If true, wait for the container to start running, and then attach as if 'kubectl attach ...' were called. Default false, unless '-i/--stdin' is set, in which case the default is true.
--cache-dir string Default cache directory (default "~/.kube/cache")
--certificate-authority string Path to a cert file for the certificate authority
--client-certificate string Path to a client certificate file for TLS
--client-key string Path to a client key file for TLS
--cluster string The name of the kubeconfig cluster to use
-c, --container string Container name to use for debug container.
--context string The name of the kubeconfig context to use
--copy-to string Create a copy of the target Pod with this name.
--custom string Path to a JSON or YAML file containing a partial container spec to customize built-in debug profiles.
--disable-compression If true, opt-out of response compression for all requests to the server
--env stringToString Environment variables to set in the container. (default [])
-f, --filename strings identifying the resource to debug
--host string Node name for host-level debugging (bypasses Kubernetes, targets the infrastructure node directly)
--image string Container image to use for debug container.
--image-pull-policy string The image pull policy for the container. If left empty, this value will not be specified by the client and defaulted by the server.
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
--keep-annotations If true, keep the original pod annotations.(This flag only works when used with '--copy-to')
--keep-init-containers Run the init containers for the pod. Defaults to true.(This flag only works when used with '--copy-to') (default true)
--keep-labels If true, keep the original pod labels.(This flag only works when used with '--copy-to')
--keep-liveness If true, keep the original pod liveness probes.(This flag only works when used with '--copy-to')
--keep-readiness If true, keep the original pod readiness probes.(This flag only works when used with '--copy-to')
--keep-startup If true, keep the original startup probes.(This flag only works when used with '--copy-to')
--kubeconfig string Path to the kubeconfig file to use for CLI requests. (default "~/.kube/config")
-n, --namespace string If present, the namespace scope for this CLI request
--profile string Options are "legacy", "general", "baseline", "netadmin", "restricted" or "sysadmin". (default "legacy")
-q, --quiet If true, suppress informational messages.
--replace When used with '--copy-to', delete the original Pod.
--request-timeout string The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
--same-node When used with '--copy-to', schedule the copy of target Pod on the same node.
-s, --server string The address and port of the Kubernetes API server
--set-image stringToString When used with '--copy-to', a list of name=image pairs for changing container images, similar to how 'kubectl set image' works. (default [])
--share-processes When used with '--copy-to', enable process namespace sharing in the copy. (default true)
-i, --stdin Keep stdin open on the container(s) in the pod, even if nothing is attached.
--target string When using an ephemeral container, target processes in this container name.
--tls-server-name string Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
--token string Bearer token for authentication to the API server
-t, --tty Allocate a TTY for the debugging container.
--user string The name of the kubeconfig user to use
--benchmark Show per-activity benchmark output
--config string Path to config file (default: ksail.yaml found via directory traversal)
