DevOps, CI/CD & Containers

Kubernetes Fundamentals: Cluster Architecture, Pods, Deployments and Services

Intermediate8 min readUpdated

Kubernetes replaces a pile of deployment scripts with a control loop: you declare the state you want and the cluster works continuously to match it. This guide explains the components that make that loop run, the core objects you will use every day — Pods, ReplicaSets, Deployments, Services, ConfigMaps and Secrets — and ends with a complete manifest for a real application plus the kubectl commands to operate it.

What you will learn

  • Describe the control plane and node components and what each is responsible for
  • Explain the reconciliation loop and why Kubernetes configuration is declarative
  • Create Deployments and understand the Pod and ReplicaSet layers beneath them
  • Expose workloads with Services and resolve them through cluster DNS
  • Supply configuration and secrets to containers without rebuilding images
  • Use labels, selectors and namespaces to organise and select objects

Once an application is packaged as a container image, a new question appears: what runs it? On one machine, a restart policy and a script are enough. Across a fleet, you need something that decides which machine each container runs on, restarts it when it dies, moves it when a node fails, replaces the old version with a new one without dropping traffic, and gives other services a stable way to find it. That job is orchestration, and Kubernetes has become the standard answer.

What makes Kubernetes unusual is not the feature list but the model. You do not tell it to start a container; you record the state you want in the cluster's database, and a set of controllers works continuously to make reality match. Grasping that one idea makes the rest of the system — including its error messages — far easier to read. This guide builds up from the architecture to a complete, working manifest, assuming you already know what an image is from the Docker fundamentals guide.

How a cluster is put together

A cluster is a control plane plus a set of worker nodes.

The control plane runs four components. The API server is the front door: everything — kubectl, controllers, the kubelets on every node — talks to it over an authenticated REST API, and nothing talks to anything else. etcd is the key-value store holding all cluster state; if you back up one thing, back up etcd. The scheduler watches for Pods with no assigned node and picks one, based on resource requests, node labels, taints and affinity rules. The controller manager runs the reconciliation loops: the Deployment controller, the node controller, the job controller and dozens more, each watching objects of one kind and acting on differences. On a managed cluster you never see these processes; on a self-managed one they usually run as static Pods on dedicated machines, in odd numbers for etcd quorum.

Each worker node runs three things. The kubelet is the agent that talks to the API server, receives the Pods assigned to its node, tells the container runtime to start them, and reports status back. The container runtime — containerd or CRI-O in current clusters, since Docker's shim was removed in 1.24 — actually pulls images and runs containers. kube-proxy programmes the node's network rules so that traffic to a Service's virtual IP reaches one of the Pods behind it.

Add a CNI plugin (Calico, Cilium, Flannel and others) that gives every Pod a routable IP, and CoreDNS running as a workload to resolve Service names, and you have a cluster.

The reconciliation loop

Every controller runs the same loop: observe the current state through the API server, compare it with the desired state recorded in the object's spec, and take one step towards closing the gap. Nothing is a one-off command.

This is why Kubernetes objects have a spec (what you want) and a status (what is true right now), and why the answer to "why is my Pod not running" is nearly always found by reading the status and the events attached to it. Delete a Pod that belongs to a Deployment and a replacement appears within seconds — not because deleting triggered a creation, but because a controller noticed one fewer Pod than the spec asks for.

It is also why configuration is declarative. You write YAML describing the end state and apply it:

kubectl apply -f k8s/           # create or update everything in the directory
kubectl diff -f k8s/            # what would change, before it changes
kubectl delete -f k8s/

kubectl apply records the configuration you supplied, so applying a modified file removes fields you dropped and leaves fields managed by other actors alone. Imperative commands (kubectl create deployment, kubectl scale, kubectl edit) exist and are useful for exploration, but production configuration belongs in files under version control — the same argument that applies to infrastructure as code generally.

Pods

A Pod is the smallest thing Kubernetes schedules. It holds one or more containers that share a network namespace — one IP address, one port space, so they reach each other on localhost — and can share volumes. Containers in a Pod are always placed on the same node and live and die together.

Most Pods have one application container. The second container, when there is one, is a helper: a log forwarder reading a shared volume, a service-mesh proxy intercepting traffic, an agent refreshing a credential file.

apiVersion: v1
kind: Pod
metadata:
  name: shop-api
  labels:
    app: shop-api
spec:
  containers:
    - name: api
      image: registry.example.com/acme/shop-api:1.4.2
      ports:
        - containerPort: 8080
      env:
        - name: SPRING_PROFILES_ACTIVE
          value: "prod"

You should almost never create a Pod like this. A bare Pod is not recreated if its node dies — nothing owns it. Pods are cattle, created and destroyed by controllers, and their names, IP addresses and lifetimes are all ephemeral. Anything that must persist goes in a volume; anything that must be reachable goes behind a Service.

Deployments and ReplicaSets

A ReplicaSet keeps a specified number of Pods matching a template alive. A Deployment owns ReplicaSets and manages transitions between them, which is what gives you versioned rollouts and rollback.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
  labels: { app: shop-api }
