Kubernetes for App Developers: Cut Through the Complexity | Akousa

yaml

apiVersion: v1
kind: Pod
metadata:
  name: my-api
  labels:
    app: my-api
spec:
  containers:
    - name: my-api
      image: registry.example.com/my-api:1.2.3
      ports:
        - containerPort: 3000
      env:
        - name: NODE_ENV
          value: "production"
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: connection-string

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
  namespace: production
  labels:
    app: my-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-api
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    metadata:
      labels:
        app: my-api
        version: "1.2.3"
    spec:
      containers:
        - name: my-api
          image: registry.example.com/my-api:1.2.3
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 15
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
            failureThreshold: 3
          startupProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 0
            periodSeconds: 5
            failureThreshold: 30
          env:
            - name: NODE_ENV
              value: "production"
          envFrom:
            - configMapRef:
                name: my-api-config
            - secretRef:
                name: my-api-secrets
      terminationGracePeriodSeconds: 30

yaml

apiVersion: <group/version> # Which API this resource belongs to
kind: <ResourceType> # What you're creating
metadata: # Name, namespace, labels, annotations
  name: my-thing
  namespace: default
  labels:
    app: my-thing
spec: # The actual configuration (varies by kind)
  ...

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
spec:
  # ...
---
apiVersion: v1
kind: Service
metadata:
  name: my-api
spec:
  # ...
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-api-config
data:
  # ...

yaml

apiVersion: v1
kind: Service
metadata:
  name: my-api
  namespace: production
spec:
  selector:
    app: my-api
  ports:
    - port: 80
      targetPort: 3000
      protocol: TCP
  type: ClusterIP

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-api
                port:
                  number: 80

yaml

apiVersion: v1
kind: Secret
metadata:
  name: my-api-secrets
  namespace: production
type: Opaque
data:
  DATABASE_URL: cG9zdGdyZXM6Ly91c2VyOnBhc3NAZGIuZXhhbXBsZS5jb206NTQzMi9teWRi
  REDIS_PASSWORD: c3VwZXJzZWNyZXRwYXNzd29yZA==
  API_KEY: YWJjZGVmMTIzNDU2Nzg5MA==

yaml

# As environment variables (all keys at once)
envFrom:
  - configMapRef:
      name: my-api-config
  - secretRef:
      name: my-api-secrets
 
# As individual environment variables (pick specific keys)
env:
  - name: DB_HOST
    valueFrom:
      configMapKeyRef:
        name: my-api-config
        key: DB_HOST
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: my-api-secrets
        key: DB_PASSWORD
 
# As mounted files
volumeMounts:
  - name: config-volume
    mountPath: /etc/config
    readOnly: true
volumes:
  - name: config-volume
    configMap:
      name: my-api-config

javascript

app.get("/ready", async (req, res) => {
  try {
    // Can we reach the database?
    await db.query("SELECT 1");
    // Can we reach the cache?
    await redis.ping();
    res.status(200).json({ status: "ready" });
  } catch (err) {
    res.status(503).json({ status: "not ready", error: err.message });
  }
});

javascript

process.on("SIGTERM", async () => {
  console.log("SIGTERM received. Starting graceful shutdown...");
 
  // Stop accepting new connections
  server.close(async () => {
    // Finish processing in-flight requests
    // Close database connections
    await db.end();
    await redis.quit();
 
    console.log("Graceful shutdown complete.");
    process.exit(0);
  });
 
  // Force shutdown after 25 seconds (leave 5s buffer before SIGKILL)
  setTimeout(() => {
    console.error("Forced shutdown after timeout.");
    process.exit(1);
  }, 25000);
});

yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-api-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-api
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 30
        - type: Pods
          value: 4
          periodSeconds: 60
      selectPolicy: Max

bash

# See all pods in a namespace
kubectl get pods -n production
 
# See more details (node, IP, restart count)
kubectl get pods -n production -o wide
 
# See all resources related to your app
kubectl get all -n production -l app=my-api

NAME                      READY   STATUS    RESTARTS   AGE
my-api-7d4b8c6f5-abc12   1/1     Running   0          2d
my-api-7d4b8c6f5-def34   0/1     Running   3          15m
my-api-7d4b8c6f5-ghi56   1/1     Running   0          2d

Events:
  Type     Reason     Age                From               Message
  ----     ------     ----               ----               -------
  Normal   Scheduled  15m                default-scheduler  Assigned to node-3
  Normal   Pulling    15m                kubelet            Pulling image "registry.example.com/my-api:1.2.3"
  Normal   Pulled     14m                kubelet            Container image pulled
  Normal   Created    14m                kubelet            Created container my-api
  Normal   Started    14m                kubelet            Started container my-api
  Warning  Unhealthy  3m (x9 over 14m)   kubelet            Readiness probe failed: Get "http://10.244.2.15:3000/ready": dial tcp 10.244.2.15:3000: connect: connection refused
  Warning  BackOff    2m (x3 over 5m)    kubelet            Back-off restarting failed container

bash

# Current container logs
kubectl logs my-api-7d4b8c6f5-def34 -n production
 
# Previous container's logs (before the restart)
kubectl logs my-api-7d4b8c6f5-def34 -n production --previous
 
# Follow logs in real-time
kubectl logs my-api-7d4b8c6f5-def34 -n production -f
 
# Last 100 lines
kubectl logs my-api-7d4b8c6f5-def34 -n production --tail=100
 
# Logs from all pods matching a label
kubectl logs -l app=my-api -n production --all-containers

bash

