Custom label/annotation columns in resource tables (#776) (#872)

Add k9s-style custom columns: surface any metadata.labels[key] / annotations[key]
as a sortable, filterable, resizable, removable column from the column picker,
with key autocomplete sampled from loaded rows. Persisted per-kind in localStorage.

Implemented by materializing each custom column as a self-contained ExtraColumn
merged into allColumns + extraColumnsByKey. Pure logic (key encoding, value read,
load-boundary sanitize) extracted to utils/custom-columns.ts with unit tests.

Closes #776.

Author: nadaverell

README.md

@@ -186,6 +186,7 @@ Table-based resource browser with smart columns per resource kind.
 
 - Browse all resource types including CRDs
 - Search by name, filter by status or problems (CrashLoopBackOff, ImagePullBackOff, etc.)
+- Add custom columns from any label or annotation — sortable, filterable, and resizable
 - Click any resource for YAML manifest, related resources, logs, and events
 
 ### Image Filesystem Viewer

packages/k8s-ui/src/components/resources/ResourcesView.tsx

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { parseColumnFilters, serializeColumnFilters } from './resource-utils'
+
+describe('column filter serialization round-trip', () => {
+  it('round-trips built-in keys', () => {
+    const filters = { status: ['Running'], namespace: ['kube-system', 'default'] }
+    expect(parseColumnFilters(serializeColumnFilters(filters))).toEqual(filters)
+  })
+
+  it('round-trips custom-column keys whose own colon collides with the delimiter', () => {
+    const filters = { 'label:tier': ['control-plane'], 'annotation:foo/bar': ['x'] }
+    const serialized = serializeColumnFilters(filters)
+    // The key colon must be encoded so the first literal ':' is the delimiter.
+    expect(serialized).toBe('label%3Atier:control-plane|annotation%3Afoo%2Fbar:x')
+    expect(parseColumnFilters(serialized)).toEqual(filters)
+  })
+
+  it('preserves commas inside values', () => {
+    const filters = { conditions: ['Ready,SchedulingDisabled'] }
+    expect(parseColumnFilters(serializeColumnFilters(filters))).toEqual(filters)
+  })
+
+  it('parses legacy unencoded built-in keys', () => {
+    expect(parseColumnFilters('status:Running')).toEqual({ status: ['Running'] })
+  })
+})

packages/k8s-ui/src/components/resources/column-filter-serialization.test.ts

@@ -1648,8 +1648,12 @@ export function parseColumnFilters(filtersParam: string | null): Record<string,
   for (const pair of filtersParam.split('|')) {
     const colonIdx = pair.indexOf(':')
     if (colonIdx > 0) {
-      const key = pair.slice(0, colonIdx).trim()
+      const rawKey = pair.slice(0, colonIdx).trim()
       const valStr = pair.slice(colonIdx + 1).trim()
+      // Keys are URI-encoded so a custom-column key's own colon (e.g.
+      // "label:tier") doesn't collide with the key:value delimiter.
+      let key: string
+      try { key = decodeURIComponent(rawKey) } catch { key = rawKey }
       if (key && valStr) {
         filters[key] = valStr.split(',').map(v => {
           try { return decodeURIComponent(v.trim()) } catch { return v.trim() }
@@ -1660,12 +1664,13 @@ export function parseColumnFilters(filtersParam: string | null): Record<string,
   return filters
 }
 
-// Serialize column filters to URL param format
-// Values are URI-encoded so commas inside values (e.g. "Ready,SchedulingDisabled") survive the round-trip.
+// Serialize column filters to URL param format. Keys and values are both
+// URI-encoded so a colon inside a custom-column key (e.g. "label:tier") or a
+// comma inside a value (e.g. "Ready,SchedulingDisabled") survives the round-trip.
 export function serializeColumnFilters(filters: Record<string, string[]>): string {
   const result = Object.entries(filters)
     .filter(([, v]) => v.length > 0)
-    .map(([k, vals]) => `${k}:${vals.map(v => encodeURIComponent(v)).join(',')}`)
+    .map(([k, vals]) => `${encodeURIComponent(k)}:${vals.map(v => encodeURIComponent(v)).join(',')}`)
     .join('|')
   return result
 }

packages/k8s-ui/src/components/resources/resource-utils.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest'
+import { customColumnKey, readCustomColumnValue, sanitizeCustomColumnDefs } from './custom-columns'
+
+describe('customColumnKey', () => {
+  it('encodes source and path', () => {
+    expect(customColumnKey({ source: 'label', path: 'topology.kubernetes.io/zone' })).toBe('label:topology.kubernetes.io/zone')
+    expect(customColumnKey({ source: 'annotation', path: 'foo/bar' })).toBe('annotation:foo/bar')
+  })
+
+  it('produces equal keys for same source+path (dedupe contract)', () => {
+    const a = customColumnKey({ source: 'label', path: 'x' })
+    const b = customColumnKey({ source: 'label', path: 'x' })
+    expect(a).toBe(b)
+  })
+
+  it('distinguishes source for the same path', () => {
+    expect(customColumnKey({ source: 'label', path: 'x' }))
+      .not.toBe(customColumnKey({ source: 'annotation', path: 'x' }))
+  })
+})
+
+describe('readCustomColumnValue', () => {
+  const res = (meta: any) => ({ metadata: meta })
+
+  it('reads a label value', () => {
+    expect(readCustomColumnValue(res({ labels: { zone: 'us-east-1a' } }), { source: 'label', path: 'zone' })).toBe('us-east-1a')
+  })
+
+  it('reads an annotation value', () => {
+    expect(readCustomColumnValue(res({ annotations: { team: 'infra' } }), { source: 'annotation', path: 'team' })).toBe('infra')
+  })
+
+  it('does not cross labels and annotations', () => {
+    const r = res({ labels: { k: 'fromLabel' }, annotations: { k: 'fromAnnotation' } })
+    expect(readCustomColumnValue(r, { source: 'label', path: 'k' })).toBe('fromLabel')
+    expect(readCustomColumnValue(r, { source: 'annotation', path: 'k' })).toBe('fromAnnotation')
+  })
+
+  it('returns empty string for a missing key', () => {
+    expect(readCustomColumnValue(res({ labels: { a: '1' } }), { source: 'label', path: 'b' })).toBe('')
+  })
+
+  it('returns empty string when metadata/bag is absent', () => {
+    expect(readCustomColumnValue({}, { source: 'label', path: 'b' })).toBe('')
+    expect(readCustomColumnValue(res({}), { source: 'annotation', path: 'b' })).toBe('')
+    expect(readCustomColumnValue(undefined, { source: 'label', path: 'b' })).toBe('')
+  })
+
+  it('coerces non-string values, but maps null/undefined to empty (not the literal "null")', () => {
+    expect(readCustomColumnValue(res({ labels: { n: 5 as any } }), { source: 'label', path: 'n' })).toBe('5')
+    expect(readCustomColumnValue(res({ labels: { n: null as any } }), { source: 'label', path: 'n' })).toBe('')
+  })
+})
+
+describe('sanitizeCustomColumnDefs', () => {
+  it('returns [] for non-array input', () => {
+    expect(sanitizeCustomColumnDefs(undefined)).toEqual([])
+    expect(sanitizeCustomColumnDefs(null)).toEqual([])
+    expect(sanitizeCustomColumnDefs({ source: 'label', path: 'x' })).toEqual([])
+    expect(sanitizeCustomColumnDefs('label:x')).toEqual([])
+  })
+
+  it('keeps well-formed defs', () => {
+    const defs = [
+      { source: 'label', path: 'zone' },
+      { source: 'annotation', path: 'team' },
+    ]
+    expect(sanitizeCustomColumnDefs(defs)).toEqual(defs)
+  })
+
+  it('drops entries with invalid source, missing or blank path', () => {
+    const raw = [
+      { source: 'label', path: 'good' },
+      { source: 'lable', path: 'typo-source' },
+      { source: 'label', path: '' },
+      { source: 'label', path: '   ' },
+      { source: 'annotation' },
+      null,
+      'label:x',
+    ]
+    expect(sanitizeCustomColumnDefs(raw)).toEqual([{ source: 'label', path: 'good' }])
+  })
+
+  it('drops a non-string path without throwing (predicate short-circuits before trim)', () => {
+    const raw = [
+      { source: 'label', path: 42 },
+      { source: 'label', path: { nested: true } },
+      { source: 'annotation', path: 'ok' },
+    ]
+    expect(() => sanitizeCustomColumnDefs(raw)).not.toThrow()
+    expect(sanitizeCustomColumnDefs(raw)).toEqual([{ source: 'annotation', path: 'ok' }])
+  })
+
+  it('trims paths so the load path matches the add path', () => {
+    expect(sanitizeCustomColumnDefs([{ source: 'label', path: '  zone  ' }]))
+      .toEqual([{ source: 'label', path: 'zone' }])
+  })
+
+  it('dedupes by key, keeping the first occurrence', () => {
+    const raw = [
+      { source: 'label', path: 'zone' },
+      { source: 'label', path: 'zone' },
+      { source: 'label', path: ' zone ' },
+      { source: 'annotation', path: 'zone' },
+    ]
+    expect(sanitizeCustomColumnDefs(raw)).toEqual([
+      { source: 'label', path: 'zone' },
+      { source: 'annotation', path: 'zone' },
+    ])
+  })
+})

packages/k8s-ui/src/utils/custom-columns.test.ts

@@ -0,0 +1,49 @@
+// User-defined table columns sourcing a metadata.labels[path] or
+// metadata.annotations[path] value. Persisted per-kind in localStorage and
+// materialized (in ResourcesView) into a self-contained ExtraColumn so they
+// ride the existing render/sort/filter override rails.
+
+export type CustomColumnSource = 'label' | 'annotation'
+
+export interface CustomColumnDef {
+  source: CustomColumnSource
+  path: string
+}
+
+// Stable identity used as the React key, ExtraColumn.key, visibility-set
+// membership, and dedupe key. Built-in column keys never use a `:` prefix, so
+// `label:`/`annotation:` can't collide with them. Build-only — never parsed
+// back into source+path, so a colon inside `path` is harmless.
+export function customColumnKey(d: CustomColumnDef): string {
+  return `${d.source}:${d.path}`
+}
+
+export function readCustomColumnValue(resource: any, d: CustomColumnDef): string {
+  const bag = d.source === 'label' ? resource?.metadata?.labels : resource?.metadata?.annotations
+  const v = bag?.[d.path]
+  return typeof v === 'string' ? v : v == null ? '' : String(v)
+}
+
+// Drop anything that isn't a well-formed def — guards the localStorage load
+// boundary where a corrupted/hand-edited blob could otherwise be a non-array
+// (crashing a later .map) or carry empty/invalid entries (dead columns).
+// TypeScript's guarantees stop at JSON.parse, so this is the one place the
+// (source, non-empty path) invariant must be enforced at runtime. Paths are
+// trimmed and deduped by key so the load path produces the same defs the add
+// path would — a hand-edited blob can't yield a padded key or two columns
+// sharing one key.
+export function sanitizeCustomColumnDefs(raw: unknown): CustomColumnDef[] {
+  if (!Array.isArray(raw)) return []
+  const seen = new Set<string>()
+  const out: CustomColumnDef[] = []
+  for (const c of raw) {
+    if (!c || (c.source !== 'label' && c.source !== 'annotation') || typeof c.path !== 'string') continue
+    const def: CustomColumnDef = { source: c.source, path: c.path.trim() }
+    if (def.path === '') continue
+    const key = customColumnKey(def)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(def)
+  }
+  return out
+}