.. _scheduler-tags-reference:

==============
Scheduler tags
==============

The Debusine scheduler matches tasks and workers using sets of required and
provided tags: a task can be assigned to a worker if the worker provides all
the tags that the task requires.

This is a reference documentation of well known tags that can be used for
matching. Tags are freeform strings, and site admins and workspace admins are
free to add custom ones to provides and requires.

See :ref:`development-blueprints-tag-based_scheduling` for the design
background for this feature.

Worker-provided tag ontologies
------------------------------

Tags provided by workers
========================

.. _scheduler-tags-worker-build-arch:

``worker:build-arch``
~~~~~~~~~~~~~~~~~~~~~

Describe the build architectures supported in the worker.

* ``worker:build-arch:{name}``: the worker supports the given build
  architecture.

``name`` is an architecture name as used in Debian, like ``amd64``, ``arm64``,
``ppc64el``, and so on.

.. _scheduler-tags-worker-cap:

``worker:cap``
--------------

Describe relevant capabilities available in the worker:

* ``worker:cap:{name}``: the worker has the named capability.

``name`` could be the name of an installed package, the name of a suite of
packages providing a significant feature, or the name of an available hardware
feature.

Other capabilities in actual use:

* ``worker:cap:autopkgtest``: autopkgtest is available
* ``worker:cap:debsign``: debsign is available
* ``worker:cap:mmdebstrap``: mmdebstrap is available
* ``worker:cap:sbsign``: sbsign is available
* ``worker:cap:sbuild``: mmdebstrap is available

Examples of possible capabilities: ``qemu``, ``dev-kvm``, ``gpu``,
``worker-type:worker``, ``task:worker:sbuild:version:1``, and so on.

.. _scheduler-tags-worker-executor:

``worker:executor``
-------------------

Describe the executor backends available in the worker.

* ``worker:executor:{name}``: the given executor is available for use in the
  worker.

``name`` can take values from the ``debusine.tasks.models.BackendType`` enum
except for ``auto``.

Example executor names: ``unshare``, ``incus-lxc``, ``incus-vm`` and ``qemu``.


.. _scheduler-tags-worker-task:

``worker:task``
---------------

Describe the availability of a given version of a given task in the worker.

* ``worker:task:{task_type}:{task_name}:version:{version}``: the worker can
  execute the task with the given type, name and version.


.. _scheduler-tags-worker-type:

``worker:type``
---------------

Describe the type of worker:

* ``worker:type:{worker_type}``: type of worker, encoding the
  type of tasks that this worker can execute. This is provided by the database
  field ``Worker.worker_type`` and cannot be overridden.

Possible values:

* ``worker:type:worker``
* ``worker:type:server``
* ``worker:type:signing``
* ``worker:type:not-assignable``: this worker cannot be used for scheduling

.. todo::

  ``{task_name:="sign"}:available:purpose`` (when not OpenPGP)

  * ``system:worker_type:{worker_type}``: type of worker, matching the task type
    that this worker can execute

  * ``$task_name:version:$version``: the worker can execute the task with the
    given name and version