Kubernetes Essentials

Core objects and how they relate

Kubernetes stores objects that describe the state you want, and controllers work to make the cluster match it. Seven objects cover most of a small application.

Add -n shop to commands, or save the namespace in your context with kubectl config set-context --current --namespace=shop. A forgotten namespace shows an empty list.

A compact manifest set

One file, five objects. The image name is a placeholder.

---
apiVersion: v1
kind: Namespace
metadata:
  name: shop
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config
  namespace: shop
data:
  LOG_LEVEL: info
---
apiVersion: v1
kind: Secret
metadata:
  name: web-secret
  namespace: shop
stringData:
  DB_PASSWORD: change-me
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: shop
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  minReadySeconds: 10
  progressDeadlineSeconds: 300
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: registry.example.com/shop/web:1.4.2
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: web-config
          env:
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: web-secret
                  key: DB_PASSWORD
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi
          startupProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 5
            failureThreshold: 30
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            periodSeconds: 5
            failureThreshold: 3
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: shop
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 8080

• The image has a specific tag. The documentation advises avoiding :latest in production because it is harder to track which version runs and to roll back.
• stringData takes plain strings, which are merged into data. Never commit a real secret value to git. Base64 is obscured, not encrypted.
• The Service listens on port 80 and forwards to the container’s targetPort 8080.

Without a cluster, yamllint shop.yaml checks syntax and style only, and kubectl create deployment web --image=... --replicas=3 --dry-run=client -o yaml prints a starting manifest. Against a real cluster, kubectl apply --dry-run=server -f shop.yaml submits the request without persisting it, and the default --validate=strict checks the schema. Client-side kubectl apply --dry-run=client still contacts the API server, so it fails when no cluster is reachable.

Probes: startup, liveness, readiness

Probes are checks the kubelet runs against a container. Each answers a different question, so a failure has a different consequence.

The mechanisms are exec, grpc, httpGet and tcpSocket. Documented defaults: initialDelaySeconds 0, periodSeconds 10, timeoutSeconds 1, successThreshold 1 (it must be 1 for liveness and startup) and failureThreshold 3. Check the documentation for your version.

• Startup. The documentation suggests one when the container usually needs more than initialDelaySeconds + failureThreshold × periodSeconds to start. In the manifest, periodSeconds: 5 times failureThreshold: 30 allows about 150 seconds.
• Liveness. The documentation says to use it with caution: it must truly indicate unrecoverable failure such as a deadlock, and a wrong setup can cause cascading failures. Reasoning, not from the docs: a check that fails because a database is down cannot be fixed by restarting this container, so it is a poor liveness check.
• Readiness is not only for startup. The documentation notes it is also useful later, for example when recovering from temporary faults or overloads.

Requests versus limits

Requests and limits are set per container. Different components use them, and that is the whole difference.

CPU is measured in CPU units: 0.1 equals 100m. Memory is measured in bytes, with suffixes such as M or the power-of-two Mi. If you set a limit but no request, and nothing applies a default request, Kubernetes uses the limit as the request. The manifest requests 100m CPU and 128Mi memory and limits memory to 256Mi. It sets no CPU limit, which is a policy choice.

• Choose numbers from measurement. kubectl top pod shows current usage but needs the metrics-server service.
• The failures look different. Too-large requests give Pending with a FailedScheduling event. Too-small memory limits give restarts and an OOMKilled reason.

Rollouts and rollbacks

A Deployment’s rollout is triggered if and only if its Pod template (.spec.template) changes, for example a new container image or new labels. Scaling does not trigger a rollout.

$ kubectl set image deployment/web web=registry.example.com/shop/web:1.4.3 -n shop
$ kubectl rollout status deployment/web -n shop
$ kubectl rollout history deployment/web -n shop
$ kubectl rollout history deployment/web -n shop --revision=2
# back to the previous revision, or to a specific one
$ kubectl rollout undo deployment/web -n shop
$ kubectl rollout undo deployment/web -n shop --to-revision=2

kubectl rollout status exits with 0 when the rollout completed and non-zero when the Deployment exceeded its progress deadline, so it works as a CI gate. It also accepts --timeout and --watch=false.

Those are the documented defaults, so check the documentation for your version. maxUnavailable and maxSurge cannot both be 0. The manifest uses maxSurge: 1 and maxUnavailable: 0: with 3 replicas, at most 4 Pods exist during the update and the number of available Pods never drops below 3, at the price of room for one extra Pod. “Available” depends on readiness, so a missing readiness probe makes rollouts less safe.

Debugging order

The Kubernetes documentation starts with the same first step: look at the Pod, then at its recent events. Follow one order and stop at the first clear answer.

1. kubectl get pods -n shop shows the status of every Pod. Add -w to watch changes.
2. kubectl describe pod NAME -n shop shows the Pod’s current state and recent events, including the scheduler’s reasons. For the last termination reason and exit code, read lastState.terminated under status.containerStatuses in kubectl get pod NAME -n shop -o yaml.
3. kubectl logs NAME -n shop, and --previous for the previous container’s crash log. Add -c CONTAINER for a multi-container Pod.
4. kubectl events --for pod/NAME -n shop lists events for that Pod only. The docs also show kubectl get events.
5. Only then get inside. kubectl exec -it NAME -n shop -- sh works when the image includes a shell. kubectl debug -it NAME -n shop --image=busybox:1.28 --target=CONTAINER adds an ephemeral debug container (stable since v1.25, per the docs). kubectl debug NAME -it --image=ubuntu --share-processes --copy-to=NAME-debug debugs a copy, and --copy-to=NAME-debug --container=CONTAINER -- sh replaces the command of a crashing container in the copy.

For a full walk-through of one case, see the CrashLoopBackOff tutorial in the tutorials section.

Cheat sheet and checklist

Before you ship

• The image tag is pinned. No :latest.
• Every container has requests. Memory limits come from measurement.
• A readiness probe exists, slow starters have a startup probe, and liveness only reports failures a restart can fix.
• Secret values are not in git. Secrets are unencrypted in etcd by default, so restrict access and read the Secrets documentation.
• CI runs kubectl rollout status and treats a non-zero exit as a failed deploy.

Official documentation

• Pods
• Pod Lifecycle
• Liveness, Readiness, and Startup Probes
• Deployments
• ReplicaSet
• Service
• ConfigMaps
• Secrets
• Namespaces
• Resource Management for Pods and Containers
• Assign Memory Resources to Containers and Pods
• Images
• Debug Pods
• Debug Running Pods

Keep going