Local Clusters and kubeconfig · Kubernetes · aiiolar

Handbooks / Kubernetes / Chapter 1

Local Clusters and kubeconfig

7 pages · ~5 min✓ Reviewed

Start here. Next up: Pods and Deployments.

KubernetesPage 1

Local Clusters and kubeconfig Mental Model

1. What a Local Cluster Is

Local tools run a real control plane on your laptop for dev and testing
kubectl just talks to whatever API server kubeconfig points at
Every tool writes a context on create: kind-<name>, minikube, k3d-<name>

2. kubeconfig Structure

Default file ~/.kube/config
Override: KUBECONFIG env var or --kubeconfig

List	Holds
clusters	server URL + CA
users	credentials
contexts	cluster + user + default namespace

current-contextused by every command
contextcluster + user + namespace
API serverkubectl talks here

KubernetesPage 2

kind vs minikube vs k3d

KubernetesPage 3

Contexts, Users and Switching Namespaces

KubernetesPage 4

kubectl explain and Dry-Run

KubernetesPage 5

Debugging with port-forward and exec

KubernetesPage 6

Cheat Sheet: Local Clusters, Contexts and Debugging

KubernetesPage 7

Check yourself

1. Pick a tool

	kind	minikube	k3d
Runs as	Kubernetes IN Docker, node = container	one VM or container; drivers docker, hyperkit, hyper-v, virtualbox	k3s (light Rancher distro) in Docker
Extras	multi-node and HA via YAML config; built for testing Kubernetes	`addons enable ingress`, metrics-server, dashboard; `--nodes N`	fastest, lowest memory; `registry create`; `-p 8080:80@loadbalancer`
Pick for	CI, multi-node tests	beginners, addons	fast, light, many clusters

2. Create and delete

bash

kind create cluster --name dev
kind delete cluster --name dev
minikube start -p dev
minikube delete -p dev
k3d cluster create dev --servers 1 --agents 2
k3d cluster delete dev

3. Local images

Cluster cannot see your local Docker images
Load the image first, else ErrImagePull

bash

kind load docker-image app:1 --name dev
minikube image load app:1
k3d image import app:1 -c dev

Mistake

ErrImagePull on a local tag means the image was never loaded.

1. Inspect and switch

current-context is the cluster kubectl uses now
view --minify shows only the active context
use-context switches; --context is a one-off override

bash

kubectl config get-contexts
kubectl config current-context
kubectl config view --minify
kubectl config use-context kind-dev
kubectl --context kind-dev get pods

2. Namespaces and users

Command	Scope
`set-context --current --namespace=staging`	saved on current context
`-n staging`	one command
`-A`	all namespaces

Users hold credentials: client cert/key, token, or exec plugin (aws eks get-token)
Two contexts can share one cluster with different users or namespaces

3. Wrong-context gotcha

use-context persists across terminals
kubectl delete in the wrong context hits prod

Stay safe

Check current-context first. Use --context explicitly in scripts. Or install kubectx/kubens: kubectx dev, kubens staging.

1. Find fields and kinds

kubectl explain pod.spec.containers reads the cluster's own API schema
Walk down with dots; --recursive prints the whole field tree
kubectl api-resources: kind, short name, API group, namespaced (po, svc, deploy, ns)

2. Dry-run modes

Flag	Runs	Checks
`--dry-run=client`	Locally	Render + validate, no server contact
`--dry-run=server`	API server	Full validation + admission, not persisted

3. YAML skeleton workflow

Generatedry-run -o yaml
Editweb.yaml
Diffkubectl diff
Applykubectl apply

bash

kubectl create deployment web --image=nginx \
  --dry-run=client -o yaml > web.yaml
kubectl diff -f web.yaml
kubectl apply -f web.yaml

diff shows what apply would change

Forgot -o yaml

Dry-run then prints only created (dry run) and no manifest.

1. port-forward

Tunnels localhost:LOCAL to container port REMOTE via the API server
Targets: pod/web-1, svc/web, deploy/web
Binds 127.0.0.1 only; pins to one pod
Dies on pod restart; blocks the terminal
--address 0.0.0.0 only deliberately

bash

kubectl port-forward pod/web-1 8080:80
kubectl port-forward svc/web 8080:80

LOCAL:REMOTE

2. exec and debug

Command	Does
`exec -it web-1 -- sh`	Shell; `--` splits kubectl flags from command
`exec web-1 -c app -- env`	`-c` picks the container
`exec web-1 -- cat /etc/resolv.conf`	One-shot command
`debug -it web-1 --image=busybox --target=web`	Distroless: no shell

3. Debug order

get pods
describe pod
logs--previous after crash
exec / port-forward

Got 'not found'?

You forgot -n namespace. Pass it on every command.

Port-forward to svc/web? Tunnel to one pod behind it, for debugging only
No shell in image? kubectl debug with a busybox image

1. Create and load

Tool	Create	Load image
kind	`kind create cluster --name dev`	`kind load docker-image app:1 --name dev`
minikube	`minikube start -p dev`	`minikube image load app:1`
k3d	`k3d cluster create dev`	`k3d image import app:1 -c dev`

Unloaded image

Local images are invisible to the cluster: ErrImagePull

2. Contexts and namespace

bash

kubectl config get-contexts
kubectl config use-context NAME
kubectl config current-context
kubectl config view --minify
kubectl config set-context --current --namespace=NS
kubectl get pods -n NS   # -A = all

3. Explain, dry-run, debug

bash

kubectl explain pod.spec --recursive
kubectl create deployment web --image=nginx --dry-run=client -o yaml > f.yaml
kubectl diff -f f.yaml

Need	Command
Tunnel	`kubectl port-forward svc/web 8080:80`
Shell	`kubectl exec -it POD -c CTR -- sh`
Crash logs	`kubectl logs --previous POD`

Dry-run without -o yaml prints no manifest
Forgot -n NS: resource not found
use-context persists across terminals