Install kubectl and Configure Context

You've written a Dockerfile, maybe even pushed an image, but the moment you need to actually talk to a Kubernetes cluster, you're staring at a blank terminal. The pain is universal: kubectl: command not found, or worse, you've installed it but every command returns connection refused or Forbidden. The gap between "I know Python" and "I can deploy" isn't the API — it's the tooling. This lesson closes that gap by showing you exactly how to install kubectl, configure your first context, and verify your connection — so the rest of your Kubernetes journey isn't a guessing game.

The problem this lesson solves

Kubernetes is controlled almost entirely through its REST API. Every pod, deployment, and service you'll ever touch is just an API object. But you won't be curling that API by hand — you'll use kubectl, the official command-line tool. Without it, you might as well be trying to drive a car without a steering wheel.

The problems you'll face right now are concrete:

• kubectl: command not found — the binary isn't installed or isn't on your $PATH.
• Errors like Unable to connect to the server: dial tcp ...: i/o timeout — you're trying to reach a cluster that isn't there.
• Forbidden or Unauthorized errors — your context is pointing at the wrong cluster or you're missing credentials.

If you're a Python developer, you might be tempted to use a library like kubernetes directly. But every production workflow — every CI/CD pipeline, every deployment guide, every incident response — assumes you know kubectl. It's the common language between you, your team, and the cluster.

Core concept / mental model

Think of kubectl as a universal remote control for Kubernetes. It doesn't contain your cluster's logic; it sends commands to the cluster's API server and displays the results.

At its heart, kubectl relies on two things:

1. The kubeconfig file (usually at ~/.kube/config) — a configuration file that stores everything kubectl needs to connect.
2. Contexts — named sets of connection parameters within that kubeconfig. A context wraps a cluster endpoint, a user credential, and a namespace together.

Here's a word-level diagram:

~/.kube/config
┌─────────────────────────────────────────────────────┐
│ contexts:                                            │
│   - name: dev                                       │
│     context:                                        │
│       cluster: kind-dev                              │
│       user: kind-dev                                 │
│       namespace: default                             │
│                                                     │
│ clusters:                                            │
│   - name: kind-dev                                   │
│     cluster:                                        │
│       server: https://127.0.0.1:xxxxx               │
│                                                     │
│ users:                                               │
│   - name: kind-dev                                   │
│     user:                                            │
│       token: ...                                     │
└─────────────────────────────────────────────────────┘

When you run kubectl get pods, kubectl reads the current context to decide which cluster to talk to, which credentials to present, and which namespace to use by default. That's it. Everything else is just details.

This might feel abstract if you're used to pip install — but stick with me. By the end of this lesson, you'll have a working local cluster, a configured context, and you'll understand exactly how kubectl makes that connection.

How it works step by step

Let's break the setup process into four logical steps:

1. Install kubectl — get the binary onto your machine.
2. Install a local cluster (like kind or minikube) — you need a real API server to talk to.
3. Configure the context — point kubectl at that cluster.
4. Verify — run a command that proves the connection works.

Why a local cluster first?

You could point kubectl at a cloud cluster, but that costs money and adds latency. For learning, a local cluster like kind (Kubernetes in Docker) or minikube is perfect. It spins up in minutes, and it's free.

• kind runs Kubernetes nodes as containers inside Docker. Lightweight, fast, great for testing.
• minikube creates a full VM. Heavier but closer to a real environment.

For this lesson, I'll use kind because it's faster and doesn't require a hypervisor.

Understanding contexts

A context is a trio of settings: cluster, user, and namespace. You can have many contexts in your kubeconfig — one for each environment (dev, staging, prod). The kubectl config command family manages them.

Key commands:

• kubectl config get-contexts — list all contexts
• kubectl config current-context — show the active one
• kubectl config use-context <name> — switch between them

Switching contexts is like switching between remote controls — the same kubectl binary suddenly starts talking to a different cluster.

Hands-on walkthrough

Now let's install kubectl and configure your first context. I'll use macOS (with Homebrew) for the commands, but I'll include alternatives.

Step 1: Install kubectl

macOS (Homebrew):

brew install kubectl

Linux (using the official Google repository):

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

Windows (PowerShell):

winget install Kubernetes.kubectl

Verify the install:

kubectl version --client

You should see something like:

Client Version: v1.28.3
Kustomize Version: v5.0.1

This output means the binary is installed. It doesn't need a server yet.

Step 2: Create a local cluster with kind

Install kind:

brew install kind

Now create a cluster:

kind create cluster --name python-dev

You'll see output like:

Creating cluster "python-dev" ...
 ✓ Ensuring node image (kindest/node:v1.28.0) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-python-dev"

That last line is key — kind has already configured a new context for you.

Pro tip: kind automatically writes a new context named kind-<cluster-name> into your kubeconfig. That's your first context, configured for you.

Step 3: Verify the context

Check which context is active:

kubectl config current-context

Expected output:

kind-python-dev

List all contexts:

kubectl config get-contexts

You'll see something like:

CURRENT   NAME            CLUSTER         AUTHINFO        NAMESPACE
*         kind-python-dev kind-python-dev kind-python-dev

The * marks the current context. Notice the NAMESPACE column is empty, which means it falls back to default.

Step 4: Test the connection

Run a command that actually talks to the cluster:

kubectl get nodes

Expected output:

NAME                       STATUS   ROLES           AGE     VERSION
python-dev-control-plane   Ready    control-plane   2m34s   v1.28.0

If you see your node with status Ready, your kubectl is installed, your context is configured, and your connection works.

Step 5: Set a default namespace (optional)

If you want to always work in a specific namespace, you can set it at the context level:

kubectl config set-context --current --namespace=dev

Now every command will default to the dev namespace (which you'd need to create first).

Compare options / when to choose what

Let's compare the most common ways to get a local cluster:

For this track, I recommend kind because it's fast, simple, and works everywhere Docker does. Once you're comfortable, you can try minikube if you need a more cluster-like experience.

Also, note the difference between contexts and clusters:

• A cluster is a collection of nodes running Kubernetes.
• A context is just a pointer to a cluster with credentials and a namespace.

You can have many contexts pointing to the same cluster (e.g., different users or namespaces).

Troubleshooting & edge cases

Here are the most common errors you'll hit and how to resolve them:

• Unable to connect to the server: dial tcp 127.0.0.1:xxxxx: connect: connection refused

• This means kind isn't running. Start it with kind start --name python-dev (or recreate with kind create cluster).

• The connection to the server ... was refused - did you specify the right host or port?

• Same as above, but often you haven't created the cluster at all. Double-check with kubectl config get-contexts — if no context is listed, create the cluster.

• error: You must be logged in to the server (Unauthorized)

• Your kubeconfig has stale or wrong credentials. Usually happens when you switch between clusters. Run kubectl config view to inspect, and if needed, delete and recreate the context.

• kubectl: command not found — the binary isn't in your $PATH. Ensure you're using the package manager's path, or install via the official binary.

• context was not found — you're trying to switch to a context that doesn't exist. Use kubectl config get-contexts to see valid names.

Pro tip: Have multiple clusters? Use kubectl config use-context kind-python-dev to switch back. Never guess which context is active — check it with kubectl config current-context.

What you learned & what's next

You've just installed kubectl, created a local Kubernetes cluster with kind, and configured your first context. You can now:

• Explain what a kubeconfig and a context are.
• Run kubectl get nodes to see your cluster.
• Switch between contexts and check the current one.

This is the foundation for everything else. In the next lesson, you'll use this setup to deploy your first Python application as a Pod, then as a Deployment. You'll see how kubectl's power really shines when you start manipulating API objects.

But before moving on, make sure you can answer this question: what does kubectl actually talk to when you run a command? If you said "the API server," you're ready. Now go create that cluster and run kubectl get nodes. Your Kubernetes journey has officially begun.