Skip to content
Chapter 2Kubernetes1.3x

A local cluster and kubectl

Get a real Kubernetes cluster running locally in under five minutes, install kubectl, and set up the two tools that make working with it bearable.

2 min read

You do not need a cloud account to learn Kubernetes. A local cluster behaves the same way for everything in this guide.

Install kubectl

brew install kubectl                              # macOS
sudo snap install kubectl --classic               # Ubuntu
choco install kubernetes-cli                      # Windows
kubectl version --client

This guide targets Kubernetes 1.3x. kubectl should be within one minor version of your cluster.

Pick a local cluster

Three reasonable options.

kind — runs Kubernetes nodes as Docker containers. Fast, disposable, closest to a real multi-node cluster. This guide uses it.

brew install kind

minikube — a VM or container based cluster with a large addon ecosystem.

brew install minikube && minikube start

Docker Desktop — enable Kubernetes in Settings. Simplest, single node, less configurable.

Create a cluster with kind

A single node works, but a multi-node cluster lets you see scheduling behave realistically. kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    kubeadmConfigPatches:
      - |
        kind: InitConfiguration
        nodeRegistration:
          kubeletExtraArgs:
            node-labels: "ingress-ready=true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        protocol: TCP
      - containerPort: 443
        hostPort: 443
        protocol: TCP
  - role: worker
  - role: worker
kind create cluster --name learn --config kind-config.yaml

The extraPortMappings matter: they let an Ingress on the cluster be reachable at localhost:80, which we use in chapter four.

Verify

kubectl cluster-info
kubectl get nodes
NAME                  STATUS   ROLES           AGE   VERSION
learn-control-plane   Ready    control-plane   45s   v1.31.0
learn-worker          Ready    <none>          30s   v1.31.0
learn-worker2         Ready    <none>          30s   v1.31.0
kubectl get pods -A

Everything in kube-system should be Running. If CoreDNS is stuck in Pending, the cluster is still starting — give it a minute.

Understand your kubeconfig

kubectl reads ~/.kube/config, which holds clusters, users, and contexts pairing them.

kubectl config get-contexts
kubectl config current-context
kubectl config use-context kind-learn

The two tools that make this bearable

kubectx and kubens — switch context and namespace without the long commands:

brew install kubectx

kubectx                  # list contexts, pick one
kubectx kind-learn
kubens kube-system       # set the default namespace

kube-ps1 — put the current context in your shell prompt:

brew install kube-ps1
# ~/.zshrc
source /opt/homebrew/share/kube-ps1/kube-ps1.sh
PROMPT='$(kube_ps1)'$PROMPT

Your prompt now reads (⎈|kind-learn:default). That line prevents the incident above.

Useful extras

brew install k9s        # terminal UI for the cluster — genuinely excellent
brew install stern      # tail logs from many pods at once
brew install helm       # the package manager, needed later

k9s in particular: run it once and you will use it daily. It turns “which pod is failing and why” from four commands into a keystroke.

Clean up

kind delete cluster --name learn

Recreating takes a minute, so feel free to destroy and rebuild while learning.

Next: the objects the whole system is made of.