create

docker.service.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,
)

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.

Arguments:

image: The image to use as the base for the service. command: The command to execute in the container(s).

exists

docker.service.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

docker.service.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

docker.service.list()

Returns the list of services

Returns

A List[python_on_whales.Services]

logs

docker.service.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.

Arguments

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

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

docker.service.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

Arguments

  • x Union[str, python_on_whales.Service, List[Union[str, python_on_whales.Service]]]: One or more services (can be id, name or python_on_whales.Service object.)

Returns

List[python_on_whales.Task]

Raises

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

remove

docker.service.remove(services)

Removes a service

Arguments

  • services Union[str, python_on_whales.Service, List[Union[str, python_on_whales.Service]]]: One or a list of services to remove.

Raises

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

rollback

docker.service.rollback()

Not yet implemented

scale

docker.service.scale(new_scales, detach=False)

Scale one or more services.

Arguments

  • new_scales Dict[Union[str, python_on_whales.Service], int]: Mapping between services and the desired scales. For example you can provide new_scale={"service1": 4, "service2": 8}
  • detach bool: If True, does not wait for the services to converge and return immediately.

Raises

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

update

docker.service.update(service, detach=False, force=False, image=None, with_registry_authentication=False)

Update a service

More options coming soon

Arguments

  • service Union[str, python_on_whales.Service]: The service to update
  • detach bool: Exit immediately instead of waiting for the service to converge
  • force bool: Force update even if no changes require it
  • image Optional[str]: Service image tag
  • with_registry_authentication bool: Send registry authentication details to swarm agents

Raises

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