Kubernetes Fundamentals

Overview

Kubernetes takes the container model explained in Docker Fundamentals and adds a control plane that keeps workloads running, healthy, and reachable across a fleet of machines. You declare a desired state through the Kubernetes API; controllers continuously compare that declaration with the cluster's observed state and reconcile the difference. A Deployment does not "run a container" directly: it manages ReplicaSets, which manage disposable Pods. A Service does not own those Pods: it selects Ready Pods by label and gives that changing backend set a stable network identity.

That ownership chain is the essential mental model. When something fails, diagnose the layer that owns the symptom instead of randomly restarting resources: the Deployment for rollout state, the Pod and its Events for scheduling or container failures, logs for application behavior, EndpointSlices for Service backends, and nodes or metrics for resource pressure. The official Kubernetes learning path follows the same practical loop: deploy, inspect, expose, scale, update, and debug. This guide keeps those tasks together.

Quick Reference

The commands below are grouped by intent, not alphabetically. Confirm the active context and namespace before every production investigation: a correct command against the wrong cluster is still a dangerous command.

Syntax

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: api
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api
    spec:
      containers:
        - name: api
          image: registry.example.com/api:1.4.0
          ports:
            - name: http
              containerPort: 8080
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi
          startupProbe:
            httpGet:
              path: /health/startup
              port: http
            periodSeconds: 5
            failureThreshold: 30
          readinessProbe:
            httpGet:
              path: /health/ready
              port: http
            periodSeconds: 5
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /health/live
              port: http
            periodSeconds: 10
            failureThreshold: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app.kubernetes.io/name: api
  ports:
    - name: http
      port: 80
      targetPort: http

The Deployment selector and Pod-template labels must match; the Service independently uses the same label to discover backends. Resource requests influence scheduling, while limits are runtime ceilings. Readiness removes an unhealthy Pod from Service traffic, liveness restarts a stuck container, and startup prevents those checks from interfering with slow initialization.

Examples

Deploy and inspect

# Confirm the target before changing anything
kubectl config current-context
kubectl config set-context --current --namespace=production

# Preview and apply the desired state
kubectl diff -f deployment.yaml
kubectl apply -f deployment.yaml
kubectl wait --for=condition=available deployment/api --timeout=120s
kubectl get pods -l app.kubernetes.io/name=api -o wide
kubectl get endpointslices -l kubernetes.io/service-name=api

Update and roll back

kubectl set image deployment/api api=registry.example.com/api:1.5.0
kubectl rollout status deployment/api
kubectl rollout history deployment/api

# If the new revision is unhealthy:
kubectl rollout undo deployment/api
kubectl rollout status deployment/api

// Inside any Pod in the cluster, the Service's DNS name resolves
// automatically - no hardcoded Pod IPs, no service registry to run.
const response = await fetch('http://api.production.svc.cluster.local/health/ready')

curl http://localhost:8080/health/ready

Troubleshooting Workflow

The official Kubernetes troubleshooting guides start with triage: decide whether the failure is in the workload, Pod, Service, or cluster. Preserve evidence before deleting or restarting anything; recreating a Pod can remove the Events and previous-container state that explain the failure.

kubectl get svc api -o yaml
kubectl get pods -l app.kubernetes.io/name=api --show-labels
kubectl get endpointslices -l kubernetes.io/service-name=api
kubectl run -it --rm net-debug --restart=Never --image=busybox:1.36 -- sh

# From the temporary in-cluster shell:
nslookup api
wget -qO- http://api/health/ready

Visual Diagram

Common Mistakes

• Editing a Pod directly (kubectl edit pod) instead of the Deployment that manages it; the change is lost the moment that Pod is replaced.
• Deleting a failing Pod before reading describe, Events, Last State, and logs --previous, destroying the best evidence and recreating the same failure.
• Treating Running as equivalent to healthy; a Pod can be Running while containers restart or readiness remains false.
• Checking only current logs after a restart, when the failure output belongs to the previous container instance.
• Debugging a broken Service without checking selectors and EndpointSlices, or confusing Service port with Pod targetPort.
• Reusing one dependency-heavy endpoint for startup, readiness, and liveness, causing a dependency outage to restart every otherwise healthy application replica.
• Omitting resource requests or guessing them far below real usage, so the scheduler packs more workload onto a node than normal demand can support.
• Treating Secret values as encrypted merely because their YAML representation is base64; use access controls and an appropriate encryption or external-secret strategy.

Performance

• Resource requests drive scheduling capacity decisions, not current usage. Under-requesting can overpack nodes; over-requesting strands capacity and can leave otherwise runnable Pods Pending.
• CPU limits are enforced by throttling, while memory pressure cannot be handled the same way and may end in an OOM kill. Choose limits from measured behavior instead of copying one ratio across every workload.
• Rolling-update settings trade speed, spare capacity, and availability. maxSurge needs temporary capacity for new Pods; maxUnavailable decides how much serving capacity may disappear during the rollout.
• Readiness design affects usable capacity. A probe that is too strict can remove healthy Pods during a traffic spike, increasing load on the remaining replicas and turning a small slowdown into a cascade.
• Horizontal autoscaling depends on meaningful requests and available metrics. Scaling cannot repair a memory leak, a broken dependency, or a Service with no endpoints.

Best Practices

• Confirm context and namespace before every change, and include -n <namespace> in runbooks so commands are safe to copy under pressure.
• I keep production configuration declarative and version-controlled. I use kubectl diff before apply, then let GitOps Principles guide continuous reconciliation and rollback.
• I use stable, consistent labels for ownership and selection. A Deployment selector, Pod-template labels, and Service selector should be understandable as one relationship.
• Set resource requests from observed steady-state demand and choose limits from measured peaks and failure tolerance. I use the Kubernetes Resource Calculator to check replica totals.
• Give startup, readiness, and liveness separate jobs. A readiness failure controls traffic; a liveness failure should mean the process is genuinely unable to recover without a restart.
• Emit structured logs, workload metrics, and traces with correlation identifiers. Observability Fundamentals explains how to combine those signals during an incident.
• I use namespaces for scope and organization, then add RBAC, Pod Security admission, and NetworkPolicy from Kubernetes Security; namespaces alone are not a security boundary.
• Prefer minimal production images and use ephemeral debug containers when necessary, rather than shipping shells and troubleshooting packages in every application image.