Skip to main content

Run a local Kubernetes Cluster

You can install the ngrok Kubernetes operator in a locally running Kubernetes cluster rather than paying for one from a cloud provider.

This is useful for:

  • Quickly getting started trying out the ngrok Operator
  • Local development & testing
  • Connecting containerized workloads on your local machine to your ngrok infrastructure
  • Faster iteration cycles without cloud latency

Running Kubernetes inside containers has the benefits of being quick and simple to setup compared to a bare-metal installation and keeps the Kubernetes environment more isolated from the dependencies and other applications on your computer. This is not a recommendation for how you should productionize your Kubernetes setup, but rather a guide on getting an easy to use local environment setup for development and testing. The following sections outline various options for running Kubernetes inside Docker containers on your local machine, but you can run the ngrok Kubernetes operator in any Kubernetes cluster you like.

Choosing a Container Runtime​

Before setting up a local Kubernetes cluster, you need a container runtime. The container runtime is responsible for running containers, managing their lifecycle, and handling networking. If you don't already have a container runtime such as Docker installed, choose one from the options below.

RuntimeOS SupportArchitecture SupportDescription
Docker EngineLinux, ⚠️ Windows (WSL2 required)x86_64, ARM64Standard CLI-based runtime. Great for users who need a lightweight container runtime without a GUI.
Docker DesktopLinux, macOS, Windowsx86_64, ARM64 (Apple Silicon)GUI-based runtime. Great for developers who want an easy-to-use experience with a dashboard.
ContainerdLinux, Windowsx86_64, ARM64, s390x, ppc64leMinimalist, Kubernetes-native runtime. Great for Kubernetes users who need a lightweight runtime without Docker dependencies.
ColimaLinux, macOSx86_64, ARM64 (Apple Silicon)macOS-native alternative to Docker Desktop. Great for Mac users looking for a lightweight and fast Docker-compatible runtime.

Choosing a Cluster Provider​

Select one of the following options for running Kubernetes inside containers on your local machine.

ProviderBenefitsThings to consider
k3dLightweight (runs on K3s), fast cluster creation, low memory/CPU usageHeavily focused on local development, making it more feature-limited
MinikubeOfficial Kubernetes project, easy to use, supports multiple driversCompared to others may be slower and consume more CPU/memory
kindMulti-node clusters in Docker, great for testing, CI/CDFocused on testing, other options may be better for local development
Microk8sLightweight, full Kubernetes experience, easy to installConfig not automatically added to Kubeconfig, requires manual addition
Docker DesktopSimple interface, Kubernetes supportGUI-based, may be slower than other options

Basic commands​

Create a k3d cluster​

Loading…

When creating a k3d cluster, the config is automatically added to your Kubeconfig file so you are ready to go immediately.

List running clusters​

Loading…

Delete a k3d cluster​

Loading…

Managing Kubernetes Contexts​

When working with multiple Kubernetes clusters (e.g., Minikube, k3d, kind, MicroK8s, cloud clusters), it is important to manage kubeconfig contexts efficiently. A context in Kubernetes determines:

  • Which cluster kubectl is communicating with.
  • Which user credentials to use for authentication.
  • Which namespace is the default for commands.

Kubernetes stores this information in the kubeconfig file (default location: ~/.kube/config). The $KUBECONFIG environment variable is used by kubectl to know where your configuraiton file is. If you would like to store it somewhere else, or use different files for different clusters, you can modify the $KUBECONFIG variable.

Viewing the Current Context​

To check which Kubernetes cluster you are currently using:

Loading…

This returns the active context, which tells kubectl which cluster and credentials are being used.

Listing All Contexts​

To see all available Kubernetes contexts in your kubeconfig:

Loading…

This will display a list of available contexts, including:

  • Cluster Name (e.g., minikube, kind-my-cluster, k3d-my-cluster).
  • User Credentials.
  • Current Context (marked with *).

Switching Between Contexts​

To switch from one Kubernetes cluster to another:

Loading…

Setting a Default Namespace for a Context​

By default, kubectl uses the default namespace. You can change the default namespace for a specific context:

Loading…

Or, specify a namespace when switching to a different context:

Loading…

Deleting a Context​

If you no longer need a specific context, you can remove it from your kubeconfig:

Loading…

This does not delete the cluster itself, only its entry from your kubeconfig.

Merging Multiple Kubeconfig Files​

If you have multiple kubeconfig files (e.g., from cloud providers and local clusters), you can merge them:

Loading…

This consolidates multiple different cluster credentials into a single kubeconfig file.