18.3.2.2 Kubernetes Deployment Manifests

Kubernetes Deployment manifests are the resource type most directly comparable to a Swarm service or a scaled Compose service, and understanding their internal anatomy, the ReplicaSet relationship, rolling update strategy fields, and revision history, clarifies behavior that looks similar to Docker-based orchestration on the surface but has its own specific mechanics worth understanding directly rather than assuming a one-to-one equivalence.

The Deployment-to-ReplicaSet relationship

A Deployment does not directly manage pods; it manages a ReplicaSet, which in turn manages the actual pods, and this extra layer of indirection is specifically what enables Kubernetes's rolling update mechanism, since updating a Deployment creates a new ReplicaSet alongside the old one, gradually shifting replica count from the old ReplicaSet to the new one:

kubectl get replicasets

NAME              DESIRED   CURRENT   READY
my-api-7d9f8b     0         0         0
my-api-8c1a2f     3         3         3

Seeing two ReplicaSets here, one scaled to zero and one to the full desired count, is the visible artifact of a completed rolling update; the old ReplicaSet is retained (rather than deleted outright) specifically to support a fast rollback without needing to rebuild it from scratch.

Rolling update strategy fields

The maxSurge and maxUnavailable fields control the rolling update's actual pacing, conceptually similar to Swarm's update parallelism but expressed as relative or absolute amounts above and below the desired replica count rather than a simple parallelism number:

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

maxSurge allows temporarily running more replicas than the desired count while new ones start, and maxUnavailable allows temporarily running fewer than desired while old ones terminate; setting maxUnavailable: 0 specifically ensures full capacity is maintained throughout the entire rollout, at the cost of needing enough spare cluster capacity to support the temporary surge above the normal desired replica count.

Revision history and rollback

Kubernetes retains a configurable number of previous ReplicaSet revisions specifically to support rollback, and the rollback command reverts directly to a specific prior revision without needing to manually reconstruct what that previous configuration actually was:

kubectl rollout history deployment/my-api

kubectl rollout undo deployment/my-api
kubectl rollout undo deployment/my-api --to-revision=3

This is functionally similar to Swarm's own docker service update --rollback, both providing a direct, built-in mechanism to revert to a previous known-good configuration without manual reconstruction, though the specific commands and underlying ReplicaSet-based implementation differ between the two systems.

Selector and label matching pitfalls

A Deployment's selector field must match the labels on its own pod template exactly, and once a Deployment is created, this selector field is generally immutable, which means a mismatch discovered after creation typically requires recreating the Deployment entirely rather than simply editing the existing one:

spec:
  selector:
    matchLabels:
      app: my-api
  template:
    metadata:
      labels:
        app: my-api

A mismatch between these two label sets, easy to introduce when copying and modifying an existing manifest without updating both places consistently, produces a validation error at creation time rather than a subtle, silent misbehavior, which is at least a clear, immediate signal rather than a confusing, delayed symptom.

Distinguishing Deployment from bare Pod or ReplicaSet

Creating a bare Pod directly, without a Deployment managing it, provides no automatic recovery if that pod is deleted or its node fails, which is meaningfully different from the self-healing behavior a Deployment-managed pod has by default; a bare, standalone ReplicaSet provides replica count maintenance and self-healing but lacks the rolling update mechanism a Deployment adds on top:

kubectl run my-api --image=my-api:1.4.2

kind: Deployment

The first command creates a bare pod with no automatic recovery at all if it is deleted; a Deployment is almost always the more appropriate choice for anything resembling a genuine, ongoing service, reserving bare pods for genuinely one-off, throwaway debugging or testing purposes specifically.

Pausing and resuming a rollout

Similar to Swarm's manual pause and resume capability, a Deployment rollout can be paused mid-progress, useful for inspecting an in-progress update before deciding whether to let it continue or roll it back:

kubectl rollout pause deployment/my-api
kubectl rollout resume deployment/my-api

kubectl rollout status deployment/my-api

rollout status blocks and reports progress until the rollout either completes or times out, which is a useful, direct way to confirm a deployment has genuinely finished successfully rather than only appearing to have started without error.

Common mistakes

• Not understanding the Deployment-to-ReplicaSet relationship, missing why old ReplicaSets persist at zero scale after a completed rollout rather than being deleted outright.
• Setting maxUnavailable without considering whether the cluster actually has enough spare capacity to support the corresponding maxSurge during a rollout requiring full availability throughout.
• Introducing a selector-to-label mismatch when copying and modifying an existing manifest, requiring the Deployment to be recreated entirely rather than simply patched.
• Creating bare pods directly for anything resembling an ongoing service, missing the automatic recovery a Deployment provides by default.
• Not using kubectl rollout status to confirm a deployment genuinely completed successfully, assuming success based only on the apply command itself completing without error.

Kubernetes Deployment manifests share conceptual similarity with Swarm services in providing replica management, rolling updates, and rollback, but their actual implementation through the ReplicaSet layer, surge-and-unavailable-based pacing, and immutable selector fields are specific mechanics worth understanding directly rather than assuming a precise, one-to-one behavioral equivalence with familiar Docker-based orchestration concepts.