🧰 KoolKits 🧰

Opinionated, language-specific, batteries-included debug container images for Kubernetes.

Available for:

KoolKits (Kubernetes toolkits) are language-specific container images that contain a (highly-opinionated) set of tools for debugging applications running in Kubernetes pods. You can read more about the motivation behind this project here.

Prefer video to reading? We have you covered:

Those images are intended for use with the new kubectl debug feature, which spins up Ephemeral containers for interactive troubleshooting. A KoolKit will be pulled by kubectl debug, spun up as a container in your pod, and have the ability to access the same process namespace as your original container.

Since production containers are usually rather bare, using a KoolKit enables you to troubleshoot with power tools instead of relying on what was left behind due to the generosity (or carelessness) of whoever originally built the production image.

🏁 Quickstart 🏁

Run a Node.js KoolKit in your production cluster (Kubernetes v1.23 and above):

kubectl debug -it <POD-NAME> --image=lightrun-platform/koolkits/koolkit-node --image-pull-policy=Never --target=<DEPLOYMENT-NAME>

Run a JVM KoolKit in MiniKube (Kubernetes v1.23 and above):

minikube kubectl -- debug -it <POD-NAME> --image=lightrun-platform/koolkits/koolkit-jvm --image-pull-policy=Never --target=<DEPLOYMENT-NAME>

Adding to .bashrc/.zshrc

You can use KoolKits faster by adding the following function to your .bashrc:

echo "## KoolKits - Shorthand
kk() {
	kubectl debug -it $1 --image=lightruncom/koolkits:$2 --image-pull-policy=Never --target=$3
}" >> ~/.bashrc
source ~/.bashrc

Or into your .zshrc:

echo "## KoolKits - Shorthand
kk() { 
	kubectl debug -it $1 --image=lightruncom/koolkits:$2 --image-pull-policy=Never --target=$3
}" >> ~/.zshrc
source ~/.zshrc

Then run kk:

kk demo-123123-qweqwe2 jvm demo

Where the full syntax is:

kk <POD-NAME> <LANGUAGE> <DEPLOYMENT-NAME>

👇 Available KoolKits 👇

Each of the folders in this repo contains the Dockerfile - and a short explanation of - the debug image. All KoolKits are based on the ubuntu:20.04 base image, since real people need real shells.

The list:

1. koolkit-jvm - AdoptOpenJDK 17.0.2 & related tooling (including jabba for easy version management and Maven 3.8.4)
2. koolkit-node - Node 16.13.1 & related tooling (including nvm for easy version management)
3. koolkit-python - Python 3.10.2 & related tooling (including pyenv for easy version management)
4. koolkit-golang - Go 1.17.6 & related tooling (including gvm for easy version management)

Note that you don't actually have to build them yourselves - all KoolKits are hosted publicly on Docker Hub and available free of charge.

Got a suggestion for improvements? We'd be happy to hear all about it - just open an issue with the requested tooling.

🚧 Coming up / WIP 🚧

• A whole new, Go 1.17.7 KoolKit (released on March 2022)
• JVM KoolKit - jvm-profiler, jHiccup support
• Node.js KoolKit - llnode, thetool support
• Python KoolKit - vardbg, memprof support

🏃 Motivation 🏃

There's a well-known Kubernetes best practice that states that one should build small container images. This makes sense for a few different reasons:

1. Building the image will consume less resources (aka CI hours)
2. Pulling the image will take less time (who wants to pay for so much ingress anyways?)
3. Less stuff means less surface area exposed to security vulnerabilities, in a world where even no-op logging isn't safe anymore

There's also a lot of tooling in existence that helps you get there without doing too much heavy lifting:

1. Alpine Linux base images are super small
2. DistroLess Docker images go a step further and remove everything but the runtime
3. Docker multi-stage builds help create thin final production images

The problem starts when you're trying to debug what's happening inside those containers. By using a small production image you're forsaking a large amount of tools that are invaluable when wrapping your head around a problem in your application.

By using a KoolKit, you're allowing yourself the benefits of a small production image without compromising on quality tools - each KoolKit contains hand-picked tools for the specific runtime it represents, in addition to a more generic set of tooling for Linux-based systems.

P.S. KoolKits was inspired by kubespy and netshoot.

🗯️ Considerations 🗯️

Size of Images

KoolKits Docker images tend to run, uhm, rather large.

KoolKits are intended to be downloaded once, kept in the cluster's Docker registry, and then spun up immediately on demand as containers. Since they're not intended for constant pulling, and since they're intended to be packed with goodies, this is a side effect we're willing to endure.

Using Ubuntu base images

Part of the reason it's hard to create a really slim image is due to our decision to go with a full Ubuntu 20.04 system as the basis for each KoolKit. This mainly came from our desire to replicate the same environment you would debug with locally inside your clusters.

For example, this means no messing around with Alpine alternatives to normal Ubuntu packages you're used to working with. Actually, this means we have a way of including tools that have no Alpine versions in each KoolKit.

Using language version managers

Each KoolKit uses (wherever possible) a language version manager instead of relying on language-specific distros. This is done to allow you to install older runtime versions easily, and in order to allow you to swap between runtime versions at will (for example, to get specific versions of tooling that only exist for specific runtime versions), as need be.

💗 Contribution 💗

We'd be more than happy to add tools we missed to any image - just open a pull request or an issue to suggest one.