Kubernetes celebrated its 1.0 release on 21 July 2015, and more than a decade later the fastest way to learn it still hasn’t changed: copy a working example, break it, fix it. Reading the documentation front to back feels productive, but most engineers only internalize how Pods, Deployments, and Services fit together after they’ve applied a manifest and watched `kubectl get pods` flip from `Pending` to `Running`. That moment of feedback is the real teacher.
This guide walks through the Kubernetes examples that actually matter in practice — the ones you’ll reuse in real clusters, the mistakes that trip up almost everyone the first time, and the habits that separate people who understand Kubernetes from people who just paste YAML. The examples here are deliberately small. Small examples are debuggable; sprawling ones hide their lessons. (Kubernetes Overview)
Why Working Examples Beat Reading Documentation
Kubernetes has an enormous surface area. The official documentation is genuinely excellent, but it’s organized by concept, not by task sequence. You can read about Deployments, Services, ConfigMaps, and Ingress in any order and never see how they connect.
Examples fix that. A runnable manifest forces you to confront the details that prose skips: why the `selector` in a Service must match the Pod’s `labels`, why a container that exits immediately causes a `CrashLoopBackOff`, why `imagePullPolicy` matters more than you’d think on a laptop. These are the things that make Kubernetes feel hostile until they suddenly feel obvious.
There’s a second reason examples matter more than they used to. Kubernetes deprecates APIs on a rolling schedule, and old tutorials rot fast. The `extensions/v1beta1` Ingress API was removed back in v1.22, and countless blog posts still show it. Working from a current example, and knowing which parts are version-sensitive, saves hours of confusing error messages. If you’re maintaining clusters rather than just learning on them, the same discipline applies to upgrades — a structured approach like these EKS cluster upgrade steps for Kubernetes 1.37 keeps you from discovering deprecated APIs in production. (Kubernetes)
The Minimal Pod Example, and What It Actually Teaches
The simplest Kubernetes example is a single Pod running an nginx container. It’s a handful of lines: an `apiVersion`, a `kind` of `Pod`, a `metadata` block with a name, and a `spec` containing one container with an image.
Apply it and you learn several things at once:
- Declarative vs. imperative. You describe the desired state; the control plane figures out how to reach it.
- Scheduling is not instant. A Pod moves through `Pending`, `ContainerCreating`, and `Running`. Watching those transitions teaches you more about the scheduler than any diagram.
- Pods are disposable. Delete it and it’s gone. Nothing recreates it. That single observation is why Deployments exist.
The common mistake here is treating a bare Pod as a deployment mechanism. It isn’t. A Pod has no self-healing, no rolling updates, and no replica management. Use it to learn, then move on.
Another frequent stumble: forgetting that `kubectl apply -f pod.yaml` needs the file to be valid YAML and valid against the schema. A single misindented line produces an error that points at the wrong place. Editors with YAML linting and the Kubernetes schema installed catch this before it reaches the cluster, and it’s worth the ten minutes of setup.
Deployment Examples: Where Real Work Starts
A Deployment wraps a Pod template in a controller that maintains a desired replica count and handles rolling updates. The canonical example is an nginx Deployment with three replicas.
What a good Deployment example demonstrates:
- Replica management. Kill a Pod and the ReplicaSet creates a replacement within seconds.
- Rolling updates. Change the image tag and Kubernetes replaces Pods gradually, keeping the service available.
- Rollback. `kubectl rollout undo` reverts to the previous revision. This is the feature people forget exists until an incident.
- Label selectors. The Deployment’s `selector.matchLabels` must match the Pod template’s labels, or the API server rejects the manifest outright.
That last point is the most common beginner error with Deployments. The error message is clear enough once you’ve seen it, but the underlying mental model — controllers find their Pods by label, not by name — is the thing worth internalizing. It explains Services, NetworkPolicies, and a dozen other objects later.
A practical tip that isn’t obvious from the docs: always set resource requests and limits in your examples, even toy ones. Without requests, the scheduler makes poor placement decisions. Without limits, one runaway container can starve a node. Examples that omit them teach bad habits that are painful to unlearn in production.
Service Examples: Connecting the Pieces
A Deployment alone is unreachable from outside the cluster. A Service gives a stable virtual IP and DNS name to a set of Pods selected by label.
The three Service types you’ll see in examples behave very differently:
| Type | Reachable from | Typical use |
|---|---|---|
| ClusterIP | Inside the cluster only | Internal service-to-service traffic |
| NodePort | Any node’s IP on a high port | Local testing, simple demos |
| LoadBalancer | Outside, via cloud load balancer | Production ingress on cloud providers |
The classic example pairs a three-replica nginx Deployment with a ClusterIP Service on port 80 targeting port 80 on the Pods. Apply both, then run `kubectl port-forward` to reach it from your laptop — a technique that’s underused and saves you from provisioning a load balancer just to check that something works.
The mistake almost everyone makes: a Service whose `selector` doesn’t match any Pod’s labels. The Service is created successfully, gets an IP, and routes to nothing. No error, no warning. The fix is `kubectl get endpoints ` — if the endpoint list is empty, your selector is wrong. Make that command a reflex.
ConfigMaps and Secrets: Configuration Without Rebuilds
Hardcoding configuration into images is one of the most common anti-patterns in early Kubernetes work. ConfigMaps and Secrets let you inject configuration at runtime.
A solid ConfigMap example shows three consumption patterns: environment variables, command-line arguments, and mounted files. The mounted-file pattern is the one people underuse, and it’s the most powerful — update the ConfigMap and the file inside the container changes (with a delay, and only if your app watches for it).
Kubernetes Secrets need a clear caveat. By default, they are base64-encoded, not encrypted. Anyone with read access to the namespace can recover the values. Examples that present Secrets as a security feature without that caveat are misleading. For data that is truly sensitive, turn on encryption at rest and keep RBAC restrictions tight.
This is also where the operational reality of Kubernetes gets interesting. Platform teams increasingly automate configuration and remediation with agentic tooling; if that’s unfamiliar territory, this explanation of what an AI agent is, with examples and applications, is a reasonable starting point for understanding what those systems can and can’t do.
Persistent Storage and Stateful Examples
Stateless examples are easy. Stateful ones are where Kubernetes examples get genuinely instructive.
A PersistentVolumeClaim example paired with a Pod shows the binding process: the claim requests storage, a volume binds to it, and the Pod mounts it. Delete the Pod and the data survives — if the reclaim policy says so. That conditional is the whole lesson.
For databases, StatefulSets matter. They give Pods stable identities and ordered startup, which matters when replica three needs replica one to exist first. A three-replica example with a headless Service demonstrates stable DNS names per Pod. It’s more complex than a Deployment, and that complexity is the point: stateful workloads need guarantees that stateless ones don’t.
The common mistake: assuming a PersistentVolumeClaim guarantees durability. It doesn’t. Reclaim policies, storage class behavior, and backup strategy are all separate concerns, and examples rarely emphasize that.
Running Examples Locally Without a Cloud Bill
You don’t need a cloud cluster to practice. minikube and kind both run a real Kubernetes control plane on a laptop. Kind (Kubernetes in Docker) is faster to start and popular for CI; minikube has more built-in addons.
A few habits that make local practice stick:
- Use a fresh namespace per example so cleanup is one command.
- Apply manifests from files, not `kubectl run`, so you build the habit of versioning YAML.
- Read the events after anything fails: `kubectl describe pod ` shows scheduling and image-pull errors that logs never will.
- Tear everything down when you’re done. Orphaned resources are how local clusters become unusable.
There’s a broader point about tooling here. Kubernetes has a reputation for creating work rather than removing it, and that reputation isn’t baseless — the operational overhead is real, and teams that adopt it without understanding the cost often struggle. The research on AI creating more work, including studies on tools like ChatGPT and Uber’s engineering experience, makes a similar argument about automation in general: new tooling shifts effort rather than eliminating it.
Common Mistakes That Break Example Manifests
After enough broken applies, patterns emerge. These are the ones that show up again and again:
- Wrong `apiVersion`. Copying a manifest from an old tutorial is the single biggest source of errors. Check the deprecation guide before assuming an example is current.
- Mismatched labels and selectors. Silent failure with Services; hard rejection with Deployments.
- Missing namespace. Applying to `default` when you meant `staging` produces confusing “resource not found” errors.
- Image pull failures. Private registries need image pull secrets; typos in image names look identical to network problems.
- No resource requests. Works fine on a laptop, misbehaves on a shared cluster.
- Assuming `latest` is stable. Pin your image tags in examples. `latest` plus `imagePullPolicy: Always` is a recipe for unpredictable behavior.
Conclusion
Kubernetes examples are not training wheels to be discarded once you “know” the platform. They’re the working vocabulary of the ecosystem — the reason a team can read a manifest and immediately understand what a system does. Start with a Pod, graduate to a Deployment with a Service, then add configuration and storage. Each layer only makes sense once the one beneath it is solid.
The engineers who get comfortable fastest aren’t the ones who read the most documentation. They’re the ones who apply something small, watch it fail, and figure out exactly why. That loop — apply, observe, fix — is the entire skill. The examples are just the entry point.
Frequently Asked Questions
What is the simplest Kubernetes example to start with?
A single Pod running an nginx container. It’s a few lines of YAML, applies in seconds, and demonstrates the core declarative model: you describe desired state and the control plane reconciles it. From there, move to a Deployment so you get replica management and self-healing.
Do I need a cloud cluster to practice Kubernetes examples?
No. Tools like minikube and kind run a real control plane locally on a laptop. Kind is faster to start and common in CI pipelines; minikube offers more addons. Both behave enough like production clusters to teach the fundamentals without any cloud spend.
Why does my Service not route traffic to my Pods?
Almost always a label mismatch. A Service finds Pods through its `selector`, not by name. If the selector doesn’t match the Pods’ labels, the Service is created successfully but has no endpoints. Run `kubectl get endpoints ` — an empty list confirms the selector is wrong.
Which Kubernetes API versions break old examples?
Several have been removed over time, most notably the `extensions/v1beta1` Ingress API in v1.22. Because Kubernetes releases roughly every four months, manifests from older tutorials frequently fail to apply. Always check the current API deprecation guide before reusing an example you found online.
Are Kubernetes Secrets actually secure?
Not by default. Secrets are base64-encoded, which is encoding, not encryption — anyone with read access to the namespace can recover the values. For stronger protection, turn on encryption at rest on the API server, restrict access with RBAC, and consider an external secrets manager for production workloads.
How many replicas should a Deployment example use?
Three is the conventional choice for examples because it demonstrates rolling updates and failure tolerance without wasting resources. In practice, replica count should follow your availability requirements and traffic patterns, not a tutorial default. Two is the practical minimum for zero-downtime rollouts.
