feat: migrate API domain to aicr.run, bump v1alpha2/v1beta2

[mchmarny]

Summary

Hard-break migration of the AICR artifact API domain aicr.nvidia.com → aicr.run, with the artifact version bumped v1alpha1 → v1alpha2 and the build-spec version v1beta1 → v1beta2. Centralized through a single pkg/header.Domain constant.

Motivation / Context

Tying the artifact contract to nvidia.com couples a vendor-neutral format to one company's brand/DNS and is verbose in every apiVersion, label key, and attestation URI. A group rename is a breaking change, so it is cheapest to land before v1 while still on alpha/beta. The version bump is signal-only (no schema change) — it makes the breaking rename explicit so consumers can distinguish migrated artifacts at a glance. See ADR-013.

Fixes: #1486, #1487, #1488, #1490, #1491, #1493
Related: #1489 (closed as won't-do — superseded by the hard-break decision below)

Type of Change

• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• API server (cmd/aicrd, pkg/server)
• Recipe engine / data (pkg/recipe)
• Bundlers (pkg/bundler, pkg/component/*)
• Collectors / snapshotter (pkg/collector, pkg/snapshotter)
• Validator (pkg/validator)
• Docs/examples (docs/, examples/)
• Other: pkg/header, pkg/evidence, OpenAPI, CI SLSA buildType

Implementation Notes

Three coordinated changes land atomically so CI is never left half-migrated:

• Domain flips on all 5 semantic roles: artifact apiVersion group, K8s label/annotation keys, in-toto/SLSA attestation+provenance URIs, and the UUIDv5 namespace seed — all derived from header.Domain.
• Versions bump: artifacts → aicr.run/v1alpha2; build spec (AICRRuntime) → aicr.run/v1beta2.
• Hard break (no transition window). IsSupportedAPIVersion (and pkg/build.Validate) accept only the new values; legacy aicr.nvidia.com/* and never-published intermediates (aicr.run/v1alpha1) fail closed with an actionable regenerate with … error. This supersedes the dual-accept window originally planned in Transition window: dual-accept aicr.nvidia.com and aicr.run apiVersion on read #1489 — pre-v1 alpha, all internal fixtures regenerate in-PR, external consumers are demo-only/owner-handled.

Three breaking effects to note:

1. Artifacts stamped aicr.nvidia.com/v1alpha1 no longer load — regenerate them.
2. apiVersion is now aicr.run/v1alpha2 (artifacts) / aicr.run/v1beta2 (build spec).
3. Deterministic bundle IDs reset — the aicrBundleNamespace UUIDv5 seed moves to https://aicr.run/bundle/v1, so deterministic-mode bundle IDs change (one-time).

Attestation/provenance URI paths (/bundle/v1, /recipe-evidence/v1, /recipe-catalog/v1, /binary/v1) are unchanged — only the host moved. The verified trust tier still requires NVIDIA-CI identity. The documented install one-liner now uses https://get.aicr.run.

Testing

go build ./...        # clean
go vet ./...          # clean
go test -race ./...   # all green except 5 sigstore-TUF-CDN tests blocked by sandbox network (pass in CI)
golangci-lint run -c .golangci.yaml ./...   # 0 issues

Added/updated tests: table-driven IsSupportedAPIVersion (accepts only new, rejects legacy + intermediates), build-spec legacy-rejection cases, loader fail-closed cases. make qualify's e2e + grype-scan legs run in CI (cluster/network not available locally).

Risk Assessment

• High — Breaking change to the artifact contract and signed attestation URIs.

Rollout notes: Pre-v1, no compatibility promise. Hard break — legacy artifacts must be regenerated (actionable error guides users). Deterministic bundle-ID reset is one-time and documented. External attestation consumers are demo-only and handled offline by the maintainer.

Checklist

• Tests pass locally (make test with -race) — except sandbox-only sigstore network tests
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-feat-1486-aicr-run-domain-v1alpha2.docs.buildwithfern.com/aicr

[github-actions]

Recipe evidence check

Broad impact: recipes/overlays/base.yaml changed; every leaf recipe is
potentially affected. Recipes that carry committed evidence are verified below;
the rest have no evidence yet (best-effort).

Protected recipes

Recipes with committed evidence (recipes/evidence/<slug>/<source>/<digest>.yaml) that this PR affects: 2

Recipe	Source	Pointer	Verify	Digest match
gb200-eks-ubuntu-training	7c4c0edc8c765a95a0f3afdb3bbb8e91	sha256-8274b6a1da24aa9782dc12162bf6a38265c30a852585ca64cfad5718efbbdec3	❌ invalid — registry-forbidden (HTTP 401): registry not accessible (make the fork's aicr-evidence package public, or provide registry credentials)	⚠️ skipped (no signed digest)
h100-gke-cos-training	7c4c0edc8c765a95a0f3afdb3bbb8e91	sha256-33d4cf36622ead990c43a596f6f53c62b87d9fa4708f59b7e3f356f215e54317	❌ invalid — registry-forbidden (HTTP 401): registry not accessible (make the fork's aicr-evidence package public, or provide registry credentials)	⚠️ skipped (no signed digest)

Other affected recipes without evidence yet: 61

These recipes are affected by this PR but carry no committed evidence pointer, so there is
nothing to verify. This is expected — evidence is hardware-gated and added over time.

• a100-aks-training
• a100-aks-ubuntu-training-kubeflow
• a100-aks-ubuntu-training
• a100-eks-training
• a100-eks-ubuntu-training-kubeflow
• a100-eks-ubuntu-training
• a100-gke-cos-training-kubeflow
• a100-gke-cos-training
• a100-oke-training
• a100-oke-ubuntu-training-kubeflow
• a100-oke-ubuntu-training
• b200-gke-cos-inference-dynamo
• b200-gke-cos-inference
• b200-gke-cos-training-kubeflow
• b200-gke-cos-training
• gb200-eks-inference
• gb200-eks-training
• gb200-eks-ubuntu-inference-dynamo
• gb200-eks-ubuntu-inference
• gb200-eks-ubuntu-training-kubeflow
• gb200-oke-inference
• gb200-oke-training
• gb200-oke-ubuntu-inference-dynamo
• gb200-oke-ubuntu-inference
• gb200-oke-ubuntu-training-kubeflow
• gb200-oke-ubuntu-training
• h100-aks-inference
• h100-aks-training
• h100-aks-ubuntu-inference-dynamo
• h100-aks-ubuntu-inference
• h100-aks-ubuntu-training-kubeflow
• h100-aks-ubuntu-training
• h100-bcm-training
• h100-bcm-ubuntu-training
• h100-eks-inference
• h100-eks-training
• h100-eks-ubuntu-inference-dynamo
• h100-eks-ubuntu-inference-nim
• h100-eks-ubuntu-inference
• h100-eks-ubuntu-training-kubeflow
• h100-eks-ubuntu-training-slurm
• h100-eks-ubuntu-training
• h100-gke-cos-inference-dynamo
• h100-gke-cos-inference
• h100-gke-cos-training-kubeflow
• h100-gke-cos-training-slurm
• h100-kind-inference-dynamo
• h100-kind-inference
• h100-kind-training-kubeflow
• h100-kind-training-slurm
• h100-kind-training
• h200-eks-inference
• h200-eks-training
• rtx-pro-6000-eks-inference
• rtx-pro-6000-eks-ubuntu-inference-dynamo
• rtx-pro-6000-eks-ubuntu-inference-nim
• rtx-pro-6000-eks-ubuntu-inference
• rtx-pro-6000-lke-inference
• rtx-pro-6000-lke-training
• rtx-pro-6000-lke-ubuntu-inference
• rtx-pro-6000-lke-ubuntu-training

How to refresh evidence

Run on a cluster matching the recipe's criteria:

aicr snapshot -o snapshot.yaml
aicr validate \
  -r recipes/overlays/<slug>.yaml \
  -s snapshot.yaml \
  --emit-attestation ./out \
  --push ghcr.io/<your-fork>/aicr-evidence
# Copy to the per-source path printed in the emit 'copyTo' hint:
#   recipes/evidence/<slug>/<source>/<bundle-digest>.yaml

This gate is warning-only and never blocks merge. See ADR-007 for the trust model.

[github-actions]

Coverage Report ✅

Metric	Value
Coverage	77.9%
Threshold	75%
Status	Pass

Coverage Badge

![Coverage](https://img.shields.io/badge/coverage-77.9%25-green)

Coverage unchanged by this PR.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 8dc21e95-3dd5-4a50-b37b-18f9fdb1cd3c

📥 Commits

Reviewing files that changed from the base of the PR and between 3e6c471 and a77b378.

📒 Files selected for processing (10)

• api/aicr/v1/server.yaml
• demos/evidence-demo-slides.html
• docs/design/013-aicr-run-domain-migration.md
• pkg/build/spec_test.go
• pkg/cli/snapshot_config_test.go
• pkg/cli/validate_test.go
• pkg/diff/diff_test.go
• pkg/evidence/attestation/builder_test.go
• pkg/header/doc.go
• pkg/validator/v1/conversion_test.go

---

📝 Walkthrough

Walkthrough

The PR updates artifact API versions, label and annotation keys, attestation URIs, manifests, docs, tests, and fixtures from aicr.nvidia.com to aicr.run. It also switches installer references to https://get.aicr.run.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• NVIDIA/aicr#1493: Updates the install-script URL to https://get.aicr.run, which matches the installer URL changes in this PR.

Possibly related PRs

• NVIDIA/aicr#873: Touches the recipe-evidence v1 attestation and pointer predicateType handling that this PR also updates to aicr.run.
• NVIDIA/aicr#879: The main PR updates the evidence-verifier predicateType/buildType URIs to the new aicr.run domain, which directly relates to the verifier parsing and fixture changes in this PR.
• NVIDIA/aicr#1492: Updates the ADR that defines the aicr.run domain migration and compatibility rules.

Suggested labels

enhancement

Suggested reviewers

• lalitadithya
• njhensley

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The code hard-rejects legacy versions, but #1486 explicitly calls for a dual-accept read transition window.	Update the implementation to match the linked issue’s dual-accept behavior, or revise the linked issue to reflect the hard-break decision.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the domain migration and version bumps shown in the diff.
Description check	✅ Passed	The description matches the changes and accurately describes the migration, bumps, and supporting updates.
Out of Scope Changes check	✅ Passed	The changes stay focused on the domain migration and related docs, tests, labels, and attestation updates.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/1486-aicr-run-domain-v1alpha2

---

_{Comment @coderabbitai help to get the list of available commands.}

[njhensley]

📋 Multi-Persona Review — PR #1499 migrate API domain to aicr.run, bump v1alpha2/v1beta2

▎ Method: 4 persona lenses (Supply-chain/Provenance, Correctness, Migration-completeness/API-contract, Docs-Operability), each finding independently confirmed against the resolved code (verifier path, gates, fixtures) by an adversarial meta-pass. Line links pinned to head a77b3784.
▎ Tier legend: 🔴 Blocker · 🟠 Major · 🟡 Minor · 🔵 Nitpick · ✅ Confirmed non-issue

Overall assessment — ✅ Approve with comments

This is a well-executed hard-break domain migration: every semantic role (apiVersion group, K8s label/annotation keys, attestation/build-type URIs, UUIDv5 seed) now derives from a single header.Domain constant, the fail-closed gates (IsSupportedAPIVersion, build.Validate) have table-driven legacy-rejection tests, and the rename is complete — the only residual aicr.nvidia.com strings are in ADRs, rejection tests, and one explanatory comment. The one substantive issue is in the signed-evidence layer: two checked-in evidence pointers had their predicateType rewritten while their pinned OCI digests stayed the same, which silently breaks end-to-end verification of those bundles. It does not break CI and is pre-v1 demo data, so it's a Major, not a Blocker.

✅ Confirmed non-issues (checked and cleared)

• Migration completeness — grepped the PR head: no aicr.nvidia.com remains in any runtime-loaded data (recipes/, pkg/, cmd/, examples/, kwok/, api/) or non-test Go. Residuals are confined to ADRs, legacy-rejection tests, and one doc comment — all intentional.
• pkg/cli/validate.go log-line change — kubectl logs -l aicr.run/run-id=<runID> is correct; labels.RunID is genuinely applied to validation Jobs (job_plan.go:256, ctrf/configmap.go:70). The old aicr.nvidia.com/job selector matched no actual label key, so this is a fix, not a regression.
• build.Validate — correctly gates on ExpectedAPIVersion = header.Domain + "/v1beta2" (spec.go:131) with new tests rejecting both aicr.nvidia.com/v1beta1 and the stale aicr.run/v1beta1.
• UUIDv5 namespace reset — intentional, documented in ADR-013 and the aicrBundleNamespace comment; no golden/testdata bundle IDs left stale.
• Hard-break gate — IsSupportedAPIVersion rejects legacy group, old-group/new-version, and new-group/old-version combos, all covered by table-driven tests.

Summary

Tier	Count	Items
🔴 Blocker	0	—
🟠 Major	1	Evidence pointer predicateType rewritten without re-signing → verification fails for 2 bundles
🟡 Minor	1	Install one-liner depends on get.aicr.run being live
🔵 Nitpick	0	—

Recommendation: Approve with comments. Resolve the 🟠 before relying on those evidence bundles (re-sign + re-digest the two pointers, or revert/delete them) — it ships an unverifiable signed artifact while CI stays green; the 🟡 is a pre-merge sanity check on the new install host.