Skip to main content

Kerrigan Resource Selection

This document describes the label-based resource selection model for Kerrigan pools, devices, and GitHub-triggered workflows. Kerrigan also keeps scheduling.pools and scheduling.capabilities for backward compatibility.

Goals​

  • Let workflow authors request the right hardware without hardcoding device names in most jobs.
  • Let System Admins and pool owners describe resources in Kerrigan using meaningful labels.
  • Provide stable implicit labels for common selectors such as pool ID, board, target type, and firmware policy.
  • Keep scheduling failures debuggable by showing what was requested and why devices were rejected.
  • Preserve backward compatibility with existing pools and capabilities manifests while introducing a clearer model.

Concepts​

Explicit Labels​

Explicit labels are user-managed metadata on pools and devices. They should be stored as key/value strings.

Examples:

sdk=2.2.0
form_factor=som
board=modalix
purpose=ga-validation
uart=enabled

Pool labels describe a set of devices. Device labels describe a particular device and can refine pool labels.

System Admins can edit all pool and device labels. Pool owners can edit labels on their owned pool and devices assigned to that pool.

Tags​

Tags are shorthand labels for human-friendly grouping. They are optional and should compile into the same matching engine as labels.

Example:

2.2.0-som-devkits
ga-firmware
uart-debug

A tag can be represented internally as either a separate tag list or as a reserved boolean-like label. The scheduler should treat tags as additive requirements, not as a separate selection engine.

Implicit Labels​

Implicit labels are generated by Kerrigan and are read-only in the UI. They use the reserved kerrigan. prefix. Users must not be allowed to create or edit explicit labels under this prefix.

Recommended implicit labels:

kerrigan.pool_id=<pool-id>
kerrigan.pool_name=<pool-name-slug>
kerrigan.target_id=<target-id>
kerrigan.board=<board>
kerrigan.target_type=<target_type>
kerrigan.os_type=<os_type>
kerrigan.firmware_channel=<channel-id>
kerrigan.firmware_base_version=<x.y.z>

The most important implicit selector is kerrigan.pool_id. It gives workflows a stable way to constrain work to a specific pool without relying on display names.

Workflow Syntax​

The manifest syntax supports scheduling.labels and scheduling.tags.

scheduling:
  strategy: spread
  max_devkits: 4
  labels:
    sdk: "2.2.0"
    form_factor: som
  tags:
    - 2.2.0-som-devkits

To select a specific pool:

scheduling:
  labels:
    kerrigan.pool_id: sdk-2-2-som

To select a specific device:

scheduling:
  labels:
    kerrigan.target_id: modalix-bluebox

To use any device in an organization-defined class:

scheduling:
  labels:
    sdk: "2.2.0"
    form_factor: som
    purpose: ci

To require UART-capable devices inside one pool:

scheduling:
  labels:
    kerrigan.pool_id: lab-a
    uart: enabled

Task-level requirements should be able to refine session-level requirements:

scheduling:
  labels:
    sdk: "2.2.0"

tasks:
  - id: smoke-som
    type: command
    requirements:
      labels:
        form_factor: som

Matching Semantics​

Kerrigan should compute effective labels for each pool and device:

effective_pool_labels = explicit_pool_labels + implicit_pool_labels
effective_device_labels = effective_pool_labels + explicit_device_labels + implicit_device_labels

Device labels override pool labels only for non-reserved keys. The kerrigan. namespace is always generated by Kerrigan.

A device is eligible when all requested labels match exactly and all requested tags are present.

Matching rules:

  • Label keys and values are strings.
  • Matching is exact after normalization.
  • Keys should be case-insensitive and stored lowercase.
  • Values should be compared as strings.
  • Missing label means no match.
  • scheduling.pools remains supported and is translated to kerrigan.pool_id in [...].
  • Existing scheduling.capabilities remains supported and is translated into label requirements during the migration period.

UI Behavior​

Pool Editor​

The pool editor should include:

  • Editable explicit labels.
  • Optional tag editor.
  • Read-only implicit labels.
  • Validation for label keys and reserved prefixes.

Pool owners can edit labels only on their owned pools. System Admins can edit all pool labels.

Device Details​

The device details view should include:

  • Editable explicit device labels.
  • Optional tag editor.
  • Read-only implicit device labels.
  • A clear indication that device labels refine pool labels.

Pool owners can edit device labels for devices in their pool. System Admins can edit all device labels.

Scheduler Diagnostics​

When a session cannot be scheduled, the UI should show:

  • Requested labels and tags.
  • Eligible pools after pool-level filtering.
  • Rejection reasons for devices, such as:
    • kerrigan.pool_id=default did not match sdk-2-2-som
    • form_factor missing
    • sdk expected 2.2.0, got 2.1.1

Without this, label-based scheduling will be hard to debug.

Validation​

Recommended label validation:

  • Key format: lowercase letters, numbers, ., _, and -.
  • Key must not start with kerrigan. for user-managed labels.
  • Value must be a short string.
  • Empty values remove the label.
  • Tags should use lowercase letters, numbers, _, and -.

Example valid keys:

sdk
form_factor
firmware.channel
owner_team

Example reserved keys:

kerrigan.pool_id
kerrigan.target_id
kerrigan.board

Migration Plan​

  1. Add backend helper functions:

    • effective_pool_labels(pool)
    • effective_target_labels(target, pool)
    • label key/value validation

  2. Add manifest parsing:

    • scheduling.labels
    • scheduling.tags
    • task-level requirements.labels
    • task-level requirements.tags

  3. Preserve existing behavior:

    • Convert scheduling.pools to kerrigan.pool_id constraints.
    • Convert scheduling.capabilities to label constraints.

  4. Update scheduler matching and diagnostics.

  5. Add UI editing for pool labels and device labels.

  6. Add read-only implicit label display.

  7. Update the manifest guide once the syntax is implemented.

Open Questions​

  • Should tags be first-class storage or represented as labels?
  • Should matching support multi-value labels, such as firmware_base_version in [2.1.1, 2.2.0], or should workflows express this as separate jobs?
  • Should pool labels automatically apply to all devices for matching, or should jobs be able to request pool-only labels separately from device labels?
  • Should pool owners be allowed to create new label keys, or only edit values for keys approved by a System Admin?