Kubernetes Basics for Developers

Kubernetes is an orchestration platform for running containers across one or many machines with a declarative model: you describe the state you want, and the cluster tries to make it true. For developers, this matters because it replaces ad hoc server setup with repeatable objects such as Pods, Deployments, and Services. A typical app has at least one container image, one Deployment, and one Service, even if the cluster is only running on a laptop with 1–2 nodes.

The main idea is that Kubernetes separates what should run from where it runs. You usually do not SSH into hosts to manage processes; instead, you apply manifests and let controllers reconcile changes. That is why concepts in Core Kubernetes building blocks and Writing Kubernetes manifests are more important than memorizing every command. A developer who understands the object model can debug faster, choose sensible resource settings, and avoid brittle deployment scripts.> If your app depends on local files, hardcoded IPs, or manual restarts, Kubernetes will expose those assumptions quickly; plan to externalize configuration and make startup idempotent.

Kubernetes is made of a few core objects that appear in almost every workflow. The most important thing for developers is to understand which objects are ephemeral, which are durable, and which are only there to coordinate traffic. The basic mental model is simple: containers run inside Pods, Pods are managed by controllers, and Services provide stable network access.

This section covers the object types you will see in kubectl get output and YAML manifests. If you can explain these four nouns clearly, most day-to-day tasks become easier to reason about, especially when debugging why a request reaches one Pod but not another. See Pod and container model and Controllers and Services for the details.

A Pod is the smallest deployable unit in Kubernetes. It usually runs one application container, though sidecars are common when you need logging, proxying, or metrics collection. Containers in the same Pod share the network namespace and can talk over localhost, but they do not share the same writable filesystem unless you mount a volume. That detail matters when you split a service into a main app container and a helper container.

Pods are meant to be disposable, not pets. When a Pod dies, Kubernetes creates a replacement rather than repairing the old one. For example, if your web container crashes because port 8080 is already in use, the kubelet will restart it depending on the restart policy. Developers should design for this by making startup fast and state external, then use Logs, events, and exec to inspect failures.> Treat a Pod as a scheduling and networking wrapper, not as a durable server instance; the controller, not the Pod, is what you usually manage.

Controllers keep the cluster aligned with the desired state you declared. A Deployment is the most common controller for stateless apps: it creates ReplicaSets, which create Pods and replace them if they disappear. A StatefulSet is used when identity and stable storage matter, but most application developers start with Deployments. If you set replicas: 3, Kubernetes will keep three matching Pods running unless a node or image problem prevents it.

Services solve the problem of changing Pod IPs by providing a stable virtual IP and DNS name. A ClusterIP Service is internal-only, while NodePort and LoadBalancer expose traffic differently depending on the environment. For a simple web app, a Deployment plus a ClusterIP Service is often enough to test through port-forwarding, then later via an Ingress. Deployments, rollouts, and replicasets explains how the controller responds to updates.> Services route to Pods by label selectors, so a typo in a label can make healthy Pods look “invisible” to traffic.

A local cluster is the fastest way to learn Kubernetes without waiting for shared infrastructure. It gives you a realistic control plane, scheduling behavior, and networking model while keeping the feedback loop short. Many teams use a local environment for the first pass of app packaging, because it turns build-and-deploy mistakes into immediate errors instead of slow CI failures.

The workflow usually looks like: build an image, push or load it into the local cluster, apply manifests, and verify the app with kubectl. Even a tiny app benefits from this sequence because it forces you to define ports, environment variables, and health checks early. The exact commands vary by tool, so this section focuses on the repeatable pattern and the trade-offs between local options.

Popular local environments include kind, minikube, and Docker Desktop. They differ mainly in speed, resource usage, and how closely they match a real cluster. Kind runs Kubernetes nodes inside Docker containers and is lightweight for automated tests; Minikube is flexible and good for experimentation; Docker Desktop integrates tightly with a desktop workflow but may hide some infrastructure differences.

Pick the tool that matches your use case. If you need quick CI-like cluster creation, kind is often fastest. If you want an interactive playground with add-ons, Minikube is convenient. For example, a developer laptop with 16 GB RAM can comfortably run a small local cluster, but enabling too many add-ons may slow image pulls and pod scheduling. The right choice is the one you will actually use every day, then validate behavior against a real cluster later.> Local clusters are excellent for behavior, not for capacity planning; always retest resource-heavy apps in an environment closer to production.

