ServiceCLI

create

create(image, command, cap_add=[], cap_drop=[], constraints=[], detach=False, dns=[], dns_options=[], dns_search=[], endpoint_mode=None, entrypoint=None, envs={}, env_files=[], generic_resources=[], groups=[], healthcheck=True, health_cmd=None, health_interval=None, health_retries=None, health_start_period=None, health_timeout=None, hosts={}, hostname=None, init=False, isolation=None, labels={}, limit_cpu=None, limit_memory=None, limit_pids=None, log_driver=None, network=None, restart_condition=None, restart_max_attempts=None, secrets=[], mounts=[])

Creates a Docker swarm service.

Consider using 'docker stack deploy' instead as it's idempotent and easier to read for complex applications. docker stack deploy is basically docker compose for swarm clusters.

Parameters:

Name	Type	Description	Default
`image`	`str`	The image to use as the base for the service.	required
`command`	`Optional[List[str]]`	The command to execute in the container(s).	required

exists

exists(x)

Verify that a service exists.

It's just calling docker.service.inspect(...) and verifies that it doesn't throw a python_on_whales.exceptions.NoSuchService.

Returns

A `bool`

inspect

inspect(x)

Returns one or a list of python_on_whales.Service object(s).

Raises

`python_on_whales.exceptions.NoSuchService` if one of the services
doesn't exists.

list

list(filters={})

Returns the list of services

Parameters:

Name	Type	Description	Default
`filters`	`Dict[str, str]`	If you want to filter the results based on a given condition. For example, `docker.service.list(filters=dict(label="my_label=hello"))`.	`{}`

Returns

A `List[python_on_whales.Services]`

logs

logs(service, details=False, since=None, tail=None, timestamps=False, follow=False, raw=False, task_ids=True, resolve=True, truncate=True, stream=False)

Returns the logs of a service as a string or an iterator.

Parameters:

Name	Type	Description	Default
`service`	`ValidService`	The service to get the logs of	required
`details`	`bool`	Show extra details provided to logs	`False`
`since`	`Union[None, datetime, timedelta]`	Use a datetime or timedelta to specify the lower date limit for the logs.	`None`
`tail`	`Optional[int]`	Number of lines to show from the end of the logs (default all)	`None`
`timestamps`	`bool`	Put timestamps next to lines.	`False`
`follow`	`bool`	If `False` (the default), the logs returned are the logs up to the time of the function call. If `True`, the logs of the container up to the time the service is stopped (removed) are displayed. Which is why you must use the `stream` option if you use the `follow` option. Without `stream`, only a `str` will be returned, possibly much later in the future (maybe never if the service is never removed). So this option is not possible (You'll get an error if you use follow and not stream). With `stream`, you'll be able to read the logs in real time and stop whenever you need.	`False`
`stream`	`bool`	Similar to the `stream` argument of `docker.run()`. This function will then returns and iterator that will yield a tuple `(source, content)` with `source` being `"stderr"` or `"stdout"`. `content` is the content of the line as bytes. Take a look at the user guide to have an example of the output.	`False`

Returns

`str` if `stream=False` (the default), `Iterable[Tuple[str, bytes]]`
if `stream=True`.

Raises

`python_on_whales.exceptions.NoSuchService` if the service does not exists.

ps

ps(x)

Returns the list of swarm tasks associated with this service.

You can pass multiple services at once at this function.

from python_on_whales import docker

tasks = docker.service.ps("my-service-name")
print(tasks[0].desired_state)
# running

Parameters:

Name	Type	Description	Default
`x`	`Union[ValidService, List[ValidService]]`	One or more services (can be id, name or `python_on_whales.Service` object.)	required

Returns

`List[python_on_whales.Task]`

Raises

`python_on_whales.exceptions.NoSuchService` if one of the services
doesn't exist.

remove

remove(services)

Removes a service

Parameters:

Name	Type	Description	Default
`services`	`Union[ValidService, List[ValidService]]`	One or a list of services to remove.	required

Raises

`python_on_whales.exceptions.NoSuchService` if one of the services
doesn't exist.

rollback

rollback()

Not yet implemented

scale

scale(new_scales, detach=False)

Scale one or more services.

Parameters:

Name	Type	Description	Default
`new_scales`	`Dict[ValidService, int]`	Mapping between services and the desired scales. For example you can provide `new_scale={"service1": 4, "service2": 8}`	required
`detach`	`bool`	If True, does not wait for the services to converge and return immediately.	`False`

Raises

`python_on_whales.exceptions.NoSuchService` if one of the services
doesn't exists.

update

update(service, detach=False, force=False, image=None, with_registry_authentication=False, quiet=False, replicas=None)

Update a service

More options coming soon

Parameters:

Name	Type	Description	Default
`service`	`ValidService`	The service to update	required
`detach`	`bool`	Exit immediately instead of waiting for the service to converge	`False`
`force`	`bool`	Force update even if no changes require it	`False`
`image`	`Optional[str]`	Service image tag	`None`
`with_registry_authentication`	`bool`	Send registry authentication details to swarm agents	`False`

Raises

`python_on_whales.exceptions.NoSuchService` if the service doesn't exists.