Swarm

Manage Docker Engine’s swarm mode.

To use any swarm methods, you first need to make the Engine part of a swarm. This can be done by either initializing a new swarm with init(), or joining an existing swarm with join().

These methods are available on client.swarm:

class Swarm
init()

Initialize a new swarm on this Engine.

Parameters:
  • advertise_addr (str) –

    Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used.

    If not specified, it will be automatically detected when possible.

  • listen_addr (str) – Listen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the default swarm listening port is used. Default: 0.0.0.0:2377
  • force_new_cluster (bool) – Force creating a new Swarm, even if already part of one. Default: False
  • task_history_retention_limit (int) – Maximum number of tasks history stored.
  • snapshot_interval (int) – Number of logs entries between snapshot.
  • keep_old_snapshots (int) – Number of snapshots to keep beyond the current snapshot.
  • log_entries_for_slow_followers (int) – Number of log entries to keep around to sync up slow followers after a snapshot is created.
  • heartbeat_tick (int) – Amount of ticks (in seconds) between each heartbeat.
  • election_tick (int) – Amount of ticks (in seconds) needed without a leader to trigger a new election.
  • dispatcher_heartbeat_period (int) – The delay for an agent to send a heartbeat to the dispatcher.
  • node_cert_expiry (int) – Automatic expiry for nodes certificates.
  • external_ca (dict) – Configuration for forwarding signing requests to an external certificate authority. Use docker.types.SwarmExternalCA.
  • name (string) – Swarm’s name
  • labels (dict) – User-defined key/value metadata.
  • signing_ca_cert (str) – The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
  • signing_ca_key (str) – The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
  • ca_force_rotate (int) – An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified.
  • autolock_managers (boolean) – If set, generate a key and use it to lock data stored on the managers.
  • log_driver (DriverConfig) – The default log driver to use for tasks created in the orchestrator.
Returns:

True if the request went through.

Raises:

docker.errors.APIError – If the server returns an error.

Example

>>> client.swarm.init(
    advertise_addr='eth0', listen_addr='0.0.0.0:5000',
    force_new_cluster=False, snapshot_interval=5000,
    log_entries_for_slow_followers=1200
)
join()

Make this Engine join a swarm that has already been created.

Parameters:
  • remote_addrs (list) – Addresses of one or more manager nodes already participating in the Swarm to join.
  • join_token (string) – Secret token for joining this Swarm.
  • listen_addr (string) – Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). Default: None
  • advertise_addr (string) – Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used. If AdvertiseAddr is not specified, it will be automatically detected when possible. Default: None
Returns:

True if the request went through.

Raises:

docker.errors.APIError – If the server returns an error.

leave()

Leave a swarm.

Parameters:force (bool) – Leave the swarm even if this node is a manager. Default: False
Returns:True if the request went through.
Raises:docker.errors.APIError – If the server returns an error.
update()

Update the swarm’s configuration.

It takes the same arguments as init(), except advertise_addr, listen_addr, and force_new_cluster. In addition, it takes these arguments:

Parameters:
  • rotate_worker_token (bool) – Rotate the worker join token. Default: False.
  • rotate_manager_token (bool) – Rotate the manager join token. Default: False.
Raises:

docker.errors.APIError – If the server returns an error.

reload()

Inspect the swarm on the server and store the response in attrs.

Raises:docker.errors.APIError – If the server returns an error.
version

The version number of the swarm. If this is not the same as the server, the update() function will not work and you will need to call reload() before calling it again.

attrs

The raw representation of this object from the server.