The most useful commands are short and repetitive: kubectl get, kubectl describe, kubectl logs, and kubectl apply. These cover 80% of developer work because they answer four questions: what exists, what happened, what the container said, and what changed. A practical loop is to apply a manifest, wait for readiness, inspect a failing Pod, then fix the manifest or image.

A small example looks like this:

kubectl apply -f deployment.yaml
kubectl get pods
kubectl describe pod my-app-7d9f8c9b6f-abcde
kubectl logs my-app-7d9f8c9b6f-abcde

Use kubectl port-forward when you want to test a web server without exposing it publicly. For instance, forwarding local port 8080 to a Pod or Service is often faster than configuring an Ingress during development. These commands pair naturally with Logs, events, and exec when the app does not start as expected.

Kubernetes manifests are YAML documents that describe objects such as Pods, Deployments, Services, and ConfigMaps. They are the source of truth for the cluster, which is why small mistakes like indentation errors or wrong label selectors can cause confusing failures. Developers usually start with a Deployment and Service, then add ConfigMaps, Secrets, and probes as the app grows.

A good manifest is explicit enough to be readable but small enough to maintain. You should define image names, container ports, labels, and resource settings instead of relying on defaults that vary across environments. Manifest structure and fields explains the common keys, while Configuration and secrets shows how to avoid hardcoding values into images.

Most manifests share the same top-level shape: apiVersion, kind, metadata, and spec. Under metadata, names and labels identify the object; under spec, you describe desired behavior such as the number of replicas or the container image. A single missing label can break a Service selector, so developers should copy label blocks carefully between related objects.

A minimal Deployment often includes the container image, exposed port, and readiness probe. Example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080

Notice that the selector labels and Pod template labels must match exactly. That detail is one of the most common sources of “no endpoints” problems, which you can trace later in Controllers and Services.

Configuration should be injected, not baked into the image. Use ConfigMaps for non-sensitive values like feature flags, ports, and environment-specific URLs. Use Secrets for credentials, API keys, and tokens, but remember that a Secret is still only base64-encoded by default; it is not automatically encrypted unless the cluster is configured for it.

A simple pattern is to expose settings as environment variables or mounted files. For example, a database host can live in a ConfigMap, while the password comes from a Secret, and your app reads both at startup. This keeps the same container image usable across dev, staging, and production. If you later need to rotate credentials, you update the Secret rather than rebuilding the image. That workflow pairs well with Developer best practices because it reduces drift and makes deployments more predictable.> Do not commit real Secrets to Git, even in a private repo; use external secret management or at least separate encrypted handling in CI.

Once the manifest is correct, the next concern is how updates move through the cluster. Kubernetes does not replace every running container at once by default; it uses controlled rollouts to keep the application available while changing the Pod template. This is where developers see the practical benefit of using a Deployment instead of managing Pods manually.

You should understand the difference between changing an image tag, changing a config value, and changing the number of replicas. These actions have different effects on rollout behavior and on how fast the system converges. Deployments, rollouts, and replicasets covers the mechanism, while Scaling and rollbacks covers operational changes and recovery.

A Deployment manages ReplicaSets, and ReplicaSets manage Pods. When you update the Pod template—such as changing the image from 1.0.0 to 1.0.1—Kubernetes creates a new ReplicaSet and gradually shifts traffic to new Pods. This rolling update behavior helps avoid downtime, but only if your readiness probe is meaningful and your app can start cleanly in multiple copies.

The common commands are:

kubectl rollout status deployment/my-app
kubectl rollout history deployment/my-app
kubectl rollout undo deployment/my-app

These commands are useful because they show whether the update is still progressing, what changed, and how to revert quickly. A deployment that keeps restarting is often caused by bad environment variables, a crash in startup code, or a probe that is too aggressive. If you are troubleshooting that case, jump to Logs, events, and exec for a structured approach.

Scaling changes the replica count, while rollbacks revert the workload to a previous template revision. Horizontal scaling is as simple as changing replicas: 3 to replicas: 6, but you should check whether your app can share state safely across instances before doing that. For example, a session-based web app may need an external session store or sticky routing to behave correctly with multiple Pods.

