Skip to main content

Setting Up Your Lab (Local Cluster)

Key Takeaways for AI & Readers
  • Local Learning Labs: Tools like Kind, Minikube, and K3d allow you to run full Kubernetes clusters locally without cloud costs.
  • Kind (Recommended): Best for speed, multi-node simulations, and CI/CD pipelines. Uses Docker containers as nodes.
  • Minikube: Best for beginners who want a GUI dashboard and easy addon management.
  • K3d: Best for lightweight, ultra-fast clusters using the K3s distribution.
  • kubectl CLI: The primary tool for interacting with any Kubernetes cluster, configured via ~/.kube/config.
  • Prerequisites: Docker Desktop (or Podman) must be installed and running before using any of these tools.

You don't need a cloud account (AWS, GCP, or Azure) to learn Kubernetes. You can run a production-grade cluster directly on your laptop using containers or virtual machines. This page guides you through setting up a local cluster, installing kubectl, and configuring essential productivity tools.

Prerequisites​

Before installing any local Kubernetes tool, ensure you have:

  1. Docker Desktop (macOS/Windows) or Docker Engine (Linux) installed and running
    • Allocate at least 4 GB RAM and 2 CPUs to Docker (check Docker Desktop → Settings → Resources)
    • Alternatively, Podman works with Kind and K3d on Linux
  2. A terminal — bash, zsh, PowerShell, or Windows Terminal
  3. Sufficient disk space — at least 10 GB free for images and cluster data

Choose Your Tool​

Each tool has strengths. Choose based on your needs:

FeatureKindMinikubeK3d
SpeedFast (seconds)Moderate (minutes)Fastest (seconds)
Multi-nodeYes (via config file)Limited (experimental)Yes (via flags)
Resource usageLow (Docker containers)Higher (VM or Docker)Lowest (K3s is minimal)
DashboardNo built-inYes (minikube dashboard)No built-in
AddonsManualBuilt-in (minikube addons)Manual
CI/CD friendlyExcellentModerateExcellent
LoadBalancerRequires MetalLBBuilt-in (minikube tunnel)Built-in (via host mapping)
Kubernetes versionFull upstreamFull upstreamK3s (certified, lightweight)

Kubernetes in Docker (Kind)​

Kind runs Kubernetes clusters using Docker container "nodes." Each node is a Docker container running containerd and the Kubernetes components. It was originally designed for testing Kubernetes itself and is widely used in CI/CD pipelines.

Why use it?

  • Fast: Clusters spin up in under 30 seconds
  • Multi-Node: Easily simulate 1 control-plane + N worker node clusters
  • Lightweight: Uses Docker containers, not resource-heavy VMs
  • Identical to upstream: Runs the exact same Kubernetes as production clusters

Installation​

# macOS
brew install kind

# Windows
choco install kind

# Linux (download binary)
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.25.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

Basic Usage​

# Create a single-node cluster
kind create cluster --name k8s-playground

# Verify it's running
kubectl cluster-info --context kind-k8s-playground

# List clusters
kind get clusters

# Delete the cluster when done
kind delete cluster --name k8s-playground

Multi-Node Configuration​

For a more realistic setup, create a config file to simulate a production-like topology:

# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
- role: worker
kind create cluster --name multi-node --config kind-config.yaml
kubectl get nodes
# NAME                       STATUS   ROLES           AGE   VERSION
# multi-node-control-plane   Ready    control-plane   45s   v1.31.0
# multi-node-worker          Ready    <none>          30s   v1.31.0
# multi-node-worker2         Ready    <none>          30s   v1.31.0
# multi-node-worker3         Ready    <none>          30s   v1.31.0

Loading Local Images​

Kind clusters cannot pull images from your local Docker daemon by default. Use kind load to make local images available:

docker build -t my-app:dev .
kind load docker-image my-app:dev --name k8s-playground

Port Mapping (Accessing Services)​

To access services from your host machine, configure port mappings in the Kind config:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30000
    hostPort: 30000
    protocol: TCP

Installing kubectl​

kubectl is the command-line tool for communicating with the Kubernetes API Server. It is required regardless of which local cluster tool you choose.

Installation​

# macOS
brew install kubectl

# Linux (snap)
sudo snap install kubectl --classic

# Linux (binary)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Windows
choco install kubernetes-cli

Configuration​

kubectl reads its configuration from ~/.kube/config (the kubeconfig file). This file contains:

  • Clusters: API Server addresses and CA certificates
  • Users: Authentication credentials (tokens, certificates, exec-based auth)
  • Contexts: A mapping of cluster + user + namespace
# View your current context
kubectl config current-context

# List all available contexts
kubectl config get-contexts

# Switch to a different context
kubectl config use-context kind-k8s-playground

When you create a cluster with Kind, Minikube, or K3d, the tool automatically updates your kubeconfig.

Verify the Connection​

kubectl cluster-info
kubectl get nodes
kubectl get namespaces

Essential Productivity Tools​

Shell Aliases​

Save typing by setting up aliases. Add these to your ~/.bashrc or ~/.zshrc:

alias k='kubectl'
alias kgp='kubectl get pods'
alias kgs='kubectl get services'
alias kgd='kubectl get deployments'
alias kga='kubectl get all'
alias kdp='kubectl describe pod'
alias kl='kubectl logs'
alias kaf='kubectl apply -f'

kubectx + kubens​

Switch between clusters and namespaces without typing long commands:

# Install
brew install kubectx    # Includes both kubectx and kubens

# Switch cluster context
kubectx kind-k8s-playground

# Switch default namespace
kubens kube-system

k9s — Terminal UI​

k9s is a terminal-based UI for managing Kubernetes clusters. It provides a real-time dashboard for Pods, Services, Deployments, and more.

brew install derailed/k9s/k9s
k9s  # Launch the UI

Autocompletion​

Enable kubectl tab-completion for your shell:

# Bash
echo 'source <(kubectl completion bash)' >> ~/.bashrc

# Zsh
echo 'source <(kubectl completion zsh)' >> ~/.zshrc

# If using the alias 'k'
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc

Troubleshooting Common Setup Issues​

ProblemCauseSolution
Cannot connect to the Docker daemonDocker is not runningStart Docker Desktop or systemctl start docker
Insufficient memoryDocker has < 2GB allocatedIncrease memory in Docker Desktop settings
kubectl: connection refusedWrong context or cluster not runningRun kubectl config current-context and verify cluster is up
ImagePullBackOff on local imagesCluster cannot see local Docker imagesUse kind load, minikube docker-env, or k3d image import
Cluster creation hangsDocker network issues or antivirus interferenceRestart Docker, check firewall rules

What's Next?​

With your local cluster running, proceed to: