docs(design): ADR-015 recipe-declared configuration profiles#1762
docs(design): ADR-015 recipe-declared configuration profiles#1762yuanchen8911 wants to merge 1 commit into
Conversation
yuanchen8911
added
the
theme/recipes
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds ADR-015 for recipe-declared configuration profiles. It defines profile declarations and fragments, generation-time selection and validation, ownership manifests in Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/015-recipe-configuration-profiles.md`:
- Around line 116-120: Clarify the profile fragment contract in the ADR by
defining which validation fields profile values may adjust, how those
adjustments merge with base validation, and how conflicting values are resolved;
alternatively, remove optional validation adjustments from the documented
profile syntax and related description.
- Around line 141-161: Update the AKS “driver-only” example in the configuration
profiles documentation so it is clearly marked illustrative/TBD and
non-shippable, or remove the example entirely. Do not present driver-only as a
usable profile until an authoritative node-pool-mode validation signal is
identified and documented.
- Around line 237-240: Define the missing-default case in the profile validation
algorithm: when the caller omits --profile and the declaration provides no
default, require an explicit selection and return ErrCodeInvalidRequest.
Preserve declared-default application when available and enforce exactly one
profile value for the resulting recipe.
- Around line 270-278: Update the hydration verification described in the recipe
configuration profile design to validate the complete effective profile
manifest, including non-policy locks such as driver.enabled, toolkit.enabled,
and dcgmExporter.env, rather than only the allocation-policy closure. Since
hydration retains only the selected profile and manifest, specify persisting
sufficient declaration/provenance data or validating the full manifest without
consulting the catalog, and apply the same correction to the related section
around lines 373-393.
- Around line 270-278: Update the profile-selection specification near the
manifest description to define one normalization step across CLI arguments,
config files, client options, query parameters, and request bodies. Require
contradictory selector values to be rejected rather than resolved by precedence,
and state that only a consistent normalized selection may reach adoptRecipe and
RecipeMetadata.Spec.
- Around line 359-367: Update the canonical `#1327` policy closure in the recipe
configuration profile documentation to include both `gpu-operator` and
`gpu-operator-ocp`. Ensure the shared descriptor covers each advertiser’s
`devicePlugin.enabled` and `enabled` paths, including their aliases, so OCP
profile-owned policy values are locked.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 08e93d0c-c7e8-4acd-b807-07ea3e1f10be
📒 Files selected for processing (1)
docs/design/015-recipe-configuration-profiles.md
1efa627 to
9de71c8
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/015-recipe-configuration-profiles.md`:
- Around line 452-472: Update PrepareAndValidate to require selectedProfile
whenever an advertiser declaration exists, verify its profile name and value
against the persisted declaration, and validate the complete manifest including
non-policy locks. Reject incoherent advertiser tuples, including advertiser:
operator when both the operator device plugin and DRA are enabled, while
preserving complete allocation-policy closure validation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 18bb9d08-2c3e-4cc5-a066-ca5c12959329
📒 Files selected for processing (1)
docs/design/015-recipe-configuration-profiles.md
e52aa21 to
50ccb07
Compare
acc9b80 to
57deb76
Compare
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
43a5d2d to
e7b7085
Compare
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
e7b7085 to
6a99627
Compare
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
yuanchen8911
changed the title
|
Ready for design review. Orientation is in the PR description; the full design is Please focus on (1) whether the proposed design is sound, and (2) opportunities to simplify — the ADR holds itself to "every element must trace to a concrete failure it prevents," and challenges under that bar are welcome. The Deferred Adoption Decisions section at the end of the doc is non-gating (each item is routed to implementation or consumer work); implementation tracking is #1761. |
6a99627 to
b8cb79d
Compare
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
b8cb79d to
368d30d
Compare
|
🌿 Preview your docs: https://nvidia-preview-adr-015-recipe-declared-params.docs.buildwithfern.com/aicr |
d2787ef to
f725b16
Compare
Signed-off-by: Yuan Chen <yuanchen97@gmail.com>
2 participants
Summary
Adds ADR-015: recipe-declared configuration profiles. An overlay may declare a single named profile enum (e.g.
gpuStack: operator | csp-managed); exactly one value is selected at recipe generation and hydrated into the artifact with a compact ownership record — so multiple qualified cluster configurations per criteria combination stay validated against the recipe. The design is deliberately minimal:componentRefs[].overrides+constraints) — no new templating, no parameter language./v1→/v2client migration), never an implicit upgrade.Motivation / Context
One criteria combination increasingly maps to more than one valid cluster configuration (GKE device-plugin ownership, AKS driver-only vs operator-managed pools). Today the only outlets are bundle-time
--set(invisible to validation — the deployed config silently diverges from whataicr validatechecks) or new criteria axes (recipe-matrix growth).The ADR chooses a middle path. It specifies the required amendments to the #1327 allocation-policy model (recipe-declared external advertiser, recomputed complete-tuple locking, hydration-boundary coherence checks, one dependency-neutral descriptor + evaluator) and an explicit ADR-011 amendment (profile-bearing recipes ride a new artifact apiVersion so released binaries fail closed instead of silently dropping the profile).
Motivating examples (both specified in the ADR):
operator(GKE driver + Operator's plugin; stock, opt-out label required),csp-managed(GKE driver + GKE's managed plugin;advertiser: external, opposite label constraint), andoperator-selfdriver(driver installed by a new values-gatedgcp-driver-installercomponent + Operator's plugin — the DGXC/NKX case, declared once its durable ownership-mode distinguishing signal is identified).driver.enabled=false,toolkit.enabled=false,operator.runtimeClass=nvidia-container-runtime, all three together).The profile direction reached consensus in internal design discussion (2026-07-14). Remaining decision points are listed in the ADR's Deferred Adoption Decisions section — none changes the mechanism or gates acceptance; each is routed to #1761 or the consumer work that resolves it. The Deferred Decision 4 catalog-compatibility follow-up is filed as #1812.
Fixes: N/A
Related: #1761 (implementation tracking), #1755 (GKE label check — first GKE consumer dependency), #1327 (allocation-policy contract being amended)
Type of Change
Component(s) Affected
docs/,examples/)Implementation Notes
Design-only PR — no code changes. Key decisions recorded in the ADR:
enabledpath.RecipeResultboundary from one canonical descriptor + shared evaluator. Rendered outputs are the exception — descriptor-expansion remediation is outcome-based (regenerate every previously rendered profiled output that diverges or stays install-time-mutable at a newly locked path, or conservatively all affected outputs), and each expansion is a re-qualification/evidence re-signing event with profile-bearing evidence current only when both the recipe digest and the scoped descriptor identity (the descriptor entries contributing to that recipe's effective closure) match (a profile-scoped ADR-007 amendment).advertiser: externalas the only reserved marker.advertiser/constraints/componentRefs; each ref:name/overridesonly; novaluesFile; existing components only.device-plugin-extended-resource).Compatibility: landing the mechanism alone is non-breaking by construction.
/v1endpoints, and released binaries are unaffected.aicr mirror listgains the shared context-aware validation gate (no rejection for well-formed recipes; it validates a defensive copy, soDiscoveroutput and the caller's artifact are unchanged); raw-artifact boundaries reject unknown-apiVersion artifacts that today pass unchecked; legacy/empty-version artifacts carryingselectedProfileare newly rejected (today's non-strict decode silently drops the field); legacy/empty-version profile-declaring overlays are newly rejected at catalog load (today the kind-only loader silently yields an unprofiled catalog); new-version overlays without a declaration are newly rejected at catalog load (today accepted kind-only); and/v1requests carrying explicit profile input are newly rejected (today the parameter is silently dropped)./v1rejection of ordinary criteria requests, evidence re-signing) are deferred to each family's explicit profile conversion — a documented per-family qualification and cut-over event (see the ADR's Consequences section).Design-review PR: implementation (#1761) starts after this design is accepted.
Testing
Doc-only change: a single new file,
docs/design/015-recipe-configuration-profiles.md. No code, no user-facing docs pages, no sidebar entries (design docs are not part of the Fern site).Full
make qualifywas run against an earlier revision of this file and passed (78.8% coverage, zero lint issues, 23/23 E2E, vulnerability gate). Subsequent revisions are prose-only edits to the same single file with no new external links, verified with scoped checks per the doc-only rule: heading/anchor hygiene reviewed,git diff --checkclean, and Fern Docs CI (including the link checker) passing on the pushed head.Risk Assessment
Rollout notes: N/A — no behavior change until #1761 lands.
Checklist
make testwith-race)make lint)git commit -S)