docker swarm

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

PARAMETER	DESCRIPTION
`ca_certificate`	Path to the PEM-formatted root CA certificate to use for the new cluster TYPE: `Optional[ValidPath]` DEFAULT: `None`
`ca_key`	Path to the PEM-formatted root CA key to use for the new cluster TYPE: `Optional[ValidPath]` DEFAULT: `None`
`certificate_expiry`	Validity period for node certificates TYPE: `Union[int, timedelta, None]` DEFAULT: `None`
`detach`	Exit immediately instead of waiting for the root rotation to converge. The function will return `None`. TYPE: `bool` DEFAULT: `False`
`external_ca`	Specifications of one or more certificate signing endpoints TYPE: `Optional[str]` DEFAULT: `None`
`rotate`	Rotate the swarm CA - if no certificate or key are provided, new ones will be generated. TYPE: `bool` DEFAULT: `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)

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

join

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

Joins a swarm

PARAMETER	DESCRIPTION
`manager_address`	The address of the swarm manager in the format `"{ip}:{port}"` TYPE: `str`
`advertise_address`	Advertised address (format: [:port]) TYPE: `Optional[str]` DEFAULT: `None`
`availability`	Availability of the node (`"active"`\|`"pause"`\|`"drain"`) TYPE: `str` DEFAULT: `'active'`
`data_path_address`	Address or interface to use for data path traffic (format: ) TYPE: `Optional[str]` DEFAULT: `None`
`listen_address`	Listen address (format: [:port]) (default 0.0.0.0:2377) TYPE: `Optional[str]` DEFAULT: `None`
`token`	Token for entry into the swarm, will determine if the node enters the swarm as a manager or a worker. TYPE: `Optional[str]` DEFAULT: `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).

PARAMETER	DESCRIPTION
`node_type`	`"manager"` or `"worker"` TYPE: `str`
`rotate`	Rotate join token TYPE: `bool` DEFAULT: `False`

leave

leave(force=False)

Leave the swarm

PARAMETER	DESCRIPTION
`force`	Force this node to leave the swarm, ignoring warnings TYPE: `bool` DEFAULT: `False`

unlock

unlock(key)

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

PARAMETER	DESCRIPTION
`key`	The key to unlock the swarm. The key can be obtained on any manager with `docker.swarm.unlock_key()`. TYPE: `str`

unlock_key

unlock_key(rotate=False)

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

PARAMETER	DESCRIPTION
`rotate`	Rotate the unlock key. TYPE: `bool` DEFAULT: `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

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