Why Docker Swarm organizations are migrating, and why the migration keeps getting deferred
Docker Swarm served its purpose well. For organizations that containerized their infrastructure in 2016–2020, Swarm provided a straightforward orchestration layer on top of Docker Compose: familiar tooling, easy mental model, manageable operational overhead. Many of those environments are still running today, hosting production workloads on Swarm clusters that have been stable and are not obviously broken. The people who built them have often moved on. The decisions baked into the deployment tooling were never properly documented. What was once well-understood infrastructure has become infrastructure that works, but that nobody wants to be responsible for changing.
The migration to Kubernetes is not forced by a production crisis. It is driven by the recognition that Swarm's development is now at a near standstill, the ecosystem has converged decisively on Kubernetes, and the gap in tooling, talent, and integrations continues to widen. The longer the migration is deferred, the harder it becomes to find engineers who understand the Swarm environment well enough to migrate it safely. Many organizations end up in a split state: new workloads going onto a fresh Kubernetes cluster, old workloads staying on Swarm because nobody wants to touch them. That works as a transitional posture, but it is not a destination.
The practical migration challenges are well-documented and consistently underestimated. Replacing the orchestrator is the starting point, not the finish line. Before any production workload moves, every application running on Swarm needs to be validated against Kubernetes: these are architecturally different platforms, and the assumptions your applications make about how containers communicate do not automatically carry across. MacVLAN networking does not translate directly. Services that publish low ports (80, 443) require a load balancer with BGP support in front of them on Kubernetes — Kubernetes does not permit that natively. Service discovery works differently. These are not configuration changes; they are design changes that touch the application layer.
The manifest story is its own workstream. Docker Compose files do not natively deploy to Kubernetes. Every service needs Deployments, Services, ConfigMaps, Ingress objects, and PersistentVolumeClaims written, validated, and version-controlled. CI/CD pipelines need to be rethought, not just reconfigured: the build side remains largely intact, but the delivery side changes fundamentally. Most teams move to GitOps at the same time (deployment driven by a Git repository sync rather than a pipeline stage pushing to a target environment), which means existing CD tooling may end up handling only half of what it used to. Monitoring and alerting need to be rebuilt around Kubernetes primitives: pods, nodes, and namespaces rather than containers and stacks. And underneath all of this is the team upskill — every engineer who touches infrastructure needs a working understanding of how Kubernetes operates, and that takes months to become second nature. A realistic end-to-end migration for a mid-sized Swarm environment typically runs six to twelve months. For larger environments, eighteen months or more is not unusual.
For the Kubernetes target platform, Talos Linux is the recommendation: immutable, API-driven, purpose-built for Kubernetes, with no SSH and a security posture that eliminates entire categories of operational risk that traditional Linux distributions carry. Portainer supports other Kubernetes distributions equally well for organizations with an existing standard.
Portainer D2K is that incremental path. It is a lightweight adapter that deploys to your Kubernetes cluster, understands Docker Compose format, speaks the Docker and Docker Swarm API, and translates deployments to native Kubernetes in real time. Your teams keep deploying as they do today. Your CI/CD pipelines do not change. Your Swarm operational knowledge stays valid while your teams build confidence on the new platform. Migration happens application by application, at whatever pace makes sense.
D2K is designed as a bridge, not as permanent infrastructure. When the last application has made the move to native Kubernetes, D2K comes out. The target environment runs on Talos Linux: declarative, immutable, API-driven, purpose-built for Kubernetes, managed by Portainer Business Edition throughout the migration and in steady-state operation.
What changes in a Swarm to Kubernetes migration, and what stays familiar
docker service scaleWhat Portainer D2K does and how it enables parallel migration
Portainer D2K is a Go-based Docker socket adapter for Kubernetes. It exposes a Docker-compatible API endpoint that Portainer can connect to as if it were connecting to a Docker host, while routing operations to the Kubernetes API server under the hood. The practical effect is that Portainer's Docker and Swarm management interface — the one the operations team already knows — continues to work against the Kubernetes cluster during and after migration.
This matters because the cognitive load of a Swarm-to-Kubernetes migration is not just technical. It is also operational. Asking a team to simultaneously learn Kubernetes, migrate their application stacks, and adapt to a new management interface while maintaining production operations is a significant change management challenge. D2K allows the migration to proceed incrementally — the infrastructure moves to Kubernetes first, the operational interface stays familiar, and the team can adopt Kubernetes-native tooling at their own pace as they become comfortable with the new environment.
Real-world scenarios where this migration pattern is underway
These are industry scenarios illustrating where this migration pattern applies. They are not Portainer customer references.
Production SaaS application stack on Swarm since 2018
SaaS companies that containerized early often have 20–50 Swarm stacks running production workloads, built and maintained by engineers who know Docker well but have limited Kubernetes experience. The migration driver is ecosystem access — modern monitoring, service mesh, GitOps tooling, and Kubernetes Operators that are not available in the Swarm ecosystem. D2K allows the migration to proceed without retraining the operations team on Kubernetes management before the infrastructure is ready.
Internal application platform migrating from legacy Swarm infrastructure
Enterprise IT organizations running internal application platforms on Swarm are migrating as part of broader infrastructure modernization programs. The requirement is a zero-disruption migration path — production workloads cannot have forced downtime during migration, and the operations team cannot be blocked from managing existing workloads while migration is in progress. Parallel operation via D2K and the ability to migrate stack-by-stack satisfies both constraints.
MSPs migrating customer environments from Swarm to Kubernetes
Managed service providers running customer workloads on Swarm clusters face the migration challenge at scale — multiple customer environments, each with different stack configurations, different operational requirements, and different risk tolerances for migration timing. D2K provides a consistent migration toolchain across all customer environments, with the ability to sequence migrations and maintain parallel operation per customer throughout the process.
Industrial Docker Swarm deployments moving to production Kubernetes
Industrial environments that adopted containerization via Docker and Swarm for operational technology workloads — SCADA frontends, historian integrations, OPC-UA adapters — are migrating as their technology vendors begin requiring or recommending Kubernetes. The operational profile in these environments prioritizes stability and low change velocity, making the incremental, parallel-run migration approach that D2K enables particularly well-suited.
How the parallel migration environment is structured
How to execute a Swarm to Kubernetes migration using Portainer and D2K
Provision the Talos Kubernetes cluster
Talos Linux is bootstrapped on the target hardware using talosctl — a declarative configuration that specifies the control plane and worker node configuration, networking, and Kubernetes version. The entire cluster configuration lives in a YAML file that is version-controlled. The cluster is ready for workloads within minutes of hardware provisioning. There is no OS to configure, no SSH to set up, and no baseline security hardening required — Talos's default posture handles all of that.
Deploy D2K and connect the Talos cluster to Portainer
The D2K adapter is deployed inside the Talos Kubernetes cluster as a containerized workload. It exposes a Docker socket-compatible endpoint that Portainer can connect to as a Docker environment. From Portainer's perspective, the Talos cluster appears as a Docker host — the team can manage it using the same Docker and Compose workflows they use on the Swarm environment. Simultaneously, the existing Swarm cluster remains connected to Portainer. Both environments are visible and manageable from the same Portainer instance.
Audit and catalog the Swarm stacks
Before migration begins, all Swarm stacks are cataloged: dependencies, environment variables, volume mounts, secrets, service ports, healthcheck configurations, and inter-service communication patterns. Portainer's stack view provides the current configuration; this catalog becomes the migration checklist. Stacks are prioritized for migration: stateless, low-dependency services migrate first; stateful services with complex networking migrate last, with the most operational care.
Migrate stacks one at a time via D2K
Each Swarm stack's Docker Compose definition is deployed to the Talos Kubernetes cluster via D2K — the Compose file is submitted through Portainer's stack deployment interface targeting the D2K-connected environment. D2K translates the Compose definition to the appropriate Kubernetes manifests automatically. The stack runs on Kubernetes. The team validates it using the same Portainer container management interface they used on Swarm. Traffic is cut over from the Swarm service to the Kubernetes service once validation is complete. The Swarm stack is then decommissioned.
Progressively adopt Kubernetes-native tooling
As stacks are migrated and the team gains familiarity with Kubernetes on Talos, applications can be converted from D2K-managed Compose deployments to native Kubernetes manifests or Helm charts managed directly through Portainer's Kubernetes interface. This progression is optional and can happen at the team's pace — D2K continues to work in steady state for applications that do not need native Kubernetes features. There is no forced cutover from D2K to native Kubernetes tooling.
Decommission the Swarm cluster when migration is complete
Once all production workloads have been migrated to Talos Kubernetes and validated, the Swarm cluster is removed from Portainer's environment list and decommissioned. The entire production estate is now running on Kubernetes, managed by Portainer Business Edition, with Talos Linux as the OS layer. Day-2 operations — Kubernetes version upgrades, Talos OS upgrades, application deployments, RBAC management — all happen through Portainer with the GitOps governance model in place from day one of the migration.
Why this migration approach is lower risk than alternatives
Zero forced downtime — parallel operation throughout
D2K enables both environments to run simultaneously, connected to the same Portainer instance. There is no maintenance window during which both environments are unavailable. Each stack is migrated independently, validated on the Kubernetes side, and cut over at a time the team controls. Workloads that are not yet ready for migration continue running on Swarm unchanged. This is a material risk reduction compared to migration patterns that require a hard cutover date.
The operations team does not need to learn Kubernetes to start migrating
D2K means the team can migrate workloads to Kubernetes using the Docker and Compose interface they already know, managed through the Portainer interface they already use. The learning curve for Kubernetes is decoupled from the migration timeline — the infrastructure moves first, and the team adopts Kubernetes-native patterns at their own pace as they become familiar with the target environment. Migrating infrastructure and simultaneously retraining an operations team is a standard cause of migration project failure; D2K removes that coupling.
Talos is a substantially better operational model than standard Linux + Kubernetes
The most common day-2 failure mode in Kubernetes environments is OS configuration drift — nodes that have drifted from their intended state due to manual intervention, package updates, or configuration changes accumulating over time. Talos's immutable OS model eliminates drift by design. The OS cannot be modified interactively; all changes are declarative and version-controlled. An organization migrating from Swarm to Kubernetes via Talos gets a Kubernetes environment that is structurally more maintainable than most standard Linux-based Kubernetes deployments, not just equivalent to Swarm.
Docker Compose knowledge is not discarded
The team's expertise in writing and managing Compose-based service definitions is directly usable in the Kubernetes environment through D2K. As the team gains familiarity with Kubernetes, they can progressively replace Compose-managed workloads with native Kubernetes manifests through Portainer — but that progression is optional and can happen at their own pace. The migration timeline is gated on application readiness and operational capacity, not on Kubernetes expertise.
Start your Swarm to Kubernetes migration
D2K deploys inside your Kubernetes cluster in minutes and connects to Portainer immediately. You can have both your Swarm and Kubernetes environments visible in the same management interface the same day. The migration can start as soon as the first application is ready to move. Talk to a solutions engineer about your Swarm estate, what the stack audit looks like, and how to sequence the migration to keep production stable throughout.
Frequently asked questions
Direct answers to questions about migrating from Docker Swarm to Kubernetes with Portainer D2K.
What is Portainer D2K and what does it do?
Portainer D2K (Docker to Kubernetes) is a translation tool that converts Docker Compose stack definitions into Kubernetes manifests. It reads the Compose files used in an existing Swarm deployment and generates the equivalent Kubernetes Deployments, Services, ConfigMaps, Secrets, PersistentVolumeClaims, and Ingress resources. The output is production-ready Kubernetes YAML that deploys directly through Portainer to a Talos Linux cluster.
Does migrating from Docker Swarm to Kubernetes require downtime?
No, not with the parallel-run approach. The Kubernetes target environment runs alongside the existing Swarm deployment. Stacks are migrated one at a time, validated in Kubernetes, and only cut over when confirmed stable. The Swarm environment continues running throughout the migration and is only decommissioned after every stack has been successfully migrated and validated.
Why is Talos Linux recommended as the migration target?
Talos Linux is an immutable, API-driven operating system designed specifically for Kubernetes. It has no SSH access, no package manager, and no mutable runtime state, which dramatically reduces the attack surface compared to a conventional Linux distribution running Kubernetes. Cluster lifecycle management (upgrades, node additions, configuration changes) is handled entirely through the Talos API, which Portainer integrates with directly.
Can Portainer manage the Swarm environment and the Kubernetes target simultaneously during migration?
Yes. Both the existing Swarm environment and the new Talos Linux Kubernetes cluster are registered as separate environments in Portainer. The same management interface, the same RBAC policies, and the same GitOps tooling apply to both. There is no need to operate two separate management tools during the transition period.
What happens to Docker Compose stacks that use Swarm-specific features?
Swarm-specific directives (deploy, replicas, update_config, placement constraints) are translated by D2K into their Kubernetes equivalents: Deployments with replica counts, rolling update strategies, and node affinity rules. Stacks that use Swarm secrets are translated to Kubernetes Secrets. Where a direct translation is not possible, D2K flags the specific directive for manual review before migration proceeds.
How long does a Docker Swarm to Kubernetes migration take with Portainer D2K?
Timeline depends on the number of stacks and their complexity. Simple Compose stacks translate and validate in hours. Complex multi-service stacks with custom networking, persistent volumes, and external integrations require more validation time. The parallel-run approach means the migration does not need to be completed in a single window: stacks can be migrated on whatever schedule the operations team chooses.