SwarmCLI

ca

ca(ca_certificate=None, ca_key=None, certificate_expiry=None, detach=False, external_ca=None, rotate=False)

Get and rotate the root CA

Parameters:

Name	Type	Description	Default
`ca_certificate`	`Optional[ValidPath]`	Path to the PEM-formatted root CA certificate to use for the new cluster	`None`
`ca_key`	`Optional[ValidPath]`	Path to the PEM-formatted root CA key to use for the new cluster	`None`
`certificate_expiry`	`Union[int, timedelta, None]`	Validity period for node certificates	`None`
`detach`	`bool`	Exit immediately instead of waiting for the root rotation to converge. The function will return `None`.	`False`
`external_ca`	`Optional[str]`	Specifications of one or more certificate signing endpoints	`None`
`rotate`	`bool`	Rotate the swarm CA - if no certificate or key are provided, new ones will be generated.	`False`

init

init(advertise_address=None, autolock=False, availability='active', data_path_address=None, data_path_port=None, listen_address=None)

Initialize a Swarm.

If you need the token to join the new swarm from another node, use the docker.swarm.join_token function.

A example of how to initialize the whole swarm without leaving the manager if the manager has ssh access to the workers:

from python_on_whales import docker, DockerClient

worker_docker = DockerClient(host="ssh://worker_linux_user@worker_hostname")
# Here the docker variable is connected to the local daemon
# worker_docker is a connected to the Docker daemon of the
# worker through ssh, useful to control it without login to the machine
# manually.
docker.swarm.init()
my_token = docker.swarm.join_token("worker")  # you can set manager too
worker_docker.swarm.join("manager_hostname:2377", token=my_token)

Parameters:

Name	Type	Description	Default
`advertise_address`	`Optional[str]`	Advertised address (format: `<ip\|interface>[:port]`)	`None`
`autolock`	`bool`	Enable manager autolocking (requiring an unlock key to start a stopped manager)	`False`
`availability`	`str`	Availability of the node ("active"\|"pause"\|"drain")	`'active'`
`data_path_address`	`Optional[str]`	Address or interface to use for data path traffic (format is `<ip\|interface>`)	`None`
`listen_address`	`Optional[str]`	address upon which the node listens for inbound swarm manager traffic (format: `<ip\|interface>[:port]`)	`None`

join

join(manager_address, advertise_address=None, availability='active', data_path_address=None, listen_address=None, token=None)

Joins a swarm

Parameters:

Name	Type	Description	Default
`manager_address`	`str`	The address of the swarm manager in the format `"{ip}:{port}"`	required
`advertise_address`	`Optional[str]`	Advertised address (format: [:port])	`None`
`availability`	`str`	Availability of the node (`"active"`\|`"pause"`\|`"drain"`)	`'active'`
`data_path_address`	`Optional[str]`	Address or interface to use for data path traffic (format: )	`None`
`listen_address`	`Optional[str]`	Listen address (format: [:port]) (default 0.0.0.0:2377)	`None`
`token`	`Optional[str]`	Token for entry into the swarm, will determine if the node enters the swarm as a manager or a worker.	`None`

join_token

join_token(node_type, rotate=False)

Obtains a token to join the swarm

This token can then be used with docker.swarm.join("manager:2377", token=my_token).

Parameters:

Name	Type	Description	Default
`node_type`	`str`	`"manager"` or `"worker"`	required
`rotate`	`bool`	Rotate join token	`False`

leave

leave(force=False)

Leave the swarm

Parameters:

Name	Type	Description	Default
`force`	`bool`	Force this node to leave the swarm, ignoring warnings	`False`

unlock

unlock(key)

Unlock a swarm after the --autolock parameter was used and the daemon restarted.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key to unlock the swarm. The key can be obtained on any manager with `docker.swarm.unlock_key()`.	required

unlock_key

unlock_key(rotate=False)

Gives you the key needed to unlock the swarm after a manager daemon reboot.

Parameters:

Name	Type	Description	Default
`rotate`	`bool`	Rotate the unlock key.	`False`

update

update(autolock=None, cert_expiry=None, dispatcher_heartbeat=None, external_ca=None, max_snapshots=None, snapshot_interval=None, task_history_limit=None)

Update the swarm configuration

Parameters:

Name	Type	Description	Default
`autolock`	`Optional[bool]`	Change manager autolocking setting	`None`
`cert_expiry`	`Optional[timedelta]`	Validity period for node certificates, default is `datetime.timedelta(days=90)`. If `int`, it's a number of seconds.	`None`
`dispatcher_heartbeat`	`Optional[timedelta]`	Dispatcher heartbeat period.	`None`
`external_ca`	`Optional[str]`	Specifications of one or more certificate signing endpoints	`None`
`max_snapshots`	`Optional[int]`	Number of additional Raft snapshots to retain	`None`
`snapshot_interval`	`Optional[int]`	Number of log entries between Raft snapshots (default 10000)	`None`
`task_history_limit`	`Optional[int]`	Task history retention limit (default 5)	`None`