==============================
Role - edpm_cyborg
==============================

This role deploys the OpenStack Cyborg agent as a Podman container on
EDPM compute nodes. The cyborg-agent discovers accelerator hardware
(GPUs, FPGAs, etc.) and reports it to the Cyborg conductor on the
controlplane.

The service is opt-in: users add ``cyborg`` to their
``OpenStackDataPlaneNodeSet`` services list when accelerator management
is needed.

Configuration
~~~~~~~~~~~~~

The cyborg-agent receives its configuration from two sources,
all synced to the compute host by this role:

1. **Base secret** (``cyborg-agent-config``) -- generated by the controlplane
   operator and declared as a ``secretRef`` in the ``OpenStackDataPlaneService``
   CR ``dataSources``. Contains the default agent configuration.

2. **Extra config** -- an optional ``configMapRef`` in the same ``dataSources``
   for user-provided ``.conf`` overrides.

All ``.conf`` files from these sources are placed into
``/etc/cyborg/cyborg.conf.d/`` inside the container.

If the same extra configuration applies to all compute nodes, a single
``OpenStackDataPlaneService`` with one ``configMapRef`` (e.g.,
``cyborg-extra-config``) is sufficient.

If different compute nodes require different configurations (e.g., GPU nodes
vs FPGA nodes), create a separate ``OpenStackDataPlaneService`` per
accelerator type, each pointing to its own ConfigMap. All variants use the
same playbook (``osp.edpm.cyborg``):

.. code-block:: yaml

   # GPU service
   apiVersion: dataplane.openstack.org/v1beta1
   kind: OpenStackDataPlaneService
   metadata:
     name: cyborg-gpu
   spec:
     dataSources:
       - secretRef:
           name: cyborg-agent-config
       - configMapRef:
           name: cyborg-gpu-extra-config
     playbook: osp.edpm.cyborg
     caCerts: combined-ca-bundle
     edpmServiceType: cyborg

   # FPGA service
   apiVersion: dataplane.openstack.org/v1beta1
   kind: OpenStackDataPlaneService
   metadata:
     name: cyborg-fpga
   spec:
     dataSources:
       - secretRef:
           name: cyborg-agent-config
       - configMapRef:
           name: cyborg-fpga-extra-config
     playbook: osp.edpm.cyborg
     caCerts: combined-ca-bundle
     edpmServiceType: cyborg

Then reference the appropriate service in each NodeSet:

.. code-block:: yaml

   # GPU NodeSet
   spec:
     services:
       - cyborg-gpu

   # FPGA NodeSet
   spec:
     services:
       - cyborg-fpga

Bind mounts
~~~~~~~~~~~

The cyborg-agent container includes the following device and system mounts
by default:

- ``/dev`` -- Host devices
- ``/sys`` -- Sysfs
- ``/etc/nvme`` -- NVMe configuration

Accelerator devices often require additional host paths (e.g., ``/dev/dri``)
to be mounted into the container. Use ``edpm_cyborg_extra_bind_mounts`` to
declare them:

.. code-block:: yaml

   edpm_cyborg_extra_bind_mounts:
     - src: /dev/dri
       dest: /dev/dri
       options: rw

The role validates that source directories exist and that destination
paths do not collide with the standard mounts (``/var/lib/cyborg``,
``/var/lib/openstack``, ``/etc/cyborg``).

.. include::
  ../collections/osp/edpm/edpm_cyborg_role.rst