GoogleCloudPlatform/k8s-aibom

What it is

k8s-aibom is a Google Cloud Platform Kubernetes controller that emits CycloneDX 1.6 ML-BOM documents for AI workloads at runtime. The summary covers the workload coverage; what matters for an engineer deciding to deploy it is how it runs, how it delivers output, and how much to trust each field. Status is "released — production-suitable for non-critical observation use cases," with APIs stable through v1.x (see VERSIONING.md).

How it works

The controller runs as a single Deployment in its own namespace (k8s-aibom-system). No DaemonSet, no privileged container, no kernel access, no node-level agent — it observes only through the standard Kubernetes API. You opt in namespaces; for each tracked workload it scrapes the workload spec and current pod status, applies category-specific detection heuristics, builds the ML-BOM, and writes to configured sinks.

Output is delivered as an AIBOM custom resource (one per workload, namespace-scoped), with the document in status.bomDocument. Optional external sinks are a GCS bucket (full BOM JSON) and a webhook endpoint (POST per BOM).

Crucially, identical inputs produce byte-identical BOMs (modulo timestamps), so output is suitable for content-addressable storage and diff-based change tracking.

The confidence model is the load-bearing detail. Every attribute carries a flag and an evidence locator:

• declared — written into the workload spec by the operator: a --model container arg, an HF_MODEL_ID env var, or a model.k8saibom.dev/name annotation.
• inferred — derived by heuristic: runtime vllm matched from image regex ^vllm/.*; agent framework identified from a langchain import pattern in container args.

flowchart LR
  W[Opted-in workload] --> C[Controller scrapes spec + pod status]
  C --> CR[AIBOM CR<br/>status.bomDocument]
  C -.optional.-> GCS[GCS bucket<br/>full JSON]
  C -.optional.-> WH[Webhook<br/>POST per BOM]

Preconditions / Affected

Workloads must be running on Kubernetes and expose identity through specs the API can read. Inferred attributes depend on image-name and arg patterns matching known signatures; attributes not present in specs, args, env vars, volumes, or annotations will not be captured. RAG collections and evaluation benchmark suites are extracted only "where determinable."

Caveats

• Self-scoped as suitable only for non-critical observation use cases — not positioned as an authoritative control.
• It is a runtime inventory: it reports what is in fact serving, calling APIs, or training, which may diverge from build-time AIBOMs describing intent. Treat that divergence as the point, not a defect.
• inferred attributes are heuristic guesses; for audit evidence under EU AI Act Article 12/50, NIST AI RMF, or ISO/IEC 42001, weight declared fields accordingly and check evidence locators.