# Open a shell in the running container
kubectl exec -it my-api-7d4b8c6f5-abc12 -n production -- /bin/sh
 
# Run a single command
kubectl exec my-api-7d4b8c6f5-abc12 -n production -- env
 
# Check if the app is listening
kubectl exec my-api-7d4b8c6f5-abc12 -n production -- netstat -tlnp
 
# Test connectivity to another service
kubectl exec my-api-7d4b8c6f5-abc12 -n production -- wget -qO- http://my-database:5432

bash

# Forward local port 8080 to the Service's port 80
kubectl port-forward svc/my-api 8080:80 -n production
 
# Forward to a specific pod
kubectl port-forward my-api-7d4b8c6f5-abc12 8080:3000 -n production

bash

# CPU and memory usage per pod
kubectl top pods -n production
 
# CPU and memory usage per node
kubectl top nodes
 
# Detailed resource view for a specific pod
kubectl describe pod my-api-7d4b8c6f5-abc12 -n production | grep -A5 "Requests\|Limits"

bash

# Restart all pods in a deployment (rolling restart)
kubectl rollout restart deployment/my-api -n production
 
# Roll back to the previous version
kubectl rollout undo deployment/my-api -n production
 
# Roll back to a specific revision
kubectl rollout history deployment/my-api -n production
kubectl rollout undo deployment/my-api -n production --to-revision=5
 
# Scale to zero (emergency stop)
kubectl scale deployment/my-api -n production --replicas=0
 
# Scale back up
kubectl scale deployment/my-api -n production --replicas=3

my-api-chart/
  Chart.yaml          # Chart metadata
  values.yaml         # Default configuration values
  templates/
    deployment.yaml   # Kubernetes manifest templates
    service.yaml
    ingress.yaml
    configmap.yaml
    hpa.yaml
    _helpers.tpl      # Template helper functions

yaml

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: { { include "my-api.fullname" . } }
  labels: { { - include "my-api.labels" . | nindent 4 } }
spec:
  replicas: { { .Values.replicaCount } }
  selector:
    matchLabels: { { - include "my-api.selectorLabels" . | nindent 6 } }
  template:
    spec:
      containers:
        - name: { { .Chart.Name } }
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources: { { - toYaml .Values.resources | nindent 12 } }

bash

# Install a chart
helm install my-api ./my-api-chart -n production
 
# Upgrade with new values
helm upgrade my-api ./my-api-chart -n production --set image.tag=1.2.4
 
# Upgrade with a values file for a specific environment
helm upgrade my-api ./my-api-chart -n production -f values-production.yaml
 
# Roll back
helm rollback my-api 1 -n production
 
# See what would change without applying
helm diff upgrade my-api ./my-api-chart -n production --set image.tag=1.2.4

bash

# Create a namespace
kubectl create namespace staging
 
# List all namespaces
kubectl get namespaces
 
# Set your default namespace (so you don't need -n every time)
kubectl config set-context --current --namespace=production

production      # Live traffic
staging         # Pre-production testing
development     # Developer environments
monitoring      # Prometheus, Grafana, etc.
ingress-nginx   # Ingress controller
cert-manager    # Certificate management

yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: production-quota
  namespace: production
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "50"

yaml

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: my-api-network-policy
  namespace: production
spec:
  podSelector:
    matchLabels:
      app: my-api
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: my-frontend
      ports:
        - port: 3000
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: my-database
      ports:
        - port: 5432

Resource	apiVersion
Pod	`v1`
Service	`v1`
ConfigMap	`v1`
Secret	`v1`
Deployment	`apps/v1`
Ingress	`networking.k8s.io/v1`
HPA	`autoscaling/v2`
CronJob	`batch/v1`

Why Kubernetes Exists (The Real Reason)

The Mental Model: Think Layers

Pods: Not Just Containers

Deployments: The Thing You Actually Create

Replicas and Selector

Rolling Update Strategy

Resource Requests and Limits

Probes

YAML Demystified: It Is Just Configuration

Services: Stable Networking for Ephemeral Pods

Ingress: HTTP Routing

ConfigMaps and Secrets: Externalize Everything

Health Checks: The Three Probes

Liveness Probe: "Is the process stuck?"

Readiness Probe: "Can it handle traffic?"

Startup Probe: "Is it still booting?"

The Shutdown Side: Graceful Termination

Resource Requests and Limits: Get These Wrong and Bad Things Happen

The Most Common Mistake: No Limits At All

CPU Throttling: The Silent Killer

Quality of Service Classes

HPA: Automatic Horizontal Pod Autoscaling

Debugging with kubectl: The Workflow That Actually Works

Step 1: What Is the Current State?

Step 2: Describe the Problem Pod

Step 3: Check the Logs

Step 4: Get Inside the Container

Step 5: Port Forward for Local Testing

Step 6: Check Resource Usage

The Emergency Commands

Helm: The Package Manager You Will Eventually Use

Namespaces: Lightweight Isolation

Common Mistakes (I Made All of These)

Mistake 1: Using the latest Tag

Mistake 2: No Resource Limits

Mistake 3: No Health Checks

Mistake 4: Not Setting terminationGracePeriodSeconds

Mistake 5: Ignoring Pod Disruption Budgets

Mistake 6: One Giant Namespace

Mistake 7: Not Using kubectl diff

Mistake 8: Skipping Network Policies

When NOT to Use Kubernetes

The Honest Take

Related Posts

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

Volume Calculator Guide for Containers and Projects

Mistake 1: Using the `latest` Tag

Mistake 4: Not Setting `terminationGracePeriodSeconds`

Mistake 7: Not Using `kubectl diff`