Skip to content
Velloreth
Developer Tools 7 min read

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

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 describe to 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.

Frequently asked questions

What is a Pod in Kubernetes?
The smallest deployable unit. A Pod holds one or more containers that share a network namespace and can share volumes. Most Pods hold a single container.
What is the difference between a Pod and a Deployment?
A Pod is a single instance. A Deployment manages a set of identical Pods, handles rolling updates, and can roll back. You almost always create a Deployment, not a bare Pod.
What is a Service?
A stable network address for a set of Pods. Pods are ephemeral and their IPs change, so a Service provides a fixed name and load-balances across the matching Pods.
What is a ConfigMap and a Secret?
A ConfigMap holds non-sensitive configuration as key-value pairs. A Secret holds sensitive data. Both can be mounted as files or exposed as environment variables.
Do I need Kubernetes?
For a single-host application, no. A container on a VM, or a managed platform, is simpler. Kubernetes pays off when you have many services, need autoscaling, or must run across multiple machines.
What is a namespace?
A virtual cluster within a Kubernetes cluster, used to separate resources by team, environment, or application. Names are unique within a namespace, not across the cluster.