Skip to content
Blog

Migrating from Swarm or Nomad to Kubernetes: A Playbook

A step-by-step migration playbook — inventory, service-to-Deployment translation, secrets, networks, storage, probes, progressive cutover with dual-run, CI/CD rework, and team enablement — plus the honest reasons not to migrate at all.

Published on • November 15, 2026

AI Assistant

Migrating an orchestrator is not a lift-and-shift; it is a translation of your platform’s vocabulary. Kubernetes is “a system for automating deployment, scaling, and management of containerized applications” (kubernetes.io) — but your Swarm stack or Nomad job file encodes assumptions about networking, secrets, health, and scheduling that do not map one-to-one. Teams that treat it as find-and-replace end up with a cluster running their containers and none of their guarantees. This playbook walks the migration in order: inventory what you have, translate each construct deliberately, cut over progressively so rollback stays one DNS change away, rework the pipeline, grow the team — and, before all of that, an honest check on whether you should migrate at all.

Step 0: “Don’t migrate if…”

Say this out loud before starting:

  • Your current orchestrator meets every requirement you actually have. If a single Swarm host with restart: unless-stopped serves your traffic and your pain is something else (CI speed, observability), Kubernetes solves the wrong problem.
  • The driver is résumé-driven or vendor-driven. Migrating because “everyone runs K8s” produces a cluster nobody wants to own. Migrating for a concrete gap — multi-tenancy, GPU scheduling, a required operator — produces a project with a definition of done.
  • You cannot fund the parallel-run period. A migration with a hard cutover date and no dual-running budget is an outage with extra steps.
  • State is undocumented. If nobody knows which volumes, cron outputs, or manual fixes live on the current cluster, fix that first; the orchestrator is not the problem.

If those boxes are unchecked but the migration is still justified (real multi-host needs, a genuine feature gap, an org standard), proceed.

Step 1: Inventory and dependency mapping

Freeze features and export everything you have. For Swarm: docker service ls, docker service inspect, docker config ls, docker secret ls, plus docker stack config -c docker-compose.yml to normalize the compose file. For Nomad: the job HCL files, nomad job inspect, Consul service registrations, and any Nomad variables. Build one spreadsheet with a row per workload:

WorkloadTypeReplicasDataDepends onExternal exposureHealthOwner
apilong-running3nonedb, redis:443 via TraefikHTTP /healthzteam-web
workerlong-running2nonedb, redis—queue depthteam-core
billing-reportscheduled1S3db—exit codeteam-core
postgresstateful1volume pgdata—:5432 internalpg_isreadyteam-core

The data and external exposure columns are where migrations actually fail; everything else is mechanical. Also record every manual snowflake: a docker exec runbook step, a file edited on the host, an env var changed without a commit.

Step 2: Translate the workload model

Swarm → Deployments and Services

A Swarm service with replicas: 3 becomes a Deployment (replica management, rolling updates) plus a ClusterIP Service (stable DNS name). Key mappings:

SwarmKubernetes
replicas: Nspec.replicas: N in a Deployment
deploy.resources.limits/memoryresources.limits (requests too — set both)
deploy.update_config: parallelism/orderDeployment strategy: RollingUpdate (maxSurge/maxUnavailable)
deploy.restart_policyDeployment + node-level restart; the controller replaces the policy
healthcheck:livenessProbe + readinessProbe (+ startupProbe for slow boots)
depends_on: condition: service_healthyNot a K8s feature — use startupProbe/init containers, or fix the app to wait on DNS
env: / configs: / secrets:envFrom ConfigMap / Secret, or mounted files
networks: front overlayService DNS; NetworkPolicy for isolation
ports: "80:80" publish modeService type + Ingress/Gateway; hostPort only when unavoidable
deploy.placement.constraintsNode affinity / nodeSelector / taints

A representative translation:

# Swarm service deploy config → Kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: shop
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate: { maxSurge: 1, maxUnavailable: 0 }
  selector:
    matchLabels: { app: api }
  template:
    metadata:
      labels: { app: api }
    spec:
      containers:
        - name: api
          image: registry.example.com/shop/api:1.4.2
          ports: [{ containerPort: 3000 }]
          envFrom:
            - configMapRef: { name: api-config }
            - secretRef: { name: api-secrets }
          resources:
            requests: { cpu: 100m, memory: 128Mi }
            limits: { cpu: "1", memory: 512Mi }
          startupProbe:
            httpGet: { path: /healthz, port: 3000 }
            failureThreshold: 30
            periodSeconds: 5
          readinessProbe:
            httpGet: { path: /healthz, port: 3000 }
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata: { name: api, namespace: shop }
spec:
  selector: { app: api }
  ports: [{ port: 80, targetPort: 3000 }]

Note the deliberate changes: requests appear alongside limits (scheduling uses requests; omitting them is the classic Swarm-migrant mistake), and maxUnavailable: 0 reproduces the zero-downtime intent of a careful Swarm update.

Nomad → Deployments, DaemonSets, CronJobs

Nomad’s model maps more cleanly because it already separates job types: type = "service" → Deployment, type = "system" → DaemonSet, type = "batch" → Job, type = "periodic" → CronJob. Translate constraint/affinity blocks to nodeSelector/affinity, task resources to container resources, and groups with network mode host + dynamic ports to Services (port = "http" { to = 8080 } becomes containerPort + service.port). Nomad’s update { max_parallel, canary } maps onto Deployment maxUnavailable plus a proper canary strategy in your pipeline (Argo Rollouts if you want native canary traffic-splitting).

Step 3: Secrets, config, and storage

Secrets are the highest-risk translation. Swarm secrets and Nomad variables are delivered as files at runtime with reasonable defaults; Kubernetes Secrets are base64-encoded Secret objects in etcd — not encrypted at rest unless you configure it. Choose deliberately:

  • Start with kubectl create secret generic --from-literal / sealed-secrets (Sealed Secrets encrypts with a cluster public key so secrets can live in git).
  • Grow into External Secrets Operator or Secrets Store CSI Driver backed by Vault, AWS Secrets Manager, or Azure Key Vault — this is the closest equivalent to “one credential store, many workloads” that Swarm/Nomad teams already had via Consul/Vault.
  • Never bake secrets into images or ConfigMaps, and rotate everything that was ever in a compose file committed to git.

Storage: named volumes map to PersistentVolumes with a StorageClass. On a single-node migration target, local-path-provisioner (Rancher) reproduces the local-driver behavior of a Swarm volume; on cloud, pick the CSI driver for your platform (EBS, PD, ANZ) so volumes survive node loss. Anything with real durability requirements becomes a StatefulSet (stable identity, ordered ops), not a Deployment with a volume attached. Plan data movement explicitly: pg_dump/restore, rsync between old volume and PVC, or dual-write — and do the data move before cutover, then verify row counts.

Step 4: Networking and ingress

Swarm’s routing mesh and a Traefik/Swarm combo become an Ingress controller (NGINX, Traefik — you can keep Traefik and swap its provider to Kubernetes, which cuts relearning) or the Gateway API. Overlay-network service discovery (http://api on the overlay) becomes cluster DNS: api.shop.svc.cluster.local, or just api inside the same namespace. Check three things early: internal service-to-service calls that used overlay DNS still resolve; anything that relied on host networking or published host ports gets a Service or LoadBalancer; and east-west traffic that Swarm left flat now needs NetworkPolicy rules if you want segmentation (it is not on by default — install a CNI that supports it, Calico or Cilium).

Step 5: Healthchecks → probes

Swarm’s single healthcheck gates restarts and depends_on; Kubernetes splits the concept and you must fill all three roles:

  • startupProbe — protects slow-starting containers from being killed by liveness (the equivalent of Swarm’s start_period).
  • readinessProbe — controls Service endpoint membership; this is your load-shedding lever.
  • livenessProbe — restarts a wedged container. Over-eager liveness (httpGet / with short timeouts) causes restart loops; test an endpoint that means “the process is alive,” not “the database is reachable.”

Replace depends_on chains with probes and idempotent startup: if the app requires the database, make it retry on connection (good practice anyway) or gate it with an init container.

Step 6: Progressive cutover (dual-run, strangler)

Do not switch traffic in one motion. Use the strangler pattern:

  1. Stand up the new stack alongside the old one, serving no production traffic. Same images, new orchestration.
  2. Shadow or mirror traffic where feasible (Ingress can duplicate requests to both backends) or route a canary host (beta.example.com) to the new stack.
  3. Move one service at a time, lowest-risk first (static frontends, then stateless APIs, then workers, then stateful). Keep the old service running but idle after each move — the rollback plan is “point DNS back.”
  4. Cut the data last and once. For stateful services: stop writes on old, sync, start writes on new, verify, decommission. Dual-write only if you can tolerate the consistency bugs it introduces.
  5. Decommission cleanly. A migration that leaves the old Swarm running “just in case” for a year means you are operating two platforms — delete the old stack after a defined bake period (typically 2–4 weeks).

Track progress as a burn-down of the inventory spreadsheet; “done” means every row has a Kubernetes owner and the old cluster is off.

Step 7: CI/CD rework

Your pipeline’s deploy step changes shape but not philosophy:

  • Build stays: docker buildx build --push with immutable tags (consider docker/metadata-action for git-SHA tags).
  • Manifests: start with plain YAML + kustomize overlays (base + overlays/staging + overlays/prod); move to Helm only if you need templated values across many environments.
  • Deploy: kubectl apply -k overlays/staging is enough to start; graduate to GitOps — Argo CD or Flux watching the repo — which gives you drift detection and audit trails your auditor will like, and replaces the “SSH and run a script” step.
  • Progressive delivery: Argo Rollouts or Flagger for canaries with metric-based promotion, once basic rolling updates are boring.
  • Pipeline gates: image vulnerability scan before push (fail on critical CVEs), kubeconform/kubectl --dry-run=server validation in CI, and a smoke-test job that runs against the new revision before traffic moves.

Step 8: Team enablement

The migration fails socially before it fails technically. Budget for: kubectl and debugging fundamentals (get/describe/logs/exec/port-forward) for everyone on call; a shared runbook for the top 10 incidents (CrashLoopBackOff, ImagePullBackOff, Pending pods, PVC stuck, ingress 502s); namespaces + RBAC so teams stop sharing a default namespace; and one person who goes deeper (CKA-level knowledge is a reasonable target, formal certification optional). Run at least one game day on the new cluster — deliberately break something and fix it together — before the old orchestrator is decommissioned.

When it’s worth it

Done this way, a migration of a dozen services takes one to three months of calendar time, most of it spent on data, networking, and pipeline work rather than YAML. The payoff is real when you needed what Kubernetes actually adds: horizontal autoscaling, hard multi-tenancy, a scheduling model for heterogeneous workloads, or an ecosystem of operators you can adopt later. If you migrated for any other reason, the honest move is to keep the receipt and re-read Step 0.

References