swarm

The swarm domain has 13 actions. On the meta surface they are all reached through arcane_swarm; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
`swarm.info`	Get swarm info	read
`swarm.init`	Initialize swarm	write
`swarm.join`	Join swarm	write
`swarm.join_candidates`	List environments available for Easy Join	read
`swarm.join_environments`	Join environments to a swarm	write
`swarm.join_tokens`	Get swarm join tokens	read
`swarm.join_tokens_rotate`	Rotate swarm join tokens	destructive
`swarm.leave`	Leave swarm	destructive
`swarm.node_identity`	Get local swarm node identity	read
`swarm.spec_update`	Update swarm spec	destructive
`swarm.status`	Get swarm status	read
`swarm.unlock`	Unlock swarm	destructive
`swarm.unlock_key`	Get swarm unlock key	read

Actions

`swarm.info`

Get swarm info

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "info"
Individual tool: arcane_swarm_info
Arcane route: GET /api/environments/{id}/swarm/info
Operation ID: get-swarm-info
Usage: Swarm manager only: answers 409 ‘Swarm mode is not enabled’ outside a swarm and 403 ‘Swarm manager access required’ on a worker. Returns id, createdAt, updatedAt, rootRotationInProgress and spec (Name, Labels, Orchestration, Raft, Dispatcher, CAConfig, EncryptionConfig.AutoLockManagers, TaskDefaults), the starting point for swarm.spec_update. Join tokens are not included (swarm.join_tokens).
Related actions: swarm.status, swarm.spec_update, swarm.join_tokens, swarm_node.list

`swarm.init`

Initialize swarm

Kind: write
Required parameters: spec
Meta tool: arcane_swarm with "action": "init"
Individual tool: arcane_swarm_init
Arcane route: POST /api/environments/{id}/swarm/init
Operation ID: init-swarm
Usage: Makes this environment’s engine the first manager of a new swarm, and fails with 409 when it is already in one (active, pending or locked) unless forceNewCluster is true. Needs the swarm:init permission. spec is required: pass {} for Docker’s defaults. Duration fields (Dispatcher.HeartbeatPeriod, CAConfig.NodeCertExpiry, …) are integer nanoseconds, as swarm.info returns them. listenAddr defaults to 0.0.0.0:2377. Set advertiseAddr (IP or interface such as eth0) on hosts with several addresses. autoLockManagers, defaultAddrPool (CIDRs), subnetSize and forceNewCluster are optional. Returns nodeId. Add nodes next with swarm.join_environments or swarm.join_tokens + swarm.join.
Related actions: swarm.status, swarm.info, swarm.join_tokens, swarm.join_environments, swarm.leave

`swarm.join`

Join swarm

Kind: write
Required parameters: joinToken, remoteAddrs
Meta tool: arcane_swarm with "action": "join"
Individual tool: arcane_swarm_join
Arcane route: POST /api/environments/{id}/swarm/join
Operation ID: join-swarm
Usage: Joins this environment’s engine (environmentId from environment.list) to an existing swarm with a token: joinToken is the worker or manager token from swarm.join_tokens on the manager’s environment, remoteAddrs the manager address(es) host:2377 (managerAddress in swarm_node.list). listenAddr defaults to 0.0.0.0:2377. advertiseAddr, dataPathAddr and availability are optional. Needs swarm:join, and fails with 409 when the engine is already in a swarm (swarm.leave first). Returns only a message, and the node shows up in swarm_node.list once ready. swarm.join_environments does the same without handling tokens and also binds the node to its environment.
Related actions: swarm.join_tokens, swarm_node.list, swarm.join_environments, swarm.status, environment.list

`swarm.join_candidates`

List environments available for Easy Join

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "join_candidates"
Individual tool: arcane_swarm_join_candidates
Arcane route: GET /api/environments/{id}/swarm/join-candidates
Operation ID: get-swarm-join-candidates
Usage: Call on the manager’s environment to list the Arcane environments swarm.join_environments can add: enabled, visible, not the local environment 0, not the manager itself and not already bound to a node of this swarm. Each item has environmentId, environmentName, environmentType (direct or edge) and status. Empty when the environment is not an active swarm manager. Needs swarm:join on the manager, and only environments where the caller also has swarm:join are listed. A candidate that is already in another swarm is listed but fails to join.
Related actions: swarm.join_environments, swarm.status, environment.list, swarm_node.list

`swarm.join_environments`

Join environments to a swarm

Kind: write
Required parameters: remoteAddrs, targets
Meta tool: arcane_swarm with "action": "join_environments"
Individual tool: arcane_swarm_join_environments
Arcane route: POST /api/environments/{id}/swarm/join-environments
Operation ID: join-swarm-environments
Usage: Easy Join: joins Arcane environments (see swarm.join_candidates) to this environment’s swarm without exposing join tokens, and binds each to its new node. Leave remoteAddrs empty to use the managers’ advertised addresses.
Related actions: swarm.join_candidates, swarm.join

`swarm.join_tokens`

