ca

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

Get and rotate the root CA

Arguments

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

---

init

docker.swarm.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)

Arguments

• advertise_address Optional[str]: Advertised address (format: <ip|interface>[:port])
• autolock bool: Enable manager autolocking (requiring an unlock key to start a stopped manager)
• availability str: Availability of the node ("active"|"pause"|"drain")
• data_path_address Optional[str]: Address or interface to use for data path traffic (format is <ip|interface>)

---

join

docker.swarm.join(
    manager_address,
    advertise_address=None,
    availability="active",
    data_path_address=None,
    listen_address=None,
    token=None,
)

Joins a swarm

Arguments

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

---

join_token

docker.swarm.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).

Arguments

• node_type str: "manager" or "worker"
• rotate bool: Rotate join token

---

leave

docker.swarm.leave(force=False)

Leave the swarm

Arguments

• force bool: Force this node to leave the swarm, ignoring warnings

---

unlock

docker.swarm.unlock(key)

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

Arguments:

key: The key to unlock the swarm. The key can be obtained on any manager with docker.swarm.unlock_key().

---

unlock_key

docker.swarm.unlock_key(rotate=False)

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

Arguments

• rotate bool: Rotate the unlock key.

---

update

docker.swarm.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

Arguments

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

---