Kubernetes Basics: Pods, Deployments and Services
Kubernetes orchestrates containers across machines. Learn the core objects, the mental model, and when you do not need it.
By Velloreth
The mental model
Kubernetes is declarative. You describe the desired state, and controllers work continuously to make the actual state match.
# "I want three replicas of this container running"
spec:
replicas: 3
If a Pod crashes, the controller creates a new one. If you change the replica count, it scales. You do not tell Kubernetes what to do; you tell it what you want.
Pods
A Pod is the smallest deployable unit. It holds one or more containers that share a network namespace and can share volumes.
apiVersion: v1
kind: Pod
metadata:
name: web
spec:
containers:
- name: web
image: nginx:1.25
ports:
- containerPort: 80
Most Pods hold a single container. A multi-container Pod is for tightly coupled processes, such as an application and a log shipper that must share a filesystem.
Pods are ephemeral. They are created and destroyed, and their IP addresses change. You rarely create a bare Pod; you create a Deployment.
Deployments
A Deployment manages a set of identical Pods.
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: myapp:1.0
ports:
- containerPort: 3000
resources:
requests:
memory: "128Mi"
cpu: "100m"
limits:
memory: "256Mi"
cpu: "500m"
The selector matches the Pod labels. This is how the Deployment knows which Pods it owns.
Rolling updates. Changing the image triggers a rolling update: new Pods are created and old ones are removed gradually, so there is no downtime.
kubectl set image deployment/web web=myapp:2.0
kubectl rollout status deployment/web
kubectl rollout undo deployment/web
Resources. requests is what the scheduler reserves; limits is the maximum. A container that exceeds its memory limit is killed.
Services
A Service gives a stable address to a set of Pods.
apiVersion: v1
kind: Service
metadata:
name: web
spec:
selector:
app: web
ports:
- port: 80
targetPort: 3000
type: ClusterIP
The selector matches Pod labels. The Service load-balances across the matching Pods.
Types:
- ClusterIP — reachable only inside the cluster. The default.
- NodePort — exposed on each node’s IP at a static port.
- LoadBalancer — provisions a cloud load balancer.
- ExternalName — a DNS alias.
Ingress is the usual way to expose HTTP services, with routing by host and path.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
spec:
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port:
number: 80
ConfigMaps and Secrets
ConfigMap for non-sensitive configuration.
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
LOG_LEVEL: info
API_URL: https://api.example.com
Secret for sensitive data.
apiVersion: v1
kind: Secret
metadata:
name: app-secrets
type: Opaque
stringData:
DATABASE_URL: postgres://user:pass@db:5432/app
Note that a Secret is base64-encoded, not encrypted, by default. Enable encryption at rest, and use a secrets manager for anything sensitive.
Use them as environment variables:
envFrom:
- configMapRef:
name: app-config
- secretRef:
name: app-secrets
Or mount them as files:
volumes:
- name: config
configMap:
name: app-config
volumeMounts:
- name: config
mountPath: /etc/config
The core commands
kubectl apply -f deployment.yaml
kubectl get pods
kubectl get deployments
kubectl get services
kubectl describe pod web-abc123
kubectl logs web-abc123
kubectl logs -f web-abc123
kubectl exec -it web-abc123 -- sh
kubectl delete -f deployment.yaml
kubectl port-forward service/web 8080:80
kubectl describe is the first command to run when something is wrong: it shows events, which usually explain why a Pod is not starting.
Probes
Liveness probe — restarts the container if it fails.
livenessProbe:
httpGet:
path: /healthz
port: 3000
initialDelaySeconds: 10
periodSeconds: 10
Readiness probe — removes the Pod from the Service if it fails, so it receives no traffic.
readinessProbe:
httpGet:
path: /ready
port: 3000
initialDelaySeconds: 5
periodSeconds: 5
Startup probe — for a slow-starting application, so the liveness probe does not kill it prematurely.
The distinction matters: a liveness failure restarts the container, and a readiness failure stops traffic. Using a liveness probe for a dependency check causes restart loops when the dependency is down.
Do you need Kubernetes?
The honest answer for most projects: no.
Kubernetes pays off when:
- You have many services that need to discover each other.
- You need autoscaling based on load.
- You must run across multiple machines for capacity or availability.
- You have a team to operate it.
Kubernetes is overkill when:
- You have one application on one machine.
- A container on a VM, or a managed platform, would do.
- Nobody on the team has operated a cluster.
The complexity is real: networking, storage, RBAC, upgrades, and the debugging of a distributed system. A single-host deployment with Compose is often the right answer, and it can be migrated later.
Common mistakes
Using a bare Pod. A Pod is not rescheduled if its node fails, and it is not updated by a rolling deploy. Use a Deployment.
A liveness probe that checks a dependency. When the dependency is down, the liveness probe fails and Kubernetes restarts the container, which creates a restart loop. Use a readiness probe for a dependency check.
No resource requests. Without a request, the scheduler cannot place the Pod well, and the node can be oversubscribed. Without a limit, one Pod can consume a node’s memory.
A memory limit that is too low. The container is killed with an OOM error, which looks like a crash. Check kubectl describe pod for the reason.
A selector that does not match. A Deployment whose selector does not match its Pod template creates no Pods, and the error is not obvious. The selector must match the template’s labels.
A Service with no endpoints. The Service selector does not match any Pod labels, so the Service has no backends. Check with kubectl get endpoints.
Secrets in a ConfigMap. A ConfigMap is not encrypted and is readable by anyone with access to the namespace. Use a Secret, and enable encryption at rest.
Debugging
A Pod that will not start:
kubectl describe pod <name> # events explain the reason
kubectl logs <name> # application output
kubectl logs <name> --previous # the previous container's output
kubectl describe is the first command to run: the events at the bottom usually explain the problem, whether it is an image pull failure, a missing ConfigMap, or a failed probe.
A Pod that starts and then crashes:
kubectl logs <name> --previous
kubectl get pod <name> -o yaml | grep -A5 lastState
The --previous flag shows the output of the container that crashed, which is where the error is.
A Service that does not respond:
kubectl get endpoints <service>
kubectl get pods --show-labels
If the endpoints list is empty, the selector does not match. Compare the Service selector with the Pod labels.
A shell in a running container:
kubectl exec -it <pod> -- sh
If the image has no shell, use a debug container.
kubectl debug -it <pod> --image=busybox --target=<container>
Practical guidance
- Create Deployments, not bare Pods.
- Use a Service for a stable address.
- Set resource requests and limits.
- Add readiness and liveness probes.
- Use ConfigMaps and Secrets for configuration.
- Use
kubectl describeto debug. - Use Ingress to expose HTTP services.
- Reconsider whether you need it for a single-host application.
For the related guides, see docker-basics-guide and docker-compose-guide. For the broader context, dockerfile-best-practices and ci-cd-pipeline-basics.
Quotable summary
A Pod is the smallest deployable unit and holds one or more containers that share a network and storage, while a Deployment manages a set of identical Pods and handles rolling updates and rollbacks. A Service gives a stable address to a set of Pods, which are otherwise ephemeral and whose IPs change. Kubernetes is declarative: you describe the desired state and the controllers work to reach it. A liveness probe restarts the container on failure and a readiness probe removes the Pod from the Service, so using a liveness probe for a dependency check causes restart loops. For a single-host application, Kubernetes is usually more complexity than the problem requires, and a container on a VM or a managed platform is often the right answer.