Get swarm join tokens

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "join_tokens"
Individual tool: arcane_swarm_join_tokens
Arcane route: GET /api/environments/{id}/swarm/join-tokens
Operation ID: get-swarm-join-tokens
Usage: Returns the worker and manager join tokens (SWMTKN-…) of the swarm this environment manages, for swarm.join (with managerAddress from swarm_node.list). Treat them as secrets. Manager only (409 outside a swarm, 403 on a worker), and Arcane checks the swarm:unlock permission for this read. Replace leaked tokens with swarm.join_tokens_rotate.
Related actions: swarm.join, swarm.join_tokens_rotate, swarm_node.list

`swarm.join_tokens_rotate`

Rotate swarm join tokens

Kind: destructive — requires confirm: true
Required parameters: none
Meta tool: arcane_swarm with "action": "join_tokens_rotate"
Individual tool: arcane_swarm_join_tokens_rotate
Arcane route: POST /api/environments/{id}/swarm/join-tokens/rotate
Operation ID: rotate-swarm-join-tokens
Usage: With neither rotateWorkerToken nor rotateManagerToken set, both tokens are rotated. Nodes already in the swarm are not affected.
Related actions: swarm.join_tokens

`swarm.leave`

Leave swarm

Kind: destructive — requires confirm: true
Required parameters: none
Meta tool: arcane_swarm with "action": "leave"
Individual tool: arcane_swarm_leave
Arcane route: POST /api/environments/{id}/swarm/leave
Operation ID: leave-swarm
Usage: Takes this environment’s engine out of its swarm (docker swarm leave) and clears Arcane’s swarm flag. It answers 409 when it is not in a swarm. Needs swarm:leave. Docker refuses a manager without force when that would remove the last manager or break quorum, and forcing the last manager discards the swarm’s state. The departed node stays in swarm_node.list as down on the remaining managers until swarm_node.delete removes it.
Related actions: swarm_node.demote, swarm_node.delete, swarm_node.list, swarm.status

`swarm.node_identity`

Get local swarm node identity

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "node_identity"
Individual tool: arcane_swarm_node_identity
Arcane route: GET /api/swarm/node-identity
Operation ID: get-swarm-node-identity
Usage: Not environment-scoped: describes the Docker engine of the Arcane manager answering the request (its local daemon), not a remote environment’s. Returns swarmNodeId, hostname, role (manager or worker, empty outside a swarm), engineVersion and swarmActive. For a given environment use swarm.status or swarm.info.
Related actions: swarm.status, swarm.info, swarm_node.get

`swarm.spec_update`

Update swarm spec

Kind: destructive — requires confirm: true
Required parameters: spec
Meta tool: arcane_swarm with "action": "spec_update"
Individual tool: arcane_swarm_spec_update
Arcane route: PUT /api/environments/{id}/swarm/spec
Operation ID: update-swarm-spec
Usage: Replaces the whole swarm spec: start from swarm.info’s spec, since omitted fields are reset (a left-out duration such as Dispatcher.HeartbeatPeriod becomes 0). Durations are integer nanoseconds, exactly as swarm.info returns them, so its spec can be sent back with only your changes.
Related actions: swarm.info, swarm.unlock_key

`swarm.status`

Get swarm status

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "status"
Individual tool: arcane_swarm_status
Arcane route: GET /api/environments/{id}/swarm/status
Operation ID: get-swarm-status
Usage: Cheap check whether an environment’s engine is in swarm mode: returns only enabled, true for workers as well as managers. It is Arcane’s stored flag, refreshed when Arcane (or the environment’s agent) starts and by swarm.init, swarm.join and swarm.leave, so it can lag changes made with the docker CLI. swarm.info and the other cluster reads additionally need a manager.
Related actions: swarm.info, swarm.init, swarm.join, environment.list

`swarm.unlock`

Unlock swarm

Kind: destructive — requires confirm: true
Required parameters: key
Meta tool: arcane_swarm with "action": "unlock"
Individual tool: arcane_swarm_unlock
Arcane route: POST /api/environments/{id}/swarm/unlock
Operation ID: unlock-swarm
Usage: Unlocks a manager that restarted with autolock on (its swarm state is locked) using key, the SWMKEY-… from swarm.unlock_key read before the restart. environmentId is the locked node’s environment. A wrong key is refused by Docker, an unlocked node answers 409 ‘swarm is not locked’, and a node outside any swarm ‘Swarm mode is not enabled’. Needs swarm:unlock.
Related actions: swarm.unlock_key

`swarm.unlock_key`

Get swarm unlock key

Kind: read
Required parameters: none
Meta tool: arcane_swarm with "action": "unlock_key"
Individual tool: arcane_swarm_unlock_key
Arcane route: GET /api/environments/{id}/swarm/unlock-key
Operation ID: get-swarm-unlock-key
Usage: Returns unlockKey (SWMKEY-…) of the swarm this environment manages. It is empty when autolock is off (turn it on with EncryptionConfig.AutoLockManagers through swarm.spec_update, or autoLockManagers at swarm.init). Manager only, needs swarm:unlock. Store it safely: a restarted autolocked manager stays locked until swarm.unlock (or docker swarm unlock on the host) is given this key.
Related actions: swarm.unlock, swarm.spec_update, swarm.info