Services

Manage services on a swarm. For more information about services, see the Engine documentation.

Before you can use any of these methods, you first need to join or initialize a swarm.

Methods available on client.services:

class ServiceCollection
create(image, command=None, **kwargs)

Create a service. Similar to the docker service create command.

Parameters

  • image (str) – The image name to use for the containers.

  • command (list of str or str) – Command to run.

  • args (list of str) – Arguments to the command.

  • constraints (list of str) – Placement constraints.

  • preferences (list of tuple) – Placement preferences.

  • maxreplicas (int) – Placement maxreplicas or (int) representing maximum number of replicas per node.

  • platforms (list of tuple) – A list of platform constraints expressed as (arch, os) tuples.

  • container_labels (dict) – Labels to apply to the container.

  • endpoint_spec (EndpointSpec) – Properties that can be configured to access and load balance a service. Default: None.

  • env (list of str) – Environment variables, in the form KEY=val.

  • hostname (string) – Hostname to set on the container.

  • init (boolean) – Run an init inside the container that forwards signals and reaps processes

  • isolation (string) – Isolation technology used by the service’s containers. Only used for Windows containers.

  • labels (dict) – Labels to apply to the service.

  • log_driver (str) – Log driver to use for containers.

  • log_driver_options (dict) – Log driver options.

  • mode (ServiceMode) – Scheduling mode for the service. Default:None

  • mounts (list of str) – Mounts for the containers, in the form source:target:options, where options is either ro or rw.

  • name (str) – Name to give to the service.

  • networks (list) – List of network names or IDs or NetworkAttachmentConfig to attach the service to. Default: None.

  • resources (Resources) – Resource limits and reservations.

  • restart_policy (RestartPolicy) – Restart policy for containers.

  • secrets (list of SecretReference) – List of secrets accessible to containers for this service.

  • stop_grace_period (int) – Amount of time to wait for containers to terminate before forcefully killing them.

  • update_config (UpdateConfig) – Specification for the update strategy of the service. Default: None

  • rollback_config (RollbackConfig) – Specification for the rollback strategy of the service. Default: None

  • user (str) – User to run commands as.

  • workdir (str) – Working directory for commands to run.

  • tty (boolean) – Whether a pseudo-TTY should be allocated.

  • groups (list) – A list of additional groups that the container process will run as.

  • open_stdin (boolean) – Open stdin

  • read_only (boolean) – Mount the container’s root filesystem as read only.

  • stop_signal (string) – Set signal to stop the service’s containers

  • healthcheck (Healthcheck) – Healthcheck configuration for this service.

  • hosts (dict) – A set of host to IP mappings to add to the container’s hosts file.

  • dns_config (DNSConfig) – Specification for DNS related configurations in resolver configuration file.

  • configs (list) – List of ConfigReference that will be exposed to the service.

  • privileges (Privileges) – Security options for the service’s containers.

  • cap_add (list) – A list of kernel capabilities to add to the default set for the container.

  • cap_drop (list) – A list of kernel capabilities to drop from the default set for the container.

  • sysctls (dict) – A dict of sysctl values to add to the container

Returns

The created service.

Return type

Service

Raises

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

get(service_id, insert_defaults=None)

Get a service.

Parameters

  • service_id (str) – The ID of the service.

  • insert_defaults (boolean) – If true, default values will be merged into the output.

Returns

The service.

Return type

Service

Raises

  • docker.errors.NotFound – If the service does not exist.

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

  • docker.errors.InvalidVersion – If one of the arguments is not supported with the current API version.

list(**kwargs)

List services.

Parameters

filters (dict) – Filters to process on the nodes list. Valid filters: id, name , label and mode. Default: None.

Returns

The services.

Return type

list of Service

Raises

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

Service objects

class Service

A service.

id

The ID of the object.

short_id

The ID of the object, truncated to 12 characters.

name

The service’s name.

version

The version number of the service. 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.

force_update()

Force update the service even if no changes require it.

Returns

True if successful.

Return type

bool

logs(**kwargs)

Get log stream for the service. Note: This method works only for services with the json-file or journald logging drivers.

Parameters

  • details (bool) – Show extra details provided to logs. Default: False

  • follow (bool) – Keep connection open to read logs as they are sent by the Engine. Default: False

  • stdout (bool) – Return logs from stdout. Default: False

  • stderr (bool) – Return logs from stderr. Default: False

  • since (int) – UNIX timestamp for the logs staring point. Default: 0

  • timestamps (bool) – Add timestamps to every log line.

  • tail (string or int) – Number of log lines to be returned, counting from the current end of the logs. Specify an integer or 'all' to output all log lines. Default: all

Returns

Logs for the service.

Return type

generator

reload()

Load this object from the server again and update attrs with the new data.

remove()

Stop and remove the service.

Raises

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

scale(replicas)

Scale service container.

Parameters

replicas (int) – The number of containers that should be running.

Returns

True if successful.

Return type

bool

tasks(filters=None)

List the tasks in this service.

Parameters

filters (dict) – A map of filters to process on the tasks list. Valid filters: id, name, node, label, and desired-state.

Returns

List of task dictionaries.

Return type

list

Raises

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

update(**kwargs)

Update a service’s configuration. Similar to the docker service update command.

Takes the same parameters as create().

Raises

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