Core Kubernetes · 04

Deployments and Scaling

1.What is a Deployment ?

A Deployment keeps N identical Pods running for a stateless app. It never creates Pods itself: it owns ReplicaSets, and they own the Pods.

  • One ReplicaSet per Pod template version, named web-<pod-template-hash>.
  • Old ones stay at 0 replicas as revision history (see Rollouts and Probes).
  • Links live in metadata.ownerReferences. Edit the Deployment, not its ReplicaSets.
Deployment webapps/v1, replicas: 3 owns, sets replicas owns, keeps at 0 ReplicaSet web-7c9fcurrent template ReplicaSet web-5d4bprevious template keeps 3 Pods web-7c9f-<random> 0 Pods, old template kept

2.Labels and Selectors

Labels are key/value tags, a selector is a query over them. A ReplicaSet finds its Pods by selector, never by name.

  • Key : optional prefix (DNS subdomain, 253 max), /, name (63 max). kubernetes.io/ and k8s.io/ are reserved.
  • Value : 63 max, may be empty.
  • Match : =, ==, !=, or set-based in, notin, exists (key), not exists (!key).
  • YAML : matchLabels and matchExpressions, all ANDed. No OR.
Deployment selectormatchLabels {app: web} Pod template labels{app: web} mustmatch copied,hash added ReplicaSet selectorapp=web, pod-template-hash=7c9f selects, owns Pod labelsapp=web, pod-template-hash=7c9f Other controllerselector {app: web} not blocked,they fight

A selector the template does not satisfy is rejected. In apps/v1 it is never defaulted and is immutable.

3.A Deployment YAML

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: nginx:1.29
        resources: {requests: {cpu: 100m}}
  • selectorMust match template labels (extras ok). Immutable.
  • replicasDefault 1. Leave out under an HPA.
  • templateA change makes (or reuses) a ReplicaSet.
What brokeWho fixes itYou see
Container crashedkubelet, in place, with backoffRESTARTS climbs, CrashLoopBackOff
Pod deleted or evictedReplicaSet makes a new PodNew name, new IP
Node failedReplicaSet, after node grace + 300s tolerationNothing for about 6 min, then Pods on other nodes
Stray Pod matchesReplicaSet adopts it, deletes extrasBack to replicas

4.Which workload controller ?

ControllerUse it forGives youWatch out
Deployment apps/v1Stateless web apps, APIs, workersInterchangeable Pods, declarative updatesPod names are random. Use a StatefulSet for stable ones
StatefulSet apps/v1Databases, queues, quorum systemsdb-0, db-1, ... : stable DNS, own PVC, in orderYou make the headless Service. PVCs stay
DaemonSet apps/v1Log shippers, node exporters, CNI agentsOne Pod per eligible nodeNo HPA. Control-plane nodes need tolerations
Job batch/v1Migrations, one-off batch runsRuns to completion, backoffLimit 6restartPolicy Never or OnFailure
CronJob batch/v1Backups, nightly reportsA new Job per schedule tickRuns may overlap (Allow). Use spec.timeZone
In short : Deployment owns ReplicaSets, ReplicaSets own Pods by label, kubelet restarts crashes.

1.Scaling by hand

Scaling only edits spec.replicas. No rollout, no new revision.

$ kubectl scale deployment/web --replicas=5

Undone by an apply that sets replicas, or an HPA.

Scale-down : who goes first
  1. Not yet on a node
  2. Pending, Unknown
  3. Not ready
  4. Lower deletion cost
  5. Doubled up on a node
  6. Ready for less time
  7. More restarts
  8. Newer

The first rule that differs decides (v1.37). The cost is the controller.kubernetes.io/pod-deletion-cost annotation: the one sure lever.

2.HorizontalPodAutoscaler

An HPA (autoscaling/v2) edits replicas for you. Every 15s its controller reads metrics and writes the target's /scale.

The mathdesired = ceil( current x metric / target )
4 Pods at 90% CPU, target 70% : ceil(4 x 90 / 70) = ceil(5.14) = 6, kept within min..max.
kubeletevery node Metrics adaptercustom / external metrics scraped 15s custom APIs metrics-serveradd-on serves kube-apiservermetrics.k8s.io/v1beta1 metrics HPA webautoscaling/v2 spec HPA controllerkube-controller-manager sets replicas Deployment web/scale subresource owns ReplicaSet, Podsmore or fewer Pods new load

metrics-server is an add-on that kubeadm does not install, see metrics-server. Custom or external metrics need an adapter, such as KEDA.

3.HPA manifest and defaults

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: {name: web}
spec:
  scaleTargetRef: {apiVersion: apps/v1,
                   kind: Deployment, name: web}
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target: {type: Utilization,
               averageUtilization: 70}
FieldDefaultNote
minReplicas10 needs an Object or External metric (beta)
maxReplicasrequiredAt least minReplicas
metrics80% CPUHighest result wins
scaleUpno wait+100% or +4 Pods per 15s
scaleDown300sHighest pick in that window
tolerance10%Per-HPA field GA in v1.37
sync15skube-controller-manager
On the DeploymentTarget the Deployment, not its ReplicaSet. Leave out replicas or each apply resets it (removing it later can drop to 1 once). Set requests.cpu : 100m, so 70% is 70m.

4.Commands

CommandWhat it does
kubectl create deployment web --image=nginx:1.29 --replicas=3Create one with 3 Pods
kubectl get deploy,rs,pods -l app=web --show-labelsThe whole chain, with pod-template-hash
kubectl get pods -l 'env in (prod, qa)'Set-based selector query
kubectl scale --current-replicas=2 --replicas=3 deployment/webScale only if it is still at 2
kubectl autoscale deployment web --min=2 --max=10 --cpu=70%Make an HPA (--cpu-percent is deprecated)
kubectl get hpa web --watchCurrent vs target metric, replicas
kubectl describe hpa webConditions (ScalingActive, ...) and events
kubectl delete deployment web --cascade=orphanRemove it, keep ReplicaSets and Pods
In short : kubectl scale sets replicas once. An HPA recomputes them every 15s from metrics.