9.2 KiB
Swarm management
Starting with Engine version 1.12 (API 1.24), it is possible to manage the engine's associated Swarm cluster using the API.
Initializing a new Swarm
You can initialize a new Swarm by calling Client.init_swarm
. An advertising
address needs to be provided, usually simply by indicating which network
interface needs to be used. Advanced options are provided using the
swarm_spec
parameter, which can easily be created using
Client.create_swarm_spec
.
spec = client.create_swarm_spec(
snapshot_interval=5000, log_entries_for_slow_followers=1200
)
client.init_swarm(
advertise_addr='eth0', listen_addr='0.0.0.0:5000', force_new_cluster=False,
swarm_spec=spec
)
Joining an existing Swarm
If you're looking to have the engine your client is connected to join an
existing Swarm, this can be accomplished by using the Client.join_swarm
method. You will need to provide a list of at least one remote address
corresponding to other machines already part of the swarm as well as the
join_token
. In most cases, a listen_addr
and advertise_addr
for your
node are also required.
client.join_swarm(
remote_addrs=['192.168.14.221:2377'], join_token='SWMTKN-1-redacted',
listen_addr='0.0.0.0:5000', advertise_addr='eth0:5000'
)
Leaving the Swarm
To leave the swarm you are currently a member of, simply use
Client.leave_swarm
. Note that if your engine is the Swarm's manager,
you will need to specify force=True
to be able to leave.
client.leave_swarm(force=False)
Retrieving Swarm status
You can retrieve information about your current Swarm status by calling
Client.inspect_swarm
. This method takes no arguments.
client.inspect_swarm()
Listing Swarm nodes
List all nodes that are part of the current Swarm using Client.nodes
.
The filters
argument allows to filter the results.
client.nodes(filters={'role': 'manager'})
Swarm API documentation
Client.init_swarm
Initialize a new Swarm using the current connected engine as the first node.
Params:
- 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. Ifadvertise_addr
is not specified, it will be automatically detected when possible. Default: None - listen_addr (string): 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
- swarm_spec (dict): Configuration settings of the new Swarm. Use
Client.create_swarm_spec
to generate a valid configuration. Default: None
Returns: True
if the request went through. Raises an APIError
if it
fails.
Client.create_swarm_spec
Create a docker.types.SwarmSpec
instance that can be used as the swarm_spec
argument in Client.init_swarm
.
Params:
- 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
Returns: docker.types.SwarmSpec
instance.
docker.types.SwarmExternalCA
Create a configuration dictionary for the external_ca
argument in a
SwarmSpec
.
Params:
- protocol (string): Protocol for communication with the external CA (currently only “cfssl” is supported).
- url (string): URL where certificate signing requests should be sent.
- options (dict): An object with key/value pairs that are interpreted as protocol-specific options for the external CA driver.
Client.inspect_node
Retrieve low-level information about a Swarm node
Params:
- node_id (string): ID of the node to be inspected.
Returns: A dictionary containing data about this node. See sample below.
{u'CreatedAt': u'2016-08-11T23:28:39.695834296Z',
u'Description': {u'Engine': {u'EngineVersion': u'1.12.0',
u'Plugins': [{u'Name': u'bridge', u'Type': u'Network'},
{u'Name': u'host', u'Type': u'Network'},
{u'Name': u'null', u'Type': u'Network'},
{u'Name': u'overlay', u'Type': u'Network'},
{u'Name': u'local', u'Type': u'Volume'}]},
u'Hostname': u'dockerserv-1.local.net',
u'Platform': {u'Architecture': u'x86_64', u'OS': u'linux'},
u'Resources': {u'MemoryBytes': 8052109312, u'NanoCPUs': 4000000000}},
u'ID': u'1kqami616p23dz4hd7km35w63',
u'ManagerStatus': {u'Addr': u'10.0.131.127:2377',
u'Leader': True,
u'Reachability': u'reachable'},
u'Spec': {u'Availability': u'active', u'Role': u'manager'},
u'Status': {u'State': u'ready'},
u'UpdatedAt': u'2016-08-11T23:28:39.979829529Z',
u'Version': {u'Index': 9}}
Client.inspect_swarm
Retrieve information about the current Swarm.
Returns: A dictionary containing information about the Swarm. See sample below.
{u'CreatedAt': u'2016-08-04T21:26:18.779800579Z',
u'ID': u'8hk6e9wh4iq214qtbgvbp84a9',
u'JoinTokens': {u'Manager': u'SWMTKN-1-redacted-1',
u'Worker': u'SWMTKN-1-redacted-2'},
u'Spec': {u'CAConfig': {u'NodeCertExpiry': 7776000000000000},
u'Dispatcher': {u'HeartbeatPeriod': 5000000000},
u'Name': u'default',
u'Orchestration': {u'TaskHistoryRetentionLimit': 10},
u'Raft': {u'ElectionTick': 3,
u'HeartbeatTick': 1,
u'LogEntriesForSlowFollowers': 500,
u'SnapshotInterval': 10000},
u'TaskDefaults': {}},
u'UpdatedAt': u'2016-08-04T21:26:19.391623265Z',
u'Version': {u'Index': 11}}
Client.join_swarm
Join an existing Swarm.
Params:
- 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, 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
Returns: True
if the request went through. Raises an APIError
if it
fails.
Client.leave_swarm
Leave a Swarm.
Params:
- force (bool): Leave the Swarm even if this node is a manager.
Default:
False
Returns: True
if the request went through. Raises an APIError
if it
fails.
Client.nodes
List Swarm nodes
Params:
- filters (dict): Filters to process on the nodes list. Valid filters:
id
,name
,membership
androle
. Default:None
Returns: A list of dictionaries containing data about each swarm node.
Client.update_node
Update the Node's configuration
Params:
- version (int): The version number of the node object being updated. This is required to avoid conflicting writes.
- node_spec (dict): Configuration settings to update. Any values not provided
will be removed. See the official Docker API documentation for more details.
Default:
None
.
Returns: True
if the request went through. Raises an APIError
if it
fails.
node_spec = {'Availability': 'active',
'Name': 'node-name',
'Role': 'manager',
'Labels': {'foo': 'bar'}
}
client.update_node(node_id='24ifsmvkjbyhk', version=8, node_spec=node_spec)
Client.update_swarm
Update the Swarm's configuration
Params:
- version (int): The version number of the swarm object being updated. This is required to avoid conflicting writes.
- swarm_spec (dict): Configuration settings to update. Use
Client.create_swarm_spec
to generate a valid configuration. Default:None
. - rotate_worker_token (bool): Rotate the worker join token. Default:
False
. - rotate_manager_token (bool): Rotate the manager join token. Default:
False
.
Returns: True
if the request went through. Raises an APIError
if it
fails.