docker service

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.

PARAMETER	DESCRIPTION
`image`	The image to use as the base for the service. TYPE: `str`
`command`	The command to execute in the container(s). TYPE: `Optional[List[str]]`

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

PARAMETER	DESCRIPTION
`filters`	If you want to filter the results based on a given condition. For example, `docker.service.list(filters=dict(label="my_label=hello"))`. TYPE: `Dict[str, str]` DEFAULT: `{}`

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.

PARAMETER	DESCRIPTION
`service`	The service to get the logs of TYPE: `ValidService`
`details`	Show extra details provided to logs TYPE: `bool` DEFAULT: `False`
`since`	Use a datetime or timedelta to specify the lower date limit for the logs. TYPE: `Union[None, datetime, timedelta]` DEFAULT: `None`
`tail`	Number of lines to show from the end of the logs (default all) TYPE: `Optional[int]` DEFAULT: `None`
`timestamps`	Put timestamps next to lines. TYPE: `bool` DEFAULT: `False`
`follow`	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. TYPE: `bool` DEFAULT: `False`
`stream`	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. TYPE: `bool` DEFAULT: `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

PARAMETER	DESCRIPTION
`x`	One or more services (can be id, name or `python_on_whales.Service` object.) TYPE: `Union[ValidService, List[ValidService]]`

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

PARAMETER	DESCRIPTION
`services`	One or a list of services to remove. TYPE: `Union[ValidService, List[ValidService]]`

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.

PARAMETER	DESCRIPTION
`new_scales`	Mapping between services and the desired scales. For example you can provide `new_scale={"service1": 4, "service2": 8}` TYPE: `Dict[ValidService, int]`
`detach`	If True, does not wait for the services to converge and return immediately. TYPE: `bool` DEFAULT: `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

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

Raises

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