Skip to content

Swarm Cluster

Initialize, join, unlock, and update a Docker Swarm cluster.

Swarm → Cluster lists every agent you can read with its Swarm role (Manager, Worker, or Not initialized) and the cluster ID for managers. Click Inspect on a row to open that agent’s cluster panel.

Use this when an agent isn’t in a Swarm yet. Arcane then includes it in the rest of the Swarm workspace.

  1. Open Swarm → Cluster and click Inspect on the agent.
  2. Optional: under Initialize Cluster, open Advanced settings. The defaults suit a local or single-network cluster.
  3. Click Initialize.
An agent outside a Swarm offers initialization and join options.
The Swarm setup page before a cluster has been initialized.The Swarm setup page before a cluster has been initialized.

An agent outside a Swarm offers initialization and join options.

Advanced settings:

Field What it does
Listen address Address and port the Swarm manager listens on for cluster traffic.
Advertise address Address other nodes use to reach this manager. Set it when the host has several network interfaces.
Swarm spec JSON A full Swarm spec as a JSON object, for settings not covered by the other fields.
Auto-lock managers Encrypts manager data so a restarted manager stays locked until you enter the unlock key.
Force new cluster Creates a new single-manager cluster from this node’s existing Swarm state. Use it to recover a cluster that lost its managers.

To add an agent to a running cluster as a manager or worker:

  1. Open Swarm → Cluster and click Inspect on the agent.
  2. Under Join Existing Cluster, enter the remote manager addresses (comma separated), the join token, and optional listen and advertise addresses.
  3. Click Join.

Easy Join adds other Remote Agents to a manager’s cluster without copying addresses or join tokens.

  1. Click Easy Join on a manager’s row under Swarm → Cluster, or on a Remote Agent’s detail page or row menu.
  2. Select each target. Only enabled, online agents not already linked to a node of this cluster are offered.
  3. For each target, choose worker or manager and an availability mode.
  4. Optional: set listen, advertise, or data-path addresses per target. Blank manager addresses use the ones Arcane finds in the cluster. Any you enter must be reachable from every selected host.
  5. Confirm.

Join tokens are never shown. Each target gets its own result in Join results, and one failure doesn’t undo the others:

Result Meaning
Joined and verified The host joined and Arcane linked the agent to its Swarm node.
Already a member and verified The host was already in this cluster. Arcane linked it without rejoining.
Joined; verification is still pending The host joined, but Arcane couldn’t confirm the node in time. Opening Nodes finishes the link later.

A host active in a different cluster is rejected; Arcane doesn’t force it to leave. Easy Join needs swarm:join on the manager and every target. The Cluster page’s Easy Join button also needs swarm-nodes:list and swarm:unlock on the manager.

In the cluster panel, click Leave Cluster to remove that node. Select Force leave if a normal leave fails.

With Auto-lock managers on, a restarted manager keeps the cluster locked until you unlock it.

  1. Open Swarm → Cluster and click Inspect on a manager.
  2. Enter the unlock key.
  3. Click Unlock.

A manager’s cluster panel shows and can rotate the worker join token, manager join token, and manager unlock key. Treat them like passwords. Rotating one invalidates the old value.

  1. Under Update Swarm Spec, click Load current spec.
  2. Edit the JSON.
  3. Click Update Spec.

Cluster actions need a Swarm manager agent and matching permissions. See Docker Swarm for the rules.