Kubernetes Debugging Container

This repository contains a Docker image designed to assist in debugging Kubernetes issues, particularly related to network connectivity and other common problems. The image is based on Alpine Linux and includes a variety of tools to help with troubleshooting.

Overview

This Docker image provides a lightweight and versatile environment for diagnosing and resolving Kubernetes issues. It includes a range of essential tools for network testing, monitoring, and general troubleshooting.

Included Tools

The following tools are pre-installed in the container:

bash: Bourne Again SHell
bind-tools: Utilities for DNS querying.
conntrack-tools: Tools for network connection tracking.
curl: Command line tool for transferring data with URLs.
fping: A ping-like program that uses ICMP echo requests to determine the status of network hosts.
git: Version control system.
htop: Interactive process viewer.
iperf3: Network bandwidth measurement tool.
iproute2: Utilities for controlling TCP/IP networking and traffic control.
ipset: IP set manipulation tools.
iputils: Collection of utilities for monitoring and managing IP networks.
jq: Command-line JSON processor.
net-tools: A collection of programs for controlling the network subsystem of the Linux kernel.
nmap: Network exploration tool and security scanner.
nmap-ncat: Network connectivity tool.
nmap-scripts: Scripting engine for nmap.
openssh: Secure shell (SSH) tools.
openssl: Toolkit for the TLS and SSL protocols.
tcpdump: Packet analyzer.
vim: Text editor.
wget: Network downloader.
yq: Portable command-line YAML processor written in Go
zsh: Z shell, a powerful command interpreter.

Additionally, the container is configured with oh-my-zsh, along with the zsh-autosuggestions plugin and the powerlevel10k theme for an enhanced command-line experience.

Installation

To pull the Docker image, run the following command:

docker pull ghcr.io/truestory1/netops-toolkit

Usage

Running in Docker

You can run the container interactively to start troubleshooting:

docker run -it --rm ghcr.io/truestory1/netops-toolkit

Running in Kubernetes

As a Standalone Pod

To run the container in a specific Kubernetes namespace, you can create a standalone pod:

Create a file named debug-pod.yaml with the following content:

apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
  namespace: <your-namespace>
spec:
  containers:
    - name: debug-container
      image: ghcr.io/truestory1/netops-toolkit
      stdin: true
      tty: true

Apply the configuration to your Kubernetes cluster:
```
kubectl apply -f debug-pod.yaml
```

Access the pod:

kubectl -n <your-namespace> exec -it debug-pod -- zsh

As a Sidecar

To run the container as a sidecar in an existing pod, you can modify the pod's configuration. Here is an example of adding the debug container as a sidecar:

Edit the deployment file (e.g., deployment.yaml) of your application to include the sidecar container:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: your-app
  namespace: <your-namespace>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: your-app
  template:
    metadata:
      labels:
        app: your-app
    spec:
      containers:
        - name: your-app-container
          image: your-app-image
          # your app container specs
        - name: debug-container
          image: ghcr.io/truestory1/netops-toolkit
          stdin: true
          tty: true

Apply the updated configuration:
```
kubectl apply -f deployment.yaml
```

Access the debug container in the pod:

kubectl -n <your-namespace> exec -it <your-pod-name> -c debug-container -- zsh

Use Cases

Network Connectivity

DNS Queries: Use dig from the bind-tools package to query DNS records.
HTTP Requests: Use curl to test HTTP endpoints.
Ping Hosts: Use fping to check the reachability of hosts.
Network Performance: Use iperf3 to measure network bandwidth between nodes.

System Monitoring

Process Monitoring: Use htop to view and manage system processes interactively.
Network Analysis: Use tcpdump to capture and analyze network traffic.

General Troubleshooting

Configuration Editing: Use vim to edit configuration files.
Version Control: Use git to manage code and configuration changes.
JSON Processing: Use jq to parse and process JSON data.

Custom Configuration

The container includes a custom .zshrc configuration file, which sets up oh-my-zsh with useful plugins and themes. You can modify this configuration by editing the configs/zshrc file and rebuilding the image.

Conclusion

This Docker image provides a robust toolkit for debugging Kubernetes issues, particularly those related to network connectivity. With a range of powerful tools and a customizable shell environment, it can significantly streamline the troubleshooting process.

Usage example

Nginx deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-debug
  namespace: test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-debug
  template:
    metadata:
      labels:
        app: nginx-debug
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80

Let's presume there is a need to perform a debug procedure. Steps:

Get container name within pod

➜  k -n test describe pod nginx-debug-74bc87f79f-mk644
Name:             nginx-debug-74bc87f79f-mk644 <--------------------------------------------------------------  POD NAME
Namespace:        test
[...........]
Containers:
  nginx:  <----------------------------------------------------------------------------------------------- CONTAINER NAME
    Container ID:   containerd://45aa75c5b0a229da569c1dc91e96c3fb612c4d01b2c2a5b2ca83f0b7b427e242
    Image:          nginx:latest
    Image ID:       docker.io/library/nginx@sha256:e3ffd9d807cce9d9f973faff2e420b05243b49fd241b576a3de929bb3362cb60
    Port:           80/TCP
    Host Port:      0/TCP
    State:          Running
      Started:      Tue, 14 May 2024 16:46:14 +0200
    Ready:          True
    Restart Count:  0
    Environment:    <none>
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-2p7pv (ro)

Run debug container

kubectl debug -n <namespace> -it <POD NAME> --image=ghcr.io/truestory1/netops-toolkit --target=<CONTAINER NAME>

Example

$ kubectl debug -n test -it nginx-debug-74bc87f79f-mk644 --image=ghcr.io/truestory1/netops-toolkit --target=nginx
Targeting container "nginx". If you don't see processes from this container it may be because the container runtime doesn't support this feature.
Defaulting debug container name to debugger-r6gdt.
If you don't see a command prompt, try pressing enter.
➜  / ps -ef
PID   USER     TIME  COMMAND
    1 root      0:00 nginx: master process nginx -g daemon off;
   29 101       0:00 nginx: worker process
   30 101       0:00 nginx: worker process
   31 101       0:00 nginx: worker process
   32 101       0:00 nginx: worker process
   33 101       0:00 nginx: worker process
   34 101       0:00 nginx: worker process
   35 101       0:00 nginx: worker process
   36 101       0:00 nginx: worker process
   37 101       0:00 nginx: worker process
   38 101       0:00 nginx: worker process
   39 101       0:00 nginx: worker process
   40 101       0:00 nginx: worker process
  217 root      0:00 zsh
  272 root      0:00 ps -ef