Rollbacks are a safety net, not a substitute for testing. If a release causes errors after deployment, kubectl rollout undo can restore the previous ReplicaSet quickly, often in seconds. Still, the better pattern is to keep small, versioned image tags and verify health checks before shifting traffic. A good practice is to pair any scaling change with metrics review so you know whether CPU, memory, or latency drove the decision. That approach complements Resource requests, limits, and health probes in the final section.

Debugging Kubernetes means understanding whether the problem is in the app, the Pod, the Service, or the node. The fastest way to narrow it down is to look at logs, events, and object state in that order. Many issues are not actually Kubernetes bugs; they are startup failures, bad image references, or selectors that do not match any Pods.

The cluster gives you several tools, but they each answer different questions. Logs show application output, events show scheduler and controller actions, and exec lets you inspect a running container directly. If you already know the symptom, these tools help you move from guesswork to evidence. See Logs, events, and exec and Common failure modes for practical examples.

kubectl logs is the first command to run when a Pod crashes or a request fails. If the container exits quickly, add --previous to inspect the last terminated instance. Events from kubectl describe pod often reveal image pull errors, probe failures, or scheduling constraints before you ever open an application log.

For deeper inspection, kubectl exec lets you run commands inside a container. That is useful when you want to check DNS resolution, environment variables, or filesystem paths. Example:

kubectl logs my-app-pod
kubectl describe pod my-app-pod
kubectl exec -it my-app-pod -- sh

A common pitfall is relying only on logs when the issue is actually in the controller or Service. For instance, if traffic never reaches the container, logs may be silent because the request never arrived. In that case, compare labels and selectors in Manifest structure and fields and Controllers and Services.

Some problems show up repeatedly in developer workflows. The most common are ImagePullBackOff, CrashLoopBackOff, failed readiness probes, and Services with no endpoints. Each one points to a different layer: image access, startup stability, health checks, or label matching.

A useful mental checklist is:

1. Confirm the image name and tag exist.
2. Check Pod events for scheduling or pull errors.
3. Verify the container starts on the declared port.
4. Compare Service selectors to Pod labels.
5. Test with port-forwarding before blaming ingress or DNS.

For example, a container that listens on port 3000 but the manifest declares 8080 may appear healthy inside the Pod but fail external probes. If you see repeated restarts, inspect the command, environment, and readiness settings first. Many of these issues are easier to catch early if you follow the patterns in Developer best practices.> When in doubt, treat the Pod as disposable and reproduce the issue with a clean kubectl apply rather than manually editing live objects.

The best Kubernetes habits are the ones that reduce surprises. Define resource requests and limits, use labels consistently, keep namespaces tidy, and make health checks reflect real readiness rather than a simple process check. These practices help the scheduler place Pods correctly and help you understand whether an update is safe to serve traffic.

For developers, the goal is not to learn every Kubernetes feature. It is to create workloads that behave predictably under restart, rescheduling, and scaling. The patterns below are enough for most services and tie together what you saw in Core Kubernetes building blocks and Debugging and observability.

Resource requests tell the scheduler what your container needs; limits cap how much it can use. If you request 250m CPU and 256Mi memory, the scheduler places the Pod on a node with enough headroom, which is much better than letting every container compete blindly. Limits matter too, because a memory-hungry process can otherwise consume a node and trigger evictions.

Health probes are equally important. A readiness probe decides when the Pod should receive traffic, while a liveness probe decides when it should be restarted. For a web API, a readiness probe might verify database connectivity or cached config, while a liveness probe checks that the process is still responsive. A probe that is too strict can cause restart loops, so start with a generous timeout and refine it with data. This is one place where observing actual behavior in Logs, events, and exec pays off.

Labels are the connective tissue of Kubernetes. They power Service selectors, Deployment matching, and most operational queries. Use a small, consistent label set such as app, tier, and env, and apply them to both Pods and higher-level objects. Namespaces help separate environments or teams so that dev, staging, and prod do not collide.

Cleanups matter because orphaned objects create confusion and cost. Delete test Deployments, Services, and ConfigMaps when you are done, especially in a shared cluster. A practical routine is to put short-lived experiments in a dedicated namespace and remove the namespace afterward:

kubectl create namespace dev-playground
kubectl delete namespace dev-playground

That habit reduces accidental cross-talk between experiments and makes it easier to reason about what is actually running. It also makes the differences between local practice and production deployment clearer, especially when paired with Developer workflow with a local cluster.