Getting Started

You need three things: a running cluster, the kubectl CLI, and a container image. We'll cover all three, then deploy a real app.

Get a Cluster

For learning, use a local cluster. For production, use a managed cluster.

Tool	Best for	Notes
kind	Local dev	Runs K8s in Docker; instant teardown
minikube	Local dev	VM-based; multi-node support
k3d	Local dev	Lightweight K3s in Docker
EKS / GKE / AKS	Production	Managed by AWS / Google / Azure
DigitalOcean / Linode	Small production	Cheaper managed K8s

Quickest local setup:

# Install kind
brew install kind                        # macOS
# Or: go install sigs.k8s.io/kind@latest

# Create a single-node cluster
kind create cluster --name dev

# Confirm
kubectl cluster-info --context kind-dev
kubectl get nodes

Install kubectl

# macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

# Verify
kubectl version --client

kubectl reads its cluster config from ~/.kube/config. Managed cluster providers give you a command to populate it (aws eks update-kubeconfig, gcloud container clusters get-credentials, ...).

Your First Deployment

Three minimum objects to run a web app: a Deployment (manages replicas), a Service (gives them a stable address), and optionally an Ingress (exposes them outside the cluster).

# app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: hello
          image: nginxdemos/hello:plain-text
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  selector:
    app: hello
  ports:
    - port: 80
      targetPort: 80

Apply it:

kubectl apply -f app.yaml

Inspect what happened:

kubectl get deployments
kubectl get pods
kubectl get services

# Watch the pods come up
kubectl get pods -w

A passing state looks like:

NAME                    READY   STATUS    RESTARTS   AGE
hello-7d9b6c5cf-2sxg6   1/1     Running   0          12s
hello-7d9b6c5cf-x7n5j   1/1     Running   0          12s

See It Running

For local clusters, port-forward to reach the service:

kubectl port-forward service/hello 8080:80
# In another terminal:
curl http://localhost:8080

The Core Loop

# Apply (create or update)
kubectl apply -f app.yaml

# Look
kubectl get pods,svc,deploy

# Describe a problem child
kubectl describe pod hello-xxx

# Look at logs
kubectl logs hello-xxx
kubectl logs -f hello-xxx              # follow

# Exec inside a container
kubectl exec -it hello-xxx -- sh

# Roll back
kubectl rollout undo deployment/hello

# Delete
kubectl delete -f app.yaml

Namespaces

Namespaces are virtual clusters inside a cluster. Use them to separate environments (staging / production), teams, or applications.

kubectl create namespace staging
kubectl apply -f app.yaml -n staging
kubectl get pods -n staging

# Set the default namespace for your context
kubectl config set-context --current --namespace=staging

A pod in staging reaches a service in the same namespace by service-name; across namespaces it's service-name.namespace.svc.cluster.local.

Useful kubectl Shortcuts

# Resource aliases
kubectl get po          # pods
kubectl get deploy      # deployments
kubectl get svc         # services
kubectl get ns          # namespaces

# Multiple resources at once
kubectl get pod,svc,deploy

# Output formats
kubectl get pod hello-xxx -o yaml
kubectl get pod hello-xxx -o json
kubectl get pods -o wide                  # extra columns (node, IP)

# Filter by label
kubectl get pods -l app=hello

# Across all namespaces
kubectl get pods --all-namespaces

# Watch
kubectl get pods -w

What's Next

You can run a basic web app. Next, learn the rest of the workload types — for stateful services, batch jobs, scheduled tasks, and per-node agents → Workloads.

Getting Started

On this page