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.
- 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.
|
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 10 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. |