Install kubectl & a Local Cluster

You do not need a cloud account to learn Kubernetes. A complete cluster can run on your laptop inside Docker containers, and it behaves like a real one for almost everything in this course.

In this lesson you will install kubectl, the command-line tool for Kubernetes, create a three-node cluster with kind, check that it works, and learn how kubectl knows which cluster to talk to. You will also see the alternatives: minikube, k3d and the cluster built into Docker Desktop.

What you need

• Docker Desktop (Windows or macOS) or Docker Engine (Linux), set up as in Install Docker Desktop & Docker Engine. kind, k3d and usually minikube run their nodes as containers.
• At least 8 GB of RAM in your laptop, with 4 GB or more given to Docker (Docker Desktop: Settings > Resources).
• A terminal. Commands in this course are written for a Bash-style shell (Linux, macOS, WSL or Git Bash); most also work in PowerShell.

Step 1: install kubectl

kubectl (say "cube control" or "cube C T L") talks to a cluster's API server. Install it with your system's package manager:

# Windows (PowerShell or Git Bash)
winget install -e --id Kubernetes.kubectl

# macOS
brew install kubectl

# Linux (x86-64): download the latest stable release and install it
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Check it with kubectl version --client. The version skew rule says kubectl must be within one minor version of the cluster: a 1.37 client works with 1.36, 1.37 and 1.38 clusters.

Step 2: choose a local cluster

All four give you real Kubernetes, so pick one. This course uses kind in its examples, because a multi-node cluster makes scheduling and DaemonSets easy to see.

Step 3: create a three-node cluster with kind

Install kind (version 0.33.0 at the time of writing):

# Windows
winget install Kubernetes.kind

# macOS
brew install kind

# Any system with Go installed
go install sigs.k8s.io/kind@v0.33.0

A plain kind create cluster makes a one-node cluster. To get one control-plane node and two workers, save this configuration as kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30080
        hostPort: 30080
  - role: worker
  - role: worker

The extraPortMappings entry forwards port 30080 on your laptop into the cluster. You will use it in the Services lesson to open an app in your browser. Now create the cluster:

kind create cluster --config kind-config.yaml

kind downloads a node image the first time (this can take a few minutes), starts three containers, installs a network plug-in and a storage provisioner, and finally prints Set kubectl context to "kind-kind". The cluster is called kind, and the context that points kubectl at it is called kind-kind.

Step 4: check the cluster

kubectl cluster-info
kubectl get nodes
kubectl version

Kubernetes control plane is running at https://127.0.0.1:41853
CoreDNS is running at https://127.0.0.1:41853/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
NAME                 STATUS   ROLES           AGE     VERSION
kind-control-plane   Ready    control-plane   2m15s   v1.37.0
kind-worker          Ready    <none>          2m1s    v1.37.0
kind-worker2         Ready    <none>          2m1s    v1.37.0
Client Version: v1.37.1
Kustomize Version: v5.8.1
Server Version: v1.37.0

All three nodes are Ready. The API server port (41853 here) is chosen at random, so yours will differ. The client is a newer patch release than the server, which is perfectly fine. kubectl also contains Kustomize, a tool you will meet in Kustomize: Bases & Overlays.

kubeconfig and contexts

How did kubectl know where the cluster is? kind wrote the details into your kubeconfig file, ~/.kube/config (on Windows, C:\Users\<you>\.kube\config). A kubeconfig holds three lists:

• clusters: API server addresses and their certificates.
• users: credentials, such as a client certificate or a token.
• contexts: a named pair of one cluster and one user, plus an optional default namespace.

The current context decides where every kubectl command goes. This matters as soon as you have more than one cluster:

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

CURRENT   NAME             CLUSTER          AUTHINFO         NAMESPACE
          docker-desktop   docker-desktop   docker-desktop
*         kind-kind        kind-kind        kind-kind
Switched to context "kind-kind".

The star marks the current context. Treat your kubeconfig like a password file: anyone who copies it can control your clusters.

The alternatives in brief

# minikube: one node, or several with --nodes
minikube start --nodes 3
minikube addons enable metrics-server
minikube dashboard

# k3d: one server plus two agent (worker) nodes
k3d cluster create dev --agents 2

minikube names its context minikube, and minikube tunnel gives LoadBalancer Services a reachable address. k3d switches your context to the new cluster automatically.

In Docker Desktop, open the Kubernetes view and choose Create cluster. You can pick kubeadm (one node, quick to start) or kind (several nodes and a choice of Kubernetes version; it needs the containerd image store). The context is called docker-desktop.

Cleaning up

Local clusters use memory even when idle. Stop or delete them when you finish:

kind delete cluster
minikube stop
k3d cluster delete dev

Deleting a kind cluster removes every object in it, so keep your manifests in files (and in Git), never only in the cluster.

Common mistakes

• "The connection to the server localhost:8080 was refused". kubectl found no kubeconfig context. Create a cluster first, or check kubectl config get-contexts.
• Running commands against the wrong cluster. Always know your current context, especially once you also have a work or cloud cluster.
• Giving Docker too little memory. Nodes go NotReady or Pods stay Pending. Raise Docker's memory limit.
• Expecting images on your laptop to be inside kind. kind nodes have their own image store. Push to a registry or use kind load docker-image my-app:1.0.

Key points

• kubectl is the command-line client; keep it within one minor version of your cluster.
• kind, minikube, k3d and Docker Desktop all run real Kubernetes locally; this course uses a three-node kind cluster.
• A kind cluster is described by a small YAML file and created with kind create cluster --config.
• The kubeconfig file stores clusters, users and contexts; the current context decides where commands go.
• Check a new cluster with kubectl cluster-info, kubectl get nodes and kubectl version.

# practice.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker

kind create cluster --name practice --config practice.yaml
kubectl config get-contexts
kubectl config use-context kind-kind
kind delete cluster --name practice