k3d¶

Purpose¶

Create and manage the local Kubernetes cluster that stands in for real staging/production while developing infrastructure changes.

Prerequisites¶

Docker Desktop running, k3d on PATH (see Local → Prerequisites).

Configuration¶

Cluster name: akshaya-staging
kubectl context: k3d-akshaya-staging
Load balancer ports: 80 -> 80, 443 -> 443 (must be explicit at creation time)

Commands¶

Create the cluster¶

k3d cluster create akshaya-staging `
  --api-port 6550 `
  -p "80:80@loadbalancer" `
  -p "443:443@loadbalancer" `
  --agents 1

List / status¶

k3d cluster list
kubectl config get-contexts
kubectl --context k3d-akshaya-staging get nodes

Stop / start (keeps cluster state, releases Docker resources)¶

k3d cluster stop akshaya-staging
k3d cluster start akshaya-staging

Delete (destructive - see below)¶

k3d cluster delete akshaya-staging

Adding a missing port mapping without recreating the cluster¶

If the cluster already exists but the load balancer only maps to a non-standard port (a common k3d default when -p 80:80@loadbalancer wasn't specified at creation), k3d cluster edit adds a mapping to an existing cluster - it only recreates the stateless load-balancer container, not the server/agent nodes, so no pod or PVC data is touched:

docker port k3d-akshaya-staging-serverlb    # check current mapping first
k3d cluster edit akshaya-staging --port-add "80:80@loadbalancer"
docker port k3d-akshaya-staging-serverlb    # confirm

This was validated live: the serverlb container was recreated in seconds while server-0/ agent-0 showed unbroken uptime throughout, and the existing Helm release, MySQL/Redis pods, and data were completely unaffected.

Validation¶

kubectl --context k3d-akshaya-staging cluster-info

Expected result¶

A reachable API server, Ready nodes, and (once deployed) Traefik running in kube-system:

kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik

Troubleshooting¶

See Kubernetes → Troubleshooting and Local → Troubleshooting.

Rollback / recovery¶

k3d cluster edit is low-risk (see above). k3d cluster delete is destructive - it deletes every pod, PVC, and locally-stored MySQL/Redis data with it. Never run this without confirming first that any data you care about is either disposable or backed up elsewhere - this local cluster has no automated backup of its own (unlike the real staging/production data VMs - see Operations → Backup).

Security considerations¶

The local cluster is reachable only via 127.0.0.1 (Docker Desktop's own networking) - it is never exposed beyond your own machine, and holds no production data, credentials, or Cloudflare/ DNS configuration of any kind.