Docker services

Services in Docker swarm

Don't use the constructor directly. Instead use

from python_on_whales import docker

my_docker_service = docker.service.inspect("my-service")

my_docker_service = docker.service.create("busybox", ["ping", "www.google.com"])

For type hints, use this

from python_on_whales import Service

def print_creation_time(some_service: Service):
    print(some_service.created_at)

Attributes

It attributes are the same that you get with the command line: docker service inspect ...

To get a complete description of those attributes, you can take a look at the daemon api reference page and click on "200 No error".

An example is worth many lines of descriptions.

In [1]: from python_on_whales import docker

In [2]: docker.swarm.init()

In [3]: my_service = docker.service.create("busybox", ["ping", "www.google.com"])

In [4]: def super_print(obj):
   ...:     print(f"type = {type(obj)}, value = {obj}")
   ...:

In [4]: super_print(service.id)
type = <class 'str'>, value = wo852sz0lgo9w7g0nupmw4nkn

In [5]: super_print(service.version)
type = <class 'python_on_whales.components.service.models.ServiceVersion'>, value = index=11

In [6]: super_print(service.created_at)
type = <class 'datetime.datetime'>, value = 2024-09-06 10:23:47.018427+00:00

In [7]: super_print(service.updated_at)
type = <class 'datetime.datetime'>, value = 2024-09-06 10:23:47.018427+00:00

In [8]: super_print(service.spec.name)
type = <class 'str'>, value = dreamy_bell

In [9]: super_print(service.spec.labels)
type = <class 'dict'>, value = {}

In [10]: super_print(service.spec.mode)
type = <class 'dict'>, value = {'Replicated': {'Replicas': 1}}

In [11]: super_print(service.spec.update_config)
type = <class 'python_on_whales.components.service.models.ChangeConfig'>, value = parallelism=1 failure_action='pause' monitor=5000000000 max_failure_ratio=0.0 order='stop-first'

In [12]: super_print(service.spec.rollback_config)
type = <class 'python_on_whales.components.service.models.ChangeConfig'>, value = parallelism=1 failure_action='pause' monitor=5000000000 max_failure_ratio=0.0 order='stop-first'

In [13]: super_print(service.spec.task_template.container_spec.image)
type = <class 'str'>, value = busybox:latest@sha256:34b191d63fbc93e25e275bfccf1b5365664e5ac28f06d974e8d50090fbb49f41

In [14]: super_print(service.spec.task_template.container_spec.labels)
type = <class 'NoneType'>, value = None

In [15]: super_print(service.spec.task_template.container_spec.privileges)
type = <class 'NoneType'>, value = None

In [16]: super_print(service.spec.task_template.container_spec.stop_grace_period)
type = <class 'int'>, value = 10000000000

In [17]: super_print(service.spec.task_template.container_spec.isolation)
type = <class 'str'>, value = default

In [18]: super_print(service.spec.task_template.container_spec.env)
type = <class 'NoneType'>, value = None

In [19]: super_print(service.spec.task_template.resources.limits)
type = <class 'python_on_whales.components.service.models.CPUMemoryQuotas'>, value = nano_cpus=None memory_bytes=None

In [20]: super_print(service.spec.task_template.resources.reservations)
type = <class 'python_on_whales.components.service.models.CPUMemoryQuotas'>, value = nano_cpus=None memory_bytes=None

In [21]: super_print(service.previous_spec)
type = <class 'NoneType'>, value = None

In [22]: super_print(service.endpoint.spec)
type = <class 'python_on_whales.components.service.models.ServiceEndpointSpec'>, value = mode=None ports=None

In [23]: super_print(service.endpoint.ports)
type = <class 'NoneType'>, value = None

In [24]: super_print(service.endpoint.virtual_ips)
type = <class 'NoneType'>, value = None

In [25]: super_print(service.update_status)
type = <class 'NoneType'>, value = None

Methods

Service

exists

exists()

Returns True if the service is still present in the swarm, False if the service has been removed.

ps

ps()

Returns the list of tasks of this service.

remove

remove()

Removes this service

It's also possible to use a service as a context manager. By using a context manager, you ensures that the service will be removed even if an exception occurs.

from python_on_whales import docker

docker.swarm.init()
with docker.service.create("ubuntu", ["sleep", "infinity"]) as my_service:
    print("I'm doing things with the service here")
    print(my_service.update_status)

print("I'm out of the context manager, the service has been removed.")

scale

scale(new_scale, detach=False)

Change the scale of a service.

See the docker.service.scale command for information about the arguments.

update

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

Updates a service

See the docker.service.update command for information about the arguments.