spec:
  replicas: 3
  selector:
    matchLabels:
      app: shop-api
  template:
    metadata:
      labels:
        app: shop-api
        version: "1.4.2"
    spec:
      containers:
        - name: api
          image: registry.example.com/acme/shop-api:1.4.2
          ports:
            - containerPort: 8080

The selector tells the Deployment which Pods it owns; the template is the Pod it stamps out. They must agree — the template's labels have to satisfy the selector — and the selector is immutable after creation, so choose a stable label such as app rather than something that changes per release.

Change the image tag and re-apply, and the Deployment creates a second ReplicaSet, scales it up as the new Pods become ready, and scales the old one down. kubectl rollout status deployment/shop-api follows the progress; kubectl rollout undo returns to the previous ReplicaSet. The details of how gradual that is — surge, unavailability, readiness gating — are covered in the Kubernetes patterns guide.

Two other workload controllers exist for different shapes: DaemonSet runs exactly one Pod per node (log agents, node exporters), and StatefulSet gives Pods stable identities and their own storage (databases, brokers).

Labels, selectors and namespaces

Kubernetes has no hierarchy of objects. Instead, everything is tagged with labels — arbitrary key/value pairs — and other objects find what they need with selectors. A Service finds its Pods by selector, a Deployment owns its Pods by selector, and you query by selector too:

kubectl get pods -l app=shop-api
kubectl get pods -l 'environment in (staging,prod),tier!=batch'
kubectl label pod shop-api-7c9f-2k4x debug=true      # add a label on the fly

That last trick is worth remembering: change a Pod's labels so the Service selector no longer matches, and the Pod is removed from load balancing while continuing to run. You can then attach a debugger to a misbehaving instance without users hitting it, and the Deployment will start a replacement to keep the replica count.

Use annotations for non-identifying metadata — a build URL, a checksum, configuration for an ingress controller. Selectors ignore them.

Namespaces partition a cluster: names must be unique within a namespace, and quotas, RBAC rules and network policies apply per namespace. Typical divisions are per team or per environment when environments share a cluster. Cluster-wide objects — nodes, PersistentVolumes, StorageClasses — live outside namespaces.

kubectl create namespace staging
kubectl config set-context --current --namespace=staging   # stop typing -n
kubectl get all -n staging

Services and how traffic finds a Pod

Pod IPs change constantly. A Service provides a stable virtual IP and DNS name in front of a set of Pods selected by label, and load-balances across the ones that are ready.

apiVersion: v1
kind: Service
metadata:
  name: shop-api
spec:
  type: ClusterIP
  selector:
    app: shop-api
  ports:
    - name: http
      port: 80          # the Service port
      targetPort: 8080  # the container port

Four types matter:

TypeWhat it gives youTypical use
ClusterIPA virtual IP reachable only inside the clusterService-to-service calls. The default.
NodePortThe same, plus a high port open on every nodeBare-metal clusters, quick demos
LoadBalancerA NodePort plus a cloud load balancer with an external IPPublic entry points on managed clusters
Headless (clusterIP: None)No virtual IP; DNS returns the Pod IPs directlyStatefulSets, client-side load balancing

Inside the cluster, CoreDNS resolves shop-api within the same namespace, and shop-api.staging.svc.cluster.local from anywhere. So the connection string in another service's configuration is simply http://shop-api/, and it keeps working through every restart, rescheduling and rollout.

Exposing many HTTP services through one address is a job for an Ingress or the newer Gateway API rather than a LoadBalancer per service, which is covered in the patterns guide.

Configuration and secrets

Images should be identical across environments; only configuration differs. ConfigMaps hold non-sensitive configuration, Secrets hold credentials, and both can be surfaced as environment variables or as files.

apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-api-config
data:
  SPRING_PROFILES_ACTIVE: "prod"
  application.yaml: |
    shop:
      currency: EUR
      catalogue:
        page-size: 50
---
apiVersion: v1
kind: Secret
metadata:
  name: shop-api-db
type: Opaque
stringData:
  username: "shop"
  password: "correct-horse-battery-staple"

stringData lets you write plain values that the API server base64-encodes on the way in — much easier to review than pre-encoded blobs. Consume them in the Pod spec:

envFrom:
  - configMapRef:
      name: shop-api-config
env:
  - name: SPRING_DATASOURCE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: shop-api-db
        key: password
volumeMounts:
  - name: config
    mountPath: /config
    readOnly: true

Mounting as a file has a useful property: updates to the ConfigMap propagate into the running container within a minute or two, so an application that watches its configuration file can pick up changes without a restart. Environment variables, by contrast, are fixed at container start — changing a ConfigMap does not restart anything, which is why teams add a checksum annotation to the Pod template so an update rolls the Deployment.

Do not commit Secret manifests with real values to Git. Use Sealed Secrets, the External Secrets Operator or your cloud's secret manager, and enable encryption at rest for etcd.

A complete manifest

Everything above, for one service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
  namespace: staging
  labels: { app: shop-api }
spec:
  replicas: 3
  selector:
    matchLabels: { app: shop-api }
  template:
    metadata:
      labels: { app: shop-api }
      annotations:
        config-checksum: "8f4c1a9e"
    spec:
      serviceAccountName: shop-api
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
      containers:
        - name: api
          image: registry.example.com/acme/shop-api:1.4.2
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 8080
          envFrom:
            - configMapRef: { name: shop-api-config }
          env:
            - name: SPRING_DATASOURCE_PASSWORD
              valueFrom:
                secretKeyRef: { name: shop-api-db, key: password }
            - name: POD_NAME
              valueFrom:
                fieldRef: { fieldPath: metadata.name }
          volumeMounts:
            - { name: config, mountPath: /config, readOnly: true }
            - { name: tmp, mountPath: /tmp }
      volumes:
        - name: config
          configMap: { name: shop-api-config }
        - name: tmp
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: shop-api
  namespace: staging
spec:
  selector: { app: shop-api }
  ports:
    - { name: http, port: 80, targetPort: http }

Note targetPort: http referring to the container's named port — rename the port later and the Service follows. fieldRef injects cluster metadata into the container, which is how applications learn their own Pod name for logging. And emptyDir for /tmp is what lets the container filesystem be mounted read-only later without breaking libraries that need scratch space.

Working with kubectl

A dozen commands cover normal operations.

kubectl get pods -o wide                       # with node and IP
kubectl get deploy,svc,cm -n staging
kubectl describe pod shop-api-7c9f-2k4x        # spec, status and events
kubectl logs -f deploy/shop-api                # follow one Pod of the Deployment
kubectl logs shop-api-7c9f-2k4x --previous     # the crashed container's logs
kubectl exec -it shop-api-7c9f-2k4x -- sh
kubectl port-forward svc/shop-api 8080:80      # reach a ClusterIP from your laptop
kubectl rollout status deploy/shop-api
kubectl rollout undo deploy/shop-api
kubectl scale deploy/shop-api --replicas=5
kubectl get events --sort-by=.lastTimestamp    # what the cluster has been doing
kubectl top pods                               # live CPU and memory, needs metrics-server

When something is wrong, the order that solves it fastest is: get pods to see the phase, describe pod to read the events at the bottom, logs --previous if it is crash-looping. The phase usually names the problem directly — ImagePullBackOff (wrong tag or missing registry credential), CrashLoopBackOff (the process exits; read the logs), Pending (nothing can schedule it; the events say whether it is resources, a taint or an unbound volume), CreateContainerConfigError (a referenced ConfigMap or Secret key does not exist).

Key takeaways

  • The control plane — API server, etcd, scheduler, controller manager — records desired state and runs the loops that reconcile reality with it; kubelet, the container runtime and kube-proxy do the work on each node.
  • Everything is declarative: write the spec, apply it, and read status and events when the result differs from what you expected.
  • A Pod is the scheduling unit and is disposable; Deployments own ReplicaSets which own Pods, giving you rollouts, rollback and self-healing.
  • Labels and selectors are how objects find each other, and namespaces partition names, quotas and access.
  • Services provide a stable virtual IP and DNS name in front of ready Pods; ClusterIP for internal traffic, LoadBalancer for cloud entry points, headless for stable per-Pod addressing.
  • ConfigMaps and Secrets keep configuration out of images; mounted files can update live, environment variables cannot, and Secrets need encryption at rest and tight RBAC.
  • get, describe, logs --previous and events diagnose almost everything, and the Pod phase usually names the fault outright.

Sources and further reading

Frequently asked questions

Do I need Kubernetes for my application?
Not necessarily. Kubernetes pays for itself when you run many services, need self-healing across machine failures, deploy frequently with zero downtime, or want a uniform platform several teams share. For one or two services on a single server it adds a large amount of machinery and a genuinely steep learning curve. A managed cluster reduces the operational cost but not the conceptual one.
Why a Pod rather than just a container?
A Pod is a group of containers that share a network namespace, an IP address and optionally volumes, and that are always scheduled onto the same node. That grouping lets a helper container — a log shipper, a proxy, a credential refresher — run alongside the application and reach it on localhost. Most Pods contain exactly one application container plus, occasionally, one helper.
What is the difference between a Deployment and a ReplicaSet?
A ReplicaSet keeps a fixed number of identical Pods running. A Deployment manages ReplicaSets over time: when you change the Pod template it creates a new ReplicaSet, scales it up while scaling the old one down, and keeps the previous ones for rollback. You almost always create Deployments and let them own the ReplicaSets, which is why you rarely write a ReplicaSet by hand.
Are Kubernetes Secrets actually secret?
By default they are base64-encoded, not encrypted, and anyone who can read Secrets in a namespace can read their values. They are better than an environment variable in a manifest because access is controlled by RBAC and they are not baked into images, but a serious setup adds encryption at rest in etcd, tight RBAC, and often an external secret manager synchronised into the cluster.