@skyhook-io/k8s-ui 1.19.0 → 1.20.0

package/src/components/kueue/QueueEvidence.tsx

@@ -0,0 +1,148 @@
+import type { ReactNode } from 'react'
+import { Badge } from '../ui/Badge'
+import { ResourceLink } from '../ui/drawer-components'
+import { TimeValue } from '../ui/ScheduleValue'
+import { FactGrid, FactRow, FactValue, type Fact } from '../facts'
+import type { StatusBadge } from '../resources/resource-utils'
+import { getAdmissionCheckStatus, getClusterQueueStatus, getKueueQueueCondition, isKueueConditionStale } from '../resources/resource-utils-kueue'
+import { describeKueuePolicy } from './policy'
+import { isDenied, unreadReason, type RelatedRead } from './related-read'
+import { namespaceEligibility } from './eligibility'
+import { KUEUE_GROUP } from './constants'
+
+export type Navigate = (ref: { kind: string; namespace: string; name: string; group?: string }) => void
+
+/** One related object's name with what Radar's read of it found. Without a read, the name alone. */
+export function ReadState({ read, found }: { read?: RelatedRead; found?: ReactNode }) {
+  if (!read) return null
+  if (read.state === 'found') return <>{found ?? <Badge severity="neutral" size="sm">Found</Badge>}</>
+  if (read.state === 'not_found') return <Badge severity="error" size="sm">Not found</Badge>
+  if (read.state === 'unconfirmed') return <span className="text-xs text-theme-text-tertiary">This Radar can’t confirm whether it exists</span>
+  return <span className={isDenied(read) ? 'text-xs text-theme-text-secondary' : 'text-xs text-theme-text-tertiary'}>{read.state === 'loading' ? 'Checking…' : `Not read: ${unreadReason(read)}`}</span>
+}
+
+export function StatusPill({ status }: { status: StatusBadge }) {
+  return <Badge colorClass={status.color} size="sm">{status.text}</Badge>
+}
+
+export function ReportedActive({ data, status, children }: { data: any; status: StatusBadge; children?: ReactNode }) {
+  const condition = getKueueQueueCondition(data)
+  const generation = data?.metadata?.generation
+  if (!condition) {
+    return <div className="space-y-2 text-sm">
+      <div className="flex flex-wrap items-center gap-2"><StatusPill status={status} /></div>
+      <p className="text-theme-text-secondary">No Active condition reported.</p>
+      {children}
+    </div>
+  }
+  return <div className="space-y-2 text-sm">
+    <div className="flex flex-wrap items-center gap-2">
+      <StatusPill status={status} />
+      {condition.reason && !status.text.startsWith(condition.reason) && <code className="break-all text-xs text-theme-text-secondary">{condition.reason}</code>}
+    </div>
+    {condition.message && <p className="whitespace-pre-wrap break-words text-theme-text-primary">{condition.message}</p>}
+    <p className="text-xs text-theme-text-tertiary">
+      Active={condition.status}
+      {condition.lastTransitionTime && <> since <TimeValue timestamp={condition.lastTransitionTime} /></>}
+      {' · '}
+      {condition.observedGeneration ? `observed generation ${condition.observedGeneration} of ${generation ?? '?'}` : 'observed generation not reported'}
+    </p>
+    {children}
+  </div>
+}
+
+function count(value: unknown, source: string): Fact {
+  return typeof value === 'number'
+    ? { text: String(value), tone: 'neutral', source }
+    : { text: 'Not reported', tone: 'unknown', source }
+}
+
+/** Controller-reported Workload counts. Reserving includes admitted, so they never add up. */
+export function QueueCounts({ data, kind }: { data: any; kind: 'ClusterQueue' | 'LocalQueue' }) {
+  const source = `Reported in the ${kind}'s status`
+  return <div className="space-y-2">
+    <FactGrid>
+      <FactRow label="Pending"><FactValue fact={count(data?.status?.pendingWorkloads, source)} /></FactRow>
+      <FactRow label="Reserving quota"><FactValue fact={count(data?.status?.reservingWorkloads, source)} /></FactRow>
+      <FactRow label="Admitted"><FactValue fact={count(data?.status?.admittedWorkloads, source)} /></FactRow>
+    </FactGrid>
+    <p className="text-xs text-theme-text-tertiary">Reserving includes admitted Workloads, so these counts are not additive. Admission does not establish that Pods are running.</p>
+  </div>
+}
+
+export function ConfiguredStop({ data }: { data: any }) {
+  const raw = data?.spec?.stopPolicy
+  const policy = describeKueuePolicy(data?.apiVersion, 'stopPolicy', raw ?? 'None')
+  return <div className="space-y-1 text-sm">
+    <div className="flex flex-wrap items-baseline gap-2">
+      <span className="text-theme-text-tertiary">Stop policy</span>
+      <code className="text-theme-text-primary">{policy.raw}</code>
+      {raw == null && <span className="text-xs text-theme-text-tertiary">(not set)</span>}
+    </div>
+    <p className="text-theme-text-secondary">{policy.meaning ?? `Radar has no description of this value for ${data?.apiVersion ?? 'this API version'}.`}</p>
+  </div>
+}
+
+function ReportedMessage({ condition, generation }: { condition: any; generation?: number }) {
+  return <p className="whitespace-pre-wrap break-words text-xs text-theme-text-secondary">
+    {isKueueConditionStale(condition, generation) && <span className="text-theme-text-tertiary">Reported for generation {condition.observedGeneration} (now {generation}): </span>}
+    {condition.message}
+  </p>
+}
+
+export function ClusterQueueReadSummary({ name, read, onNavigate }: { name: string; read?: RelatedRead; onNavigate?: Navigate }) {
+  const parent = read?.state === 'found' ? read.object : undefined
+  const condition = parent ? getKueueQueueCondition(parent) : undefined
+  return <div className="min-w-0 space-y-1 text-sm">
+    <div className="flex flex-wrap items-center gap-2 break-all [&_button]:text-left">
+      <ResourceLink name={name} kind="clusterqueues" group={KUEUE_GROUP} onNavigate={onNavigate} />
+      <ReadState read={read} found={parent ? <StatusPill status={getClusterQueueStatus(parent)} /> : undefined} />
+    </div>
+    {parent && <p className="text-xs text-theme-text-secondary">
+      Read from the ClusterQueue{condition?.reason && condition.status !== 'True' ? `: ${condition.reason}${isKueueConditionStale(condition, parent.metadata?.generation) ? ' (stale)' : ''}` : ''}{parent.spec?.stopPolicy && parent.spec.stopPolicy !== 'None' ? ` · stop policy ${parent.spec.stopPolicy}` : ''}
+    </p>}
+    {parent && condition?.message && condition.status !== 'True' && <ReportedMessage condition={condition} generation={parent.metadata?.generation} />}
+  </div>
+}
+
+/**
+ * Whether a namespace matches a ClusterQueue's namespaceSelector. The
+ * selector is only known from a ClusterQueue that was read; the namespace's
+ * labels are needed only when the selector has terms.
+ */
+export function namespaceEligibilityFact({ clusterQueue, parent, namespaceRead }: { clusterQueue: string; parent?: RelatedRead; namespaceRead?: RelatedRead }): Fact {
+  const source = `ClusterQueue ${clusterQueue} namespaceSelector`
+  if (parent?.state !== 'found') {
+    const why = !parent ? 'Unknown: the ClusterQueue was not read'
+      : parent.state === 'loading' ? 'Checking the ClusterQueue…'
+        : parent.state === 'not_found' ? 'Unknown: the ClusterQueue was not found'
+          : `Unknown: ClusterQueue not read (${unreadReason(parent)})`
+    return { text: why, tone: 'unknown', source }
+  }
+  const selector = parent.object?.spec?.namespaceSelector
+  const labels = namespaceRead?.state === 'found' ? (namespaceRead.object?.metadata?.labels ?? {}) : undefined
+  const result = namespaceEligibility(selector, labels)
+  switch (result.state) {
+    case 'eligible':
+      return { text: result.basis === 'all' ? 'Eligible: the selector is empty ({}), so every namespace matches' : 'Eligible: its labels match the selector', tone: 'healthy', source }
+    case 'not_eligible':
+      return { text: result.basis === 'none' ? 'Not eligible: the ClusterQueue sets no namespaceSelector, so no namespace matches' : 'Not eligible: its labels don’t match the selector', tone: 'unhealthy', source }
+    default:
+      if (result.why === 'unsupported_operator') return { text: `Unknown: the selector uses operator ${result.operator || '(none)'}, which Radar doesn't evaluate`, tone: 'unknown', source }
+      if (namespaceRead?.state === 'loading') return { text: 'Checking the namespace…', tone: 'unknown', source }
+      return { text: namespaceRead?.state === 'not_found' ? 'Unknown: the Namespace was not found' : `Unknown: its labels weren’t read (${unreadReason(namespaceRead)})`, tone: 'unknown', source }
+  }
+}
+
+export function AdmissionCheckRow({ name, onFlavors, read, onNavigate }: { name: string; onFlavors?: string[]; read?: RelatedRead; onNavigate?: Navigate }) {
+  const check = read?.state === 'found' ? read.object : undefined
+  const condition = check ? getKueueQueueCondition(check) : undefined
+  return <div className="min-w-0 space-y-1 text-sm">
+    <div className="flex flex-wrap items-center gap-2 break-all [&_button]:text-left">
+      <ResourceLink name={name} kind="admissionchecks" group={KUEUE_GROUP} onNavigate={onNavigate} />
+      <ReadState read={read} found={check ? <StatusPill status={getAdmissionCheckStatus(check)} /> : undefined} />
+    </div>
+    <p className="break-words text-xs text-theme-text-secondary">{onFlavors?.length ? `Applies to flavors: ${onFlavors.join(', ')}` : 'Applies to all flavors'}</p>
+    {condition?.message && condition.status !== 'True' && <ReportedMessage condition={condition} generation={check.metadata?.generation} />}
+  </div>
+}

package/src/components/kueue/constants.ts

@@ -0,0 +1 @@
+export const KUEUE_GROUP = 'kueue.x-k8s.io'

package/src/components/kueue/eligibility.ts

@@ -0,0 +1,43 @@
+// Whether a namespace may submit Workloads to a ClusterQueue, from the
+// ClusterQueue's namespaceSelector. Kueue reads a null selector as "no
+// namespace" and an empty one ({}) as "every namespace", so only a selector
+// with terms needs the namespace's labels.
+
+export type NamespaceEligibility =
+  | { state: 'eligible'; basis: 'all' | 'labels' }
+  | { state: 'not_eligible'; basis: 'none' | 'labels' }
+  /** The labels are needed and weren't read, or the selector can't be evaluated. */
+  | { state: 'unknown'; why: 'labels_unread' | 'unsupported_operator'; operator?: string }
+
+interface Requirement { key?: string; operator?: string; values?: string[] }
+export interface LabelSelector { matchLabels?: Record<string, string>; matchExpressions?: Requirement[] }
+
+function selectorHasTerms(selector: LabelSelector | null | undefined): boolean {
+  return !!selector && (Object.keys(selector.matchLabels ?? {}).length > 0 || (selector.matchExpressions?.length ?? 0) > 0)
+}
+
+/** Evaluating the selector would use the namespace's labels (it has terms, all with supported operators). */
+export function needsNamespaceLabels(selector: LabelSelector | null | undefined): boolean {
+  const result = namespaceEligibility(selector, undefined)
+  return result.state === 'unknown' && result.why === 'labels_unread'
+}
+
+/** labels is undefined when the namespace's labels weren't read. */
+export function namespaceEligibility(selector: LabelSelector | null | undefined, labels: Record<string, string> | undefined): NamespaceEligibility {
+  if (selector == null) return { state: 'not_eligible', basis: 'none' }
+  if (!selectorHasTerms(selector)) return { state: 'eligible', basis: 'all' }
+  const unsupported = (selector.matchExpressions ?? []).find(term => !['In', 'NotIn', 'Exists', 'DoesNotExist'].includes(term?.operator ?? ''))
+  if (unsupported) return { state: 'unknown', why: 'unsupported_operator', operator: String(unsupported?.operator ?? '') }
+  if (!labels) return { state: 'unknown', why: 'labels_unread' }
+  const has = (key: string) => Object.prototype.hasOwnProperty.call(labels, key)
+  const matches = Object.entries(selector.matchLabels ?? {}).every(([key, value]) => has(key) && labels[key] === value)
+    && (selector.matchExpressions ?? []).every(({ key = '', operator, values = [] }) => {
+      switch (operator) {
+        case 'In': return has(key) && values.includes(labels[key])
+        case 'NotIn': return !has(key) || !values.includes(labels[key])
+        case 'Exists': return has(key)
+        default: return !has(key)
+      }
+    })
+  return matches ? { state: 'eligible', basis: 'labels' } : { state: 'not_eligible', basis: 'labels' }
+}

package/src/components/kueue/flavors-tried.ts

@@ -0,0 +1,79 @@
+// Parses the flavor attempts out of a pending Workload's QuotaReserved
+// message. Kueue builds it as "couldn't assign flavors to pod set <ps>: <reasons>"
+// per failing pod set, joined by "; ", with each pod set's reasons sorted
+// alphabetically and joined by ", " — so the order of the reasons is not the
+// order flavors were tried. A message with any part this parser doesn't
+// recognise yields null and is shown verbatim instead.
+
+export type FlavorAttemptKind =
+  | 'insufficient_quota'
+  | 'insufficient_unused_quota'
+  | 'untolerated_taint'
+  | 'node_affinity'
+  | 'flavor_not_found'
+  | 'resource_unavailable'
+  | 'skipped_by_annotation'
+  | 'pinned_by_original'
+
+export interface FlavorAttempt {
+  kind: FlavorAttemptKind
+  flavor?: string
+  resource?: string
+  /** The controller's own words for this reason. */
+  text: string
+}
+
+export interface PodSetAttempts {
+  podSet: string
+  attempts: FlavorAttempt[]
+}
+
+const podSetPrefix = "couldn't assign flavors to pod set "
+
+/** The message is Kueue's per-flavor account of why quota wasn't assigned (parsed or not). Its error form isn't. */
+export function isFlavorAssignmentMessage(message: string | undefined): boolean {
+  return !!message && message.startsWith(podSetPrefix)
+}
+
+const patterns: { kind: FlavorAttemptKind; re: RegExp; flavor?: number; resource?: number }[] = [
+  { kind: 'insufficient_unused_quota', re: /^insufficient unused quota for (\S+) in flavor (\S+), \S+ more needed$/, resource: 1, flavor: 2 },
+  { kind: 'insufficient_quota', re: /^insufficient quota for (\S+) in flavor (\S+), (?:previously considered podsets requests \(\S+\) \+ current podset request \(\S+\) > maximum capacity \(\S+\)|request > maximum capacity \(\S+ > \S+\))$/, resource: 1, flavor: 2 },
+  { kind: 'untolerated_taint', re: /^untolerated taint .+ in flavor (\S+)$/, flavor: 1 },
+  { kind: 'node_affinity', re: /^flavor (\S+) doesn't match node affinity$/, flavor: 1 },
+  { kind: 'flavor_not_found', re: /^flavor (\S+) not found$/, flavor: 1 },
+  { kind: 'resource_unavailable', re: /^resource (\S+) unavailable in ClusterQueue$/, resource: 1 },
+  { kind: 'skipped_by_annotation', re: /^skipping flavor (\S+) due to WorkloadAllowedResourceFlavorAnnotation annotation$/, flavor: 1 },
+  // Names the candidate flavor, then the flavor the original Workload holds.
+  { kind: 'pinned_by_original', re: /^could not assign (\S+) flavor since the original workload is assigned: \S+$/, flavor: 1 },
+]
+
+// A reason begins only at one of these; ", " inside a reason ("…, 2 more needed")
+// is not a boundary.
+const reasonStart = /, (?=insufficient (?:unused )?quota for |untolerated taint |flavor \S+ (?:doesn't match node affinity|not found)|resource \S+ unavailable in ClusterQueue|skipping flavor |could not assign )/
+
+function parseReason(text: string): FlavorAttempt | null {
+  for (const { kind, re, flavor, resource } of patterns) {
+    const match = re.exec(text)
+    if (match) return { kind, text, ...(flavor ? { flavor: match[flavor] } : {}), ...(resource ? { resource: match[resource] } : {}) }
+  }
+  return null
+}
+
+export function parseFlavorAttempts(message: string | undefined): PodSetAttempts[] | null {
+  if (!message?.startsWith(podSetPrefix)) return null
+  const result: PodSetAttempts[] = []
+  for (const part of message.slice(podSetPrefix.length).split(`; ${podSetPrefix}`)) {
+    const separator = part.indexOf(': ')
+    if (separator <= 0) return null
+    const podSet = part.slice(0, separator)
+    const reasons = part.slice(separator + 2).split(reasonStart)
+    const attempts: FlavorAttempt[] = []
+    for (const reason of reasons) {
+      const attempt = parseReason(reason)
+      if (!attempt) return null
+      attempts.push(attempt)
+    }
+    result.push({ podSet, attempts })
+  }
+  return result
+}

package/src/components/kueue/helpers.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { parseFlavorAttempts } from './flavors-tried'
+import { namespaceEligibility } from './eligibility'
+import { describeKueuePolicy } from './policy'
+import { isDenied, unreadReason } from './related-read'
+
+describe('parseFlavorAttempts', () => {
+  it('parses the Kueue v0.18 message seen on a live 3-CPU Workload into both attempts', () => {
+    const message = "couldn't assign flavors to pod set main: insufficient quota for cpu in flavor gpu-night-813-small, previously considered podsets requests (0) + current podset request (3) > maximum capacity (1), insufficient quota for cpu in flavor gpu-night-813-spot, previously considered podsets requests (0) + current podset request (3) > maximum capacity (1)"
+    expect(parseFlavorAttempts(message)).toEqual([{ podSet: 'main', attempts: [
+      { kind: 'insufficient_quota', resource: 'cpu', flavor: 'gpu-night-813-small', text: 'insufficient quota for cpu in flavor gpu-night-813-small, previously considered podsets requests (0) + current podset request (3) > maximum capacity (1)' },
+      { kind: 'insufficient_quota', resource: 'cpu', flavor: 'gpu-night-813-spot', text: 'insufficient quota for cpu in flavor gpu-night-813-spot, previously considered podsets requests (0) + current podset request (3) > maximum capacity (1)' },
+    ] }])
+  })
+
+  it('splits pod sets and every reason format, keeping commas inside a reason', () => {
+    const message = "couldn't assign flavors to pod set driver: flavor a doesn't match node affinity, insufficient unused quota for nvidia.com/gpu in flavor b, 2 more needed, untolerated taint gpu=true:NoSchedule in flavor c; couldn't assign flavors to pod set workers: flavor z not found, resource example.com/fpga unavailable in ClusterQueue, skipping flavor y due to WorkloadAllowedResourceFlavorAnnotation annotation, could not assign x flavor since the original workload is assigned: w"
+    const parsed = parseFlavorAttempts(message)
+    expect(parsed?.map(p => p.podSet)).toEqual(['driver', 'workers'])
+    expect(parsed?.[0].attempts.map(a => [a.kind, a.flavor, a.resource])).toEqual([
+      ['node_affinity', 'a', undefined], ['insufficient_unused_quota', 'b', 'nvidia.com/gpu'], ['untolerated_taint', 'c', undefined],
+    ])
+    expect(parsed?.[1].attempts.map(a => [a.kind, a.flavor, a.resource])).toEqual([
+      ['flavor_not_found', 'z', undefined], ['resource_unavailable', undefined, 'example.com/fpga'], ['skipped_by_annotation', 'y', undefined], ['pinned_by_original', 'x', undefined],
+    ])
+  })
+
+  it('returns null for anything it cannot account for, so the caller shows the message verbatim', () => {
+    for (const message of [
+      undefined,
+      '',
+      "LocalQueue no-such-localqueue doesn't exist",
+      "Workload namespace doesn't match ClusterQueue selector",
+      'failed to assign flavors to pod set main: boom',
+      "couldn't assign flavors to pod set main: topology \"rack\" doesn't allow to fit any of 3 pod(s)",
+      "couldn't assign flavors to pod set main: insufficient quota for cpu in flavor a, request > maximum capacity (24 > 8), something new",
+      "couldn't assign flavors to pod set main",
+    ]) expect(parseFlavorAttempts(message)).toBeNull()
+  })
+
+  it('accepts an older quota detail shape as long as the reason prefix is known', () => {
+    expect(parseFlavorAttempts("couldn't assign flavors to pod set main: insufficient quota for cpu in flavor default, request > maximum capacity (24 > 8)")?.[0].attempts[0].flavor).toBe('default')
+  })
+})
+
+describe('namespaceEligibility', () => {
+  it('reads null as no namespace and {} as every namespace without needing labels', () => {
+    expect(namespaceEligibility(null, undefined)).toEqual({ state: 'not_eligible', basis: 'none' })
+    expect(namespaceEligibility(undefined, undefined)).toEqual({ state: 'not_eligible', basis: 'none' })
+    expect(namespaceEligibility({}, undefined)).toEqual({ state: 'eligible', basis: 'all' })
+    expect(namespaceEligibility({ matchLabels: {}, matchExpressions: [] }, undefined)).toEqual({ state: 'eligible', basis: 'all' })
+  })
+
+  it('needs labels for a selector with terms, and says so when they were not read', () => {
+    expect(namespaceEligibility({ matchLabels: { team: 'a' } }, undefined)).toEqual({ state: 'unknown', why: 'labels_unread' })
+    expect(namespaceEligibility({ matchLabels: { team: 'a' } }, { team: 'a' }).state).toBe('eligible')
+    expect(namespaceEligibility({ matchLabels: { team: 'a' } }, { team: 'b' }).state).toBe('not_eligible')
+    expect(namespaceEligibility({ matchLabels: { team: 'a' } }, {}).state).toBe('not_eligible')
+  })
+
+  it('evaluates every selector operator as Kubernetes does', () => {
+    const sel = (operator: string, values?: string[]) => ({ matchExpressions: [{ key: 'tier', operator, values }] })
+    expect(namespaceEligibility(sel('In', ['gpu']), { tier: 'gpu' }).state).toBe('eligible')
+    expect(namespaceEligibility(sel('In', ['gpu']), {}).state).toBe('not_eligible')
+    expect(namespaceEligibility(sel('NotIn', ['gpu']), {}).state).toBe('eligible')
+    expect(namespaceEligibility(sel('NotIn', ['gpu']), { tier: 'gpu' }).state).toBe('not_eligible')
+    expect(namespaceEligibility(sel('Exists'), { tier: '' }).state).toBe('eligible')
+    expect(namespaceEligibility(sel('DoesNotExist'), { tier: '' }).state).toBe('not_eligible')
+    expect(namespaceEligibility(sel('Gt', ['1']), { tier: '2' })).toEqual({ state: 'unknown', why: 'unsupported_operator', operator: 'Gt' })
+  })
+})
+
+describe('describeKueuePolicy', () => {
+  it('keeps a dictionary per API version and shows unknown values raw', () => {
+    expect(describeKueuePolicy('kueue.x-k8s.io/v1beta1', 'flavorFungibility.whenCanBorrow', 'Borrow').meaning).toContain('Equivalent to MayStopSearch in newer Kueue')
+    expect(describeKueuePolicy('kueue.x-k8s.io/v1beta2', 'flavorFungibility.whenCanBorrow', 'Borrow')).toEqual({ raw: 'Borrow' })
+    expect(describeKueuePolicy('kueue.x-k8s.io/v1beta2', 'admissionScope.admissionMode', 'NoAdmissionFairSharing').meaning).toBeTruthy()
+    expect(describeKueuePolicy('kueue.x-k8s.io/v1', 'stopPolicy', 'Hold')).toEqual({ raw: 'Hold' })
+    expect(describeKueuePolicy('kueue.x-k8s.io/v1beta2', 'stopPolicy', 'Hold').meaning).toContain('admitted Workloads run to completion')
+  })
+})
+
+describe('related reads', () => {
+  it('tells a denial apart from a read that failed for another reason', () => {
+    expect(isDenied({ state: 'unavailable', code: 'user_forbidden' })).toBe(true)
+    expect(isDenied({ state: 'unavailable', code: 'kind_sync_timed_out' })).toBe(false)
+    expect(isDenied({ state: 'not_found' })).toBe(false)
+    expect(unreadReason({ state: 'unavailable', code: 'user_forbidden' })).toBe('you can’t read it')
+    expect(unreadReason({ state: 'unavailable', code: 'radar_forbidden' })).toBe('Radar can’t read it')
+    expect(unreadReason({ state: 'unavailable', code: 'rbac_denied' })).toBe('you can’t read it')
+    expect(unreadReason({ state: 'loading' })).toBe('checking…')
+    expect(unreadReason({ state: 'unavailable' })).toBe('the read failed')
+  })
+})
+
+describe('policy dictionaries against the served CRDs', () => {
+  it('describe every enum value Kueue v0.18 serves, per version', async () => {
+    const { enums } = (await import('./testdata/kueue-v0.18-policy-enums.json')).default as { enums: Record<string, Record<string, string[]>> }
+    for (const [version, fields] of Object.entries(enums)) {
+      for (const [field, values] of Object.entries(fields)) {
+        for (const value of values) expect(describeKueuePolicy(version, field as any, value).meaning, `${version} ${field}=${value}`).toBeTruthy()
+      }
+    }
+  })
+})

package/src/components/kueue/policy.ts

@@ -0,0 +1,100 @@
+// Plain-language meanings for Kueue queue policy values, one dictionary per
+// served API version. Wording follows the CRD field descriptions; a value a
+// dictionary doesn't list is shown raw, never mapped to a nearby meaning.
+
+export type KueuePolicyField =
+  | 'stopPolicy'
+  | 'queueingStrategy'
+  | 'preemption.withinClusterQueue'
+  | 'preemption.reclaimWithinCohort'
+  | 'preemption.borrowWithinCohort.policy'
+  | 'flavorFungibility.whenCanBorrow'
+  | 'flavorFungibility.whenCanPreempt'
+  | 'flavorFungibility.preference'
+  | 'admissionScope.admissionMode'
+
+type Dictionary = Partial<Record<KueuePolicyField, Record<string, string>>>
+
+const shared: Dictionary = {
+  stopPolicy: {
+    None: 'Not stopped by policy.',
+    Hold: 'Stopped: no new reservations; reservations are cancelled for Workloads not yet admitted, and admitted Workloads run to completion.',
+    HoldAndDrain: 'Stopped and draining: no new reservations; reservations are cancelled and admitted Workloads are evicted.',
+  },
+  queueingStrategy: {
+    StrictFIFO: 'By priority, then creation time; the Workload at the head that can’t be admitted blocks those behind it, even if they fit.',
+    BestEffortFIFO: 'By priority, then creation time; a Workload that can’t be admitted doesn’t block those behind it that fit.',
+  },
+  'preemption.withinClusterQueue': {
+    Never: 'A pending Workload never preempts Workloads in this ClusterQueue.',
+    LowerPriority: 'A pending Workload that doesn’t fit nominal quota may preempt lower-priority Workloads in this ClusterQueue.',
+    LowerOrNewerEqualPriority: 'A pending Workload may preempt Workloads in this ClusterQueue with lower priority, or equal priority and newer.',
+  },
+  'preemption.reclaimWithinCohort': {
+    Never: 'Never preempts Workloads of other ClusterQueues in the cohort.',
+    LowerPriority: 'May preempt lower-priority Workloads of cohort ClusterQueues that use more than their nominal quota.',
+    Any: 'May preempt Workloads of cohort ClusterQueues that use more than their nominal quota, regardless of priority.',
+  },
+  'preemption.borrowWithinCohort.policy': {
+    Never: 'A Workload that must borrow never preempts in other cohort ClusterQueues.',
+    LowerPriority: 'A Workload that must borrow may preempt lower-priority Workloads in other cohort ClusterQueues.',
+  },
+  'flavorFungibility.preference': {
+    BorrowingOverPreemption: 'When every flavor needs borrowing or preemption, prefer borrowing.',
+    PreemptionOverBorrowing: 'When every flavor needs borrowing or preemption, prefer preemption.',
+  },
+}
+
+const admissionMode = {
+  UsageBasedAdmissionFairSharing: 'Admission fair sharing: Workloads are ordered by their LocalQueue’s recent resource usage.',
+  NoAdmissionFairSharing: 'Admission fair sharing is off for this ClusterQueue.',
+}
+
+const mayStopSearchBorrow = 'Stop at the first flavor where the Workload fits or fits by borrowing.'
+const mayStopSearchPreempt = 'Stop at the first flavor where the Workload fits or fits by preempting.'
+
+const v1beta1: Dictionary = {
+  ...shared,
+  'admissionScope.admissionMode': admissionMode,
+  'flavorFungibility.whenCanBorrow': {
+    MayStopSearch: mayStopSearchBorrow,
+    TryNextFlavor: 'Try the next flavor before borrowing in this one.',
+    Borrow: `${mayStopSearchBorrow} (Equivalent to MayStopSearch in newer Kueue.)`,
+  },
+  'flavorFungibility.whenCanPreempt': {
+    MayStopSearch: mayStopSearchPreempt,
+    TryNextFlavor: 'Try the next flavor before preempting in this one.',
+    Preempt: `${mayStopSearchPreempt} (Equivalent to MayStopSearch in newer Kueue.)`,
+  },
+}
+
+const v1beta2: Dictionary = {
+  ...shared,
+  'flavorFungibility.whenCanBorrow': {
+    MayStopSearch: mayStopSearchBorrow,
+    TryNextFlavor: 'Try the next flavor before borrowing in this one.',
+  },
+  'flavorFungibility.whenCanPreempt': {
+    MayStopSearch: mayStopSearchPreempt,
+    TryNextFlavor: 'Try the next flavor before preempting in this one.',
+  },
+  'admissionScope.admissionMode': admissionMode,
+
+}
+
+const dictionaries: Record<string, Dictionary> = {
+  'kueue.x-k8s.io/v1beta1': v1beta1,
+  'kueue.x-k8s.io/v1beta2': v1beta2,
+}
+
+export interface KueuePolicyValue {
+  raw: string
+  /** Absent when this Radar has no meaning for the value at this API version. */
+  meaning?: string
+}
+
+export function describeKueuePolicy(apiVersion: string | undefined, field: KueuePolicyField, value: unknown): KueuePolicyValue {
+  const raw = String(value)
+  const meaning = dictionaries[apiVersion ?? '']?.[field]?.[raw]
+  return meaning ? { raw, meaning } : { raw }
+}