Kong Run

Running Kong Locally Without the Kubernetes Headache

I spent last week trying to get a proper local dev environment set up for a client's Kong gateway project. Standard Kubernetes is overkill when you just want to iterate on routes and plugins. Kong Run solved that problem, but it comes with its own set of quirks worth knowing about before you waste a day fighting it. Kong Run is essentially a lightweight wrapper around a local Kubernetes cluster, designed specifically for working with Kong Gateway during development. Instead of spinning up Minikube, Kind, or k3s manually every time you want to test a configuration change, Kong Run does it all in one command. It provisions the cluster, deploys the Kong container with the right image tag, and exposes the necessary ports so your dev server can talk to it like it's talking to a real gateway. The whole thing usually comes up in about 30 to 45 seconds depending on your machine and Docker image pull speed. The core use case is pretty narrow and that is exactly why it exists. You are building a Kong plugin, you are writing Declarative Config files, or you need to smoke-test a route before pushing to staging. It is not meant for anything production-adjacent. I have seen people try to use it for load testing, and that is a mistake you only make once.

How to Install and Use It

The installation is straightforward if you already have Node.js and npm on your machine. Run the typical install command, verify the binary shows up with a version check, and you are ready to go. Make sure your Docker daemon is running first because Kong Run depends on it entirely. If Docker is not active, the command fails silently for a few seconds before spitting out an error that makes it look like the CLI itself is broken. I fell for that trap once, wasted about twenty minutes before I remembered to check whether Docker Desktop was actually running in the background. Once installed, the basic workflow looks like this. You run the start command from your project root, it builds or pulls the Kong image, spins up a single-node cluster, and prints out the access URLs. It usually gives you the admin port and the proxy port within the output. From there you can point your app at the local admin API, deploy a Konfigure file, and start adding routes and services. The config can be loaded via the declarative config endpoint or you can use the admin API directly to make changes.

Kong Run Troubleshooting Real Problems

Here is a specific issue I ran into that is not documented anywhere obvious. If you run Kong Run on a machine with an existing Docker network conflict, specifically a network named something like kong-run-net or a residual container from a previous failed attempt, the tool will hang indefinitely during startup. It does not clean up orphaned containers properly between runs. I discovered this when my environment would not come back up after a system reboot. The workaround was to run a docker volume prune and docker network prune before starting Kong Run again. After that, it came up cleanly every time. Another edge case involves resource limits. On machines with less than 4GB of RAM allocated to Docker, Kong tends to crash under even light load because the default resource settings inside the container are generous. I had to adjust the Docker daemon's memory allocation to at least 8GB total before Kong became stable enough to run any meaningful tests. Without that, you get opaque OOM kills that give you no helpful error message.

Common Pitfalls and Counter-Intuitive Things

One thing beginners miss is that Kong Run does not persist your configuration between restarts. Every time the cluster tears down, everything in the database is gone unless you have mounted a persistent volume. This is by design, but I have seen multiple developers lose hours of work because they assumed their routes would survive a machine restart. The fix is to mount a simple bind mount or a named volume into the Kong container for both the database and the declarative config file. A single volume flag in your startup command handles this, and it prevents data loss entirely. A second counter-intuitive behavior is that Kong Run defaults to a specific Kong image version, and updating the CLI does not always update the image. If you upgrade Kong Run to a newer version but your local Kong image stays pinned to an older tag, you can end up with a mismatch between the CLI's expected behavior and what the gateway is actually doing. I learned this the hard way when a plugin I was developing suddenly started throwing schema validation errors after an update. The solution is to explicitly declare the Kong image tag in your configuration rather than letting Kong Run pick the default. It takes five extra seconds and saves you from chasing phantom bugs.

When Kong Run Is Not the Right Tool

Kong Run has clear limitations. It only supports a single Kong node, so if your development workflow requires multi-node testing or database synchronization patterns, it will not cover that. It also relies heavily on Docker being available and healthy, which means Windows users sometimes run into WSL2 networking quirks that do not show up on macOS or Linux. The admin API is fully exposed by default, which is convenient but also means you should never leave Kong Run running on a network you do not trust. If you need something more production-realistic, consider using Kind or k3s instead. They take longer to set up and require more manual configuration, but they give you a cluster that actually behaves like what you would deploy. For quick iteration and plugin development though, Kong Run is hard to beat. It usually cuts the setup time from forty minutes of manual configuration down to about two minutes of waiting for images to pull. That trade-off is worth it for most local development workflows.

Kong Run and Plugin Development

If you are writing a custom Kong plugin, Kong Run gives you a practical sandbox where you can test against a real gateway without maintaining a separate test environment. Mount your plugin directory into the container, set the appropriate environment variables, and you can iterate on your code in near real-time. The feedback loop is fast enough that I would recommend it for any plugin developer who does not want to spin up a full staging cluster for every small change. The process itself is mostly about getting the volume mounts right and making sure your plugin code is rebuilt before each test run.