Kubernetes for Developers: The Concepts You Must Know to Deploy and Debug in K8s

Kubernetes documentation assumes you want to run a cluster. Most developers just want to deploy their app. This guide covers everything a developer needs: writing Deployments and Services, configuring environment variables, setting resource limits, debugging crashed pods, and the kubectl commands that solve 90% of production issues.

⚡ TL;DR: Deployment manages replicas. Service exposes them. Ingress routes external traffic. ConfigMap holds config. Secret holds credentials. Resources defines CPU/memory limits. Liveness probe restarts unhealthy pods. Readiness probe controls traffic routing. kubectl logs, describe, and exec debug everything.

A complete application deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-api
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1   # At most 1 pod down during update
      maxSurge: 1         # At most 1 extra pod during update
  template:
    metadata:
      labels:
        app: my-api
    spec:
      containers:
        - name: api
          image: my-registry/my-api:v1.2.3  # Always pin exact version
          ports:
            - containerPort: 3000
          env:
            - name: NODE_ENV
              value: production
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:       # From Secret, not hardcoded
                  name: db-secret
                  key: url
          resources:
            requests:               # Minimum guaranteed
              cpu: "100m"           # 0.1 CPU core
              memory: "128Mi"
            limits:                 # Maximum allowed
              cpu: "500m"           # 0.5 CPU core
              memory: "512Mi"       # Pod killed if exceeded!
          livenessProbe:            # Restart if unhealthy
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 15
            periodSeconds: 20
          readinessProbe:           # Remove from load balancer if not ready
            httpGet:
              path: /ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10

Debugging crashed pods — the kubectl toolkit

# The debugging workflow for any K8s issue

# Step 1: What's wrong?
kubectl get pods                                # List pods and their status
kubectl get pods -l app=my-api                  # Filter by label

# Step 2: Why is it failing?
kubectl describe pod my-api-abc123             # Events, conditions, resource issues
# Look for:
# - "OOMKilled" = pod exceeded memory limit
# - "CrashLoopBackOff" = container keeps crashing
# - "ImagePullBackOff" = can't pull image
# - "Pending" = no node has enough resources

# Step 3: What did the app log?
kubectl logs my-api-abc123                     # Current container logs
kubectl logs my-api-abc123 --previous         # Previous container logs (after crash)
kubectl logs -l app=my-api --since=1h         # All pods, last 1 hour
kubectl logs -f my-api-abc123                 # Follow live

# Step 4: Get a shell in the container
kubectl exec -it my-api-abc123 -- /bin/sh    # Interactive shell
kubectl exec my-api-abc123 -- env            # Check environment variables
kubectl exec my-api-abc123 -- curl localhost:3000/health  # Test endpoint from inside

# Step 5: Check resource usage
kubectl top pods                              # CPU and memory per pod
kubectl top nodes                            # Node resource usage

Services and Ingress

---
apiVersion: v1
kind: Service
metadata:
  name: my-api-svc
spec:
  selector:
    app: my-api           # Routes to pods with this label
  ports:
    - port: 80            # Service port
      targetPort: 3000    # Container port
  type: ClusterIP         # Internal only (use LoadBalancer for external)

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rate-limit: "100"
spec:
  rules:
    - host: api.myapp.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-api-svc
                port:
                  number: 80

Kubernetes developer checklist

• ✅ Always set resource requests AND limits — without limits, one pod can starve others
• ✅ Always add liveness AND readiness probes — different purposes, both needed
• ✅ Use Secrets for credentials — never hardcode in Deployment YAML
• ✅ Pin image versions — never use :latest in production
• ✅ Use RollingUpdate strategy — zero-downtime deployments
• ✅ kubectl describe pod is your best debugging tool — read the Events section
• ❌ Never set CPU limit below what your app actually needs — causes throttling
• ❌ Never use hostPort — use Services instead

Kubernetes connects to the Docker best practices guide — the container you ship to K8s must follow those practices first. For serverless alternatives to K8s, AWS Lambda handles much of the operational complexity K8s requires. External reference: Kubernetes concepts documentation.