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¶
- get_unlock_key()¶
Get the unlock key for this Swarm manager.
- Returns
A
dict
containing anUnlockKey
member
- 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, likeeth0: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, likeeth0: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
default_addr_pool (list of str) – Default Address Pool specifies default subnet pools for global scope networks. Each pool should be specified as a CIDR block, like ‘10.0.0.0/8’. Default: None
subnet_size (int) – SubnetSize specifies the subnet size of the networks created from the default subnet pool. Default: None
data_path_addr (string) – Address or interface to use for data path traffic. For example, 192.168.1.1, or an interface, like eth0.
data_path_port (int) – Port number to use for data path traffic. Acceptable port range is 1024 to 49151. If set to
None
or 0, the default port 4789 will be used. Default: Nonetask_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
The ID of the created node.
- Return type
(str)
- 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, default_addr_pool=['10.20.0.0/16], subnet_size=24, 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:
'0.0.0.0:2377
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, likeeth0: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
data_path_addr (string) – Address or interface to use for data path traffic. For example, 192.168.1.1, or an interface, like eth0.
- 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.
- unlock()¶
Unlock a locked swarm.
- Parameters
key (string) – The unlock key as provided by
get_unlock_key()
- Raises
docker.errors.InvalidArgument – If the key argument is in an incompatible format
docker.errors.APIError – If the server returns an error.
- Returns
True if the request was successful.
Example
>>> key = client.api.get_unlock_key() >>> client.unlock_swarm(key)
- update()¶
Update the swarm’s configuration.
It takes the same arguments as
init()
, exceptadvertise_addr
,listen_addr
, andforce_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
.rotate_manager_unlock_key (bool) – Rotate the manager unlock key. 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 callreload()
before calling it again.
- attrs¶
The raw representation of this object from the server.