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 = 0oyrbhxbqs1t2tw8q6qm1fqz0

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-11-20 11:35:32.791819+00:00

In [7]: super_print(service.updated_at)
type = <class 'datetime.datetime'>, value = 2024-11-20 11:35:32.791819+00:00

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

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:5b0f33c83a97f5f7d12698df6732098b0cdb860d377f6307b68efe2c6821296f

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.