Swarm Mode Architecture

Relevant source files

• api/types/network/network.go
• api/types/swarm/config.go
• api/types/swarm/secret.go
• api/types/swarm/swarm.go
• daemon/cluster.go
• daemon/cluster/cluster.go
• daemon/cluster/configs.go
• daemon/cluster/convert/config.go
• daemon/cluster/convert/secret.go
• daemon/cluster/convert/swarm.go
• daemon/cluster/filters.go
• daemon/cluster/filters_test.go
• daemon/cluster/helpers.go
• daemon/cluster/listen_addr.go
• daemon/cluster/listen_addr_linux.go
• daemon/cluster/listen_addr_others.go
• daemon/cluster/networks.go
• daemon/cluster/noderunner.go
• daemon/cluster/nodes.go
• daemon/cluster/secrets.go
• daemon/cluster/swarm.go
• daemon/cluster/tasks.go
• daemon/network/filter.go
• daemon/network/filter_test.go
• daemon/server/router/network/backend.go
• daemon/server/router/network/network_routes.go
• integration-cli/daemon/daemon.go
• integration-cli/daemon/daemon_swarm.go
• integration-cli/docker_api_swarm_service_test.go
• integration-cli/docker_api_swarm_test.go
• integration-cli/docker_cli_prune_unix_test.go
• integration-cli/docker_cli_service_create_test.go
• integration-cli/docker_cli_service_health_test.go
• integration-cli/docker_cli_service_logs_test.go
• integration-cli/docker_cli_service_scale_test.go
• integration-cli/docker_cli_swarm_test.go
• integration-cli/docker_cli_swarm_unix_test.go
• vendor/github.com/moby/moby/api/types/network/network.go

This page describes the architecture of Docker Swarm mode within the Moby project, focusing on cluster management, node coordination, SwarmKit integration, and the cluster lifecycle. It covers cluster.go, noderunner.go, swarm.go, listen address detection, and swarm init/join mechanics.

Sources: daemon/cluster/cluster.go1-40 daemon/cluster/swarm.go27-145

SwarmKit Integration Overview

Swarm mode is implemented as a clustering layer that integrates the moby/swarmkit library into the Docker daemon. This integration allows a standalone Docker Engine to participate in a distributed orchestration system.

The Cluster object daemon/cluster/cluster.go113 is a static, configurable entity for accessing swarm-related functionality. It exists regardless of whether swarm mode is enabled. When swarm mode is activated via Init daemon/cluster/swarm.go27 or Join daemon/cluster/swarm.go148 a nodeRunner daemon/cluster/noderunner.go29 is instantiated to manage the underlying SwarmKit node.

Sources: daemon/cluster/cluster.go6-16 daemon/cluster/cluster.go113-123 daemon/cluster/noderunner.go28-41

Core Components

The Cluster Controller

The Cluster struct daemon/cluster/cluster.go113 manages the lifecycle of the swarm participation. It handles initialization, joining, and leaving the cluster, as well as providing access to the SwarmKit gRPC control API.

Field	Type	Description
controlMutex	sync.RWMutex	Protects long-running reconfiguration operations (init/join/leave).
mu	sync.RWMutex	Protects access to the current cluster state and the nodeRunner reference.
nr	*nodeRunner	The active manager for the SwarmKit node. Present only when swarm mode is enabled.
stateDir	string	Directory for persistent swarm state (swarm/).
watchStream	chan *swarmapi.WatchMessage	Channel for passing SwarmKit store notifications to the daemon.

Sources: daemon/cluster/cluster.go113-123 daemon/cluster/cluster.go19-32

NodeRunner Lifecycle

The nodeRunner daemon/cluster/noderunner.go29 is responsible for starting the SwarmKit node and maintaining its connection. It implements a backoff restart loop to handle transient errors and network issues.

Sources: daemon/cluster/cluster.go10-13 daemon/cluster/noderunner.go28-41 daemon/cluster/noderunner.go99-189

Cluster Operations

Initialization and Joining

The Init daemon/cluster/swarm.go27 and Join daemon/cluster/swarm.go148 methods are the entry points for enabling swarm mode. These functions handle address resolution, certificate setup, and the creation of the initial cluster state.

Address Detection and Resolution

Swarm mode requires three primary addresses:

1. Listen Address: The address the gRPC API and gossip protocol listen on (default 0.0.0.0:2377).
2. Advertise Address: The address other nodes use to reach this node.
3. Data Path Address: The address used for the VXLAN overlay data plane.

The daemon attempts to automatically detect these if not provided, using network helpers and system IP inspections.

Sources: daemon/cluster/swarm.go54-96 daemon/cluster/swarm.go162-180 daemon/cluster/cluster.go71

Cluster Lifecycle Diagram

This diagram maps API requests to the internal code entities responsible for cluster reconfiguration.

Sources: daemon/cluster/swarm.go27-30 daemon/cluster/swarm.go148-151 daemon/cluster/cluster.go115 daemon/cluster/noderunner.go99-106

Task Execution and Backend Integration

The swarm agent on each node uses an Executor to manage container lifecycles. This executor communicates with the Docker daemon's backend to create and start containers that represent swarm tasks.

The Container Adapter

The container adapter conducts remote operations for a container by wrapping the daemon's internal backend interfaces.

Key Responsibilities:

• Image Pulling: The adapter calls image backend methods to ensure the required image is present before task execution.
• Network Attachment: It blocks task execution until node network attachments have been allocated by the manager.
• Volume Creation: Ensures cluster-specific volumes are available before container start.

Sources: daemon/cluster/noderunner.go138-143 daemon/cluster/cluster.go89-94

Persistent State

Swarm state is persisted in docker-state.json within the swarm state directory daemon/cluster/cluster.go70 This allows the daemon to resume its role in the cluster automatically upon restart.

• loadPersistentState: Reads the JSON file and reconstructs the nodeStartConfig daemon/cluster/noderunner.go46
• savePersistentState: Serializes the current node configuration (addresses, tokens, etc.) to disk daemon/cluster/cluster.go174 daemon/cluster/noderunner.go176

Sources: daemon/cluster/cluster.go70 daemon/cluster/cluster.go174-180 daemon/cluster/noderunner.go176