config

package
v0.13.0-rc2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 14, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package config defines the AICRConfig file schema accepted by the aicr CLI's --config flag on the recipe and bundle commands.

AICRConfig is a Kubernetes-style envelope (kind / apiVersion / metadata / spec) that lets users capture flag values for both commands in a single YAML or JSON document. CLI flags always override values loaded from a config file; for slice/map flags, presence on the command line replaces the file's value rather than appending.

Sources are restricted to local file paths and HTTP/HTTPS URLs. ConfigMap (cm://) URIs are intentionally rejected: extract the data with kubectl and pass the resulting file instead.

Secrets (notably the cosign identity token) are not part of the schema; they must be supplied via environment variables or dedicated CLI flags.

Index

Constants

View Source
const APIVersion = "aicr.nvidia.com/v1alpha1"

APIVersion is the apiVersion for AICRConfig documents.

View Source
const Kind = "AICRConfig"

Kind is the kind value for AICRConfig documents.

Variables

This section is empty.

Functions

This section is empty.

Types

type AICRConfig

type AICRConfig struct {
	Kind       string   `yaml:"kind" json:"kind"`
	APIVersion string   `yaml:"apiVersion" json:"apiVersion"`
	Metadata   Metadata `yaml:"metadata" json:"metadata"`
	Spec       Spec     `yaml:"spec" json:"spec"`
}

AICRConfig is the top-level schema for the --config file accepted by the aicr CLI's recipe, bundle, and validate commands.

func Load

func Load(ctx context.Context, source string) (*AICRConfig, error)

Load reads and parses an AICRConfig from a local file path or HTTP(S) URL. ConfigMap (cm://) URIs are rejected.

Decoding is strict: unknown fields cause an error, so typos like `spec.bundel.deployment.deployer` fail at load time rather than silently producing zero values.

The returned AICRConfig is fully validated: kind/apiVersion match the expected constants, criteria enums parse against pkg/recipe parsers, and the deployer string parses against pkg/bundler/config.

func (*AICRConfig) Bundle

func (c *AICRConfig) Bundle() *BundleSpec

Bundle returns the bundle section, or nil if cfg or the section is unset.

func (*AICRConfig) Recipe

func (c *AICRConfig) Recipe() *RecipeSpec

Recipe returns the recipe section, or nil if cfg or the section is unset.

func (*AICRConfig) Validate

func (c *AICRConfig) Validate() error

Validate checks that an AICRConfig is well-formed and that all enumerated values are recognized by the corresponding recipe / bundler parsers.

Validate does NOT check semantic interactions across the recipe and bundle commands (for example, that a bundle.input.recipe path actually exists); such checks belong to the caller that consumes the config.

func (*AICRConfig) Validation

func (c *AICRConfig) Validation() *ValidateSpec

Validation returns the validate section, or nil if cfg or the section is unset. Named Validation (not Validate) to avoid colliding with (*AICRConfig).Validate, which checks well-formedness of the whole config.

type AttestationSpec

type AttestationSpec struct {
	Enabled                   bool   `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	CertificateIdentityRegexp string `yaml:"certificateIdentityRegexp,omitempty" json:"certificateIdentityRegexp,omitempty"`
	OIDCDeviceFlow            bool   `yaml:"oidcDeviceFlow,omitempty" json:"oidcDeviceFlow,omitempty"`
}

AttestationSpec captures bundle attestation inputs.

IdentityToken is intentionally absent: tokens are secrets and must be supplied via the COSIGN_IDENTITY_TOKEN environment variable or the --identity-token flag.

type BundleInputSpec

type BundleInputSpec struct {
	Recipe string `yaml:"recipe,omitempty" json:"recipe,omitempty"`
}

BundleInputSpec captures input file paths for the bundle command.

type BundleOutputSpec

type BundleOutputSpec struct {
	// Target is a local directory path or an oci:// URI.
	Target    string `yaml:"target,omitempty" json:"target,omitempty"`
	ImageRefs string `yaml:"imageRefs,omitempty" json:"imageRefs,omitempty"`
}

BundleOutputSpec describes the bundle output destination.

type BundleResolved

type BundleResolved struct {
	// RecipeInput is spec.bundle.input.recipe.
	RecipeInput string

	// OutputTarget is the parsed spec.bundle.output.target. Nil when
	// config did not set a target. OutputTargetRaw preserves the original
	// string for log/error messages.
	OutputTarget    *oci.Reference
	OutputTargetRaw string

	// ImageRefs is spec.bundle.output.imageRefs.
	ImageRefs string

	// Deployer is the parsed spec.bundle.deployment.deployer. Empty
	// (zero) when config did not set a deployer.
	Deployer bundlercfg.DeployerType

	// Repo is spec.bundle.deployment.repo.
	Repo string

	// ValueOverrides is spec.bundle.deployment.set, parsed.
	// Nil if config did not set the field; non-nil (possibly empty) if
	// config provided an explicit list (including `set: []`).
	ValueOverrides []bundlercfg.ComponentPath

	// DynamicValues is spec.bundle.deployment.dynamic, parsed.
	// Same nil-vs-empty semantics as ValueOverrides.
	DynamicValues []bundlercfg.ComponentPath

	// SystemNodeSelector is spec.bundle.scheduling.systemNodeSelector.
	// Nil if config did not set it; non-nil empty if `{}` was explicit.
	SystemNodeSelector map[string]string

	// SystemNodeTolerations is spec.bundle.scheduling.systemNodeTolerations,
	// parsed. Nil if config did not set the field.
	SystemNodeTolerations []corev1.Toleration

	// AcceleratedNodeSelector is spec.bundle.scheduling.acceleratedNodeSelector.
	AcceleratedNodeSelector map[string]string

	// AcceleratedNodeTolerations is the parsed slice.
	AcceleratedNodeTolerations []corev1.Toleration

	// WorkloadGate is the parsed spec.bundle.scheduling.workloadGate taint.
	// Nil when config did not set it.
	WorkloadGate *corev1.Taint

	// WorkloadSelector is spec.bundle.scheduling.workloadSelector.
	WorkloadSelector map[string]string

	// Nodes is spec.bundle.scheduling.nodes; 0 when unset.
	Nodes int

	// StorageClass is spec.bundle.scheduling.storageClass.
	StorageClass string

	// Attest is spec.bundle.attestation.enabled.
	Attest bool

	// CertIDRegexp is spec.bundle.attestation.certificateIdentityRegexp.
	CertIDRegexp string

	// OIDCDeviceFlow is spec.bundle.attestation.oidcDeviceFlow.
	OIDCDeviceFlow bool

	// InsecureTLS is spec.bundle.registry.insecureTLS.
	InsecureTLS bool

	// PlainHTTP is spec.bundle.registry.plainHTTP.
	PlainHTTP bool

	// VendorCharts is spec.bundle.deployment.vendorCharts. When true,
	// upstream Helm chart bytes are pulled into the bundle at bundle time
	// so the resulting artifact is air-gap deployable. Off by default.
	VendorCharts bool
}

BundleResolved is the typed-domain projection of BundleSpec produced by (*BundleSpec).Resolve. Every field is converted from its wire form exactly once at the conversion boundary; CLI and API consumers layer flag overrides on top of these values rather than re-parsing strings.

Zero values mean "config did not set this field." Maps and slices preserve the nil-vs-explicitly-empty distinction from the wire spec — callers can therefore detect whether a user wrote `selector: {}` to clear an inherited default vs. omitted the key entirely.

type BundleSpec

type BundleSpec struct {
	Input       *BundleInputSpec  `yaml:"input,omitempty" json:"input,omitempty"`
	Output      *BundleOutputSpec `yaml:"output,omitempty" json:"output,omitempty"`
	Deployment  *DeploymentSpec   `yaml:"deployment,omitempty" json:"deployment,omitempty"`
	Scheduling  *SchedulingSpec   `yaml:"scheduling,omitempty" json:"scheduling,omitempty"`
	Attestation *AttestationSpec  `yaml:"attestation,omitempty" json:"attestation,omitempty"`
	Registry    *RegistrySpec     `yaml:"registry,omitempty" json:"registry,omitempty"`
}

BundleSpec captures the inputs to `aicr bundle`.

func (*BundleSpec) Resolve

func (b *BundleSpec) Resolve() (*BundleResolved, error)

Resolve converts a BundleSpec from the wire-string form to a typed BundleResolved. It is nil-receiver tolerant and never returns a nil pointer — callers reach into fields, so nil would just relocate the nil-pointer dereference.

Errors are attributed to their source spec path (for example, "spec.bundle.deployment.set") so callers can surface the location of invalid input without reconstructing the path themselves.

type CriteriaSpec

type CriteriaSpec struct {
	Service     string `yaml:"service,omitempty" json:"service,omitempty"`
	Accelerator string `yaml:"accelerator,omitempty" json:"accelerator,omitempty"`
	Intent      string `yaml:"intent,omitempty" json:"intent,omitempty"`
	OS          string `yaml:"os,omitempty" json:"os,omitempty"`
	Platform    string `yaml:"platform,omitempty" json:"platform,omitempty"`
	Nodes       int    `yaml:"nodes,omitempty" json:"nodes,omitempty"`
}

CriteriaSpec mirrors the recipe query parameters. Field names and string values match the corresponding CLI flags so a config file can be read alongside an aicr recipe invocation without translation.

Values are stored as strings (rather than typed enums) so the loader can surface validation errors with the same messages as the CLI parsers.

type DeploymentSpec

type DeploymentSpec struct {
	Deployer     string   `yaml:"deployer,omitempty" json:"deployer,omitempty"`
	Repo         string   `yaml:"repo,omitempty" json:"repo,omitempty"`
	Set          []string `yaml:"set,omitempty" json:"set,omitempty"`
	Dynamic      []string `yaml:"dynamic,omitempty" json:"dynamic,omitempty"`
	VendorCharts bool     `yaml:"vendorCharts,omitempty" json:"vendorCharts,omitempty"`
}

DeploymentSpec captures deployer choice and value-override inputs.

type EvidenceAttestationResolved

type EvidenceAttestationResolved struct {
	Out         string
	BOM         string
	Push        string
	PlainHTTP   bool
	InsecureTLS bool
}

EvidenceAttestationResolved is the typed view of spec.validate.evidence.attestation. See EvidenceCNCFResolved for the nil-flatten rationale.

type EvidenceAttestationSpec

type EvidenceAttestationSpec struct {
	// Setting Out enables the attestation path; empty leaves it off
	// even if other fields are populated.
	Out string `yaml:"out,omitempty" json:"out,omitempty"`

	BOM  string `yaml:"bom,omitempty" json:"bom,omitempty"`
	Push string `yaml:"push,omitempty" json:"push,omitempty"`

	// Pointer fields so the spec layer can distinguish nil (absent in
	// YAML/JSON) from &false (explicit opt-out). The resolved layer
	// flattens to plain bool — see EvidenceAttestationResolved.
	PlainHTTP   *bool `yaml:"plainHTTP,omitempty" json:"plainHTTP,omitempty"`
	InsecureTLS *bool `yaml:"insecureTLS,omitempty" json:"insecureTLS,omitempty"`
}

EvidenceAttestationSpec configures the recipe-evidence v1 bundle path (--emit-attestation / --bom / --push / --plain-http / --insecure-tls). Bundle format is documented in ADR-007.

The OIDC identity token used by --push is intentionally absent: tokens are short-lived secrets and must not be embedded in version-controlled configuration. The CLI resolves it at sign time.

type EvidenceCNCFResolved

type EvidenceCNCFResolved struct {
	Dir            string
	CNCFSubmission bool
	Features       []string
}

EvidenceCNCFResolved is the typed view of spec.validate.evidence.cncf. Bool fields flatten the spec layer's *bool to plain bool: nil (absent in YAML/JSON) becomes false, and downstream consumers do not need to distinguish nil from &false for these specific feature toggles (default is false in both cases).

type EvidenceCNCFSpec

type EvidenceCNCFSpec struct {
	Dir string `yaml:"dir,omitempty" json:"dir,omitempty"`

	// Requires Dir. Pointer so the spec layer can distinguish nil
	// (absent in YAML/JSON) from &false (explicit opt-out); the
	// resolved layer flattens to plain bool — see EvidenceCNCFResolved.
	CNCFSubmission *bool `yaml:"cncfSubmission,omitempty" json:"cncfSubmission,omitempty"`

	// Empty = all features. Only honored when CNCFSubmission is true.
	Features []string `yaml:"features,omitempty" json:"features,omitempty"`
}

EvidenceCNCFSpec configures the CNCF AI Conformance evidence path (--evidence-dir / --cncf-submission / --feature).

type EvidenceSpec

type EvidenceSpec struct {
	CNCF        *EvidenceCNCFSpec        `yaml:"cncf,omitempty" json:"cncf,omitempty"`
	Attestation *EvidenceAttestationSpec `yaml:"attestation,omitempty" json:"attestation,omitempty"`
}

EvidenceSpec is the umbrella for the two evidence kinds `aicr validate` can emit: CNCF AI Conformance markdown (CNCF) and the recipe-evidence v1 bundle (Attestation). Either or both may be populated; an unset section means the corresponding kind is CLI-only.

type Metadata

type Metadata struct {
	Name string `yaml:"name,omitempty" json:"name,omitempty"`
}

Metadata holds identifying information for an AICRConfig document.

type RecipeInputSpec

type RecipeInputSpec struct {
	Snapshot string `yaml:"snapshot,omitempty" json:"snapshot,omitempty"`
}

RecipeInputSpec describes alternate inputs to recipe generation. Snapshot is mutually exclusive with Criteria at the top of RecipeSpec.

type RecipeOutputSpec

type RecipeOutputSpec struct {
	Path   string `yaml:"path,omitempty" json:"path,omitempty"`
	Format string `yaml:"format,omitempty" json:"format,omitempty"`
}

RecipeOutputSpec describes how the recipe is emitted.

type RecipeSpec

type RecipeSpec struct {
	Criteria *CriteriaSpec     `yaml:"criteria,omitempty" json:"criteria,omitempty"`
	Input    *RecipeInputSpec  `yaml:"input,omitempty" json:"input,omitempty"`
	Output   *RecipeOutputSpec `yaml:"output,omitempty" json:"output,omitempty"`
	Data     string            `yaml:"data,omitempty" json:"data,omitempty"`
}

RecipeSpec captures the inputs to `aicr recipe`.

func (*RecipeSpec) DataDir

func (r *RecipeSpec) DataDir() string

DataDir returns spec.recipe.data, or "" when unset.

func (*RecipeSpec) OutputFormat

func (r *RecipeSpec) OutputFormat() string

OutputFormat returns spec.recipe.output.format, or "" when unset.

func (*RecipeSpec) OutputPath

func (r *RecipeSpec) OutputPath() string

OutputPath returns spec.recipe.output.path, or "" when unset.

func (*RecipeSpec) ResolveCriteria

func (r *RecipeSpec) ResolveCriteria() (*recipe.Criteria, error)

ResolveCriteria converts the recipe criteria spec from wire-string form to a typed *recipe.Criteria. Nil-receiver tolerant; never returns a nil pointer.

Unlike recipe.NewCriteria, the returned Criteria does NOT default unset fields to "any": empty enum fields signal "config did not set this slot" so callers can detect what to copy onto a target Criteria. Nodes < 0 is rejected; Nodes == 0 means unset.

func (*RecipeSpec) SnapshotPath

func (r *RecipeSpec) SnapshotPath() string

SnapshotPath returns spec.recipe.input.snapshot, or "" when unset.

type RegistrySpec

type RegistrySpec struct {
	InsecureTLS bool `yaml:"insecureTLS,omitempty" json:"insecureTLS,omitempty"`
	PlainHTTP   bool `yaml:"plainHTTP,omitempty" json:"plainHTTP,omitempty"`
}

RegistrySpec captures OCI-registry transport options for bundle push.

type SchedulingSpec

type SchedulingSpec struct {
	SystemNodeSelector         map[string]string `yaml:"systemNodeSelector,omitempty" json:"systemNodeSelector,omitempty"`
	SystemNodeTolerations      []string          `yaml:"systemNodeTolerations,omitempty" json:"systemNodeTolerations,omitempty"`
	AcceleratedNodeSelector    map[string]string `yaml:"acceleratedNodeSelector,omitempty" json:"acceleratedNodeSelector,omitempty"`
	AcceleratedNodeTolerations []string          `yaml:"acceleratedNodeTolerations,omitempty" json:"acceleratedNodeTolerations,omitempty"`
	WorkloadGate               string            `yaml:"workloadGate,omitempty" json:"workloadGate,omitempty"`
	WorkloadSelector           map[string]string `yaml:"workloadSelector,omitempty" json:"workloadSelector,omitempty"`
	Nodes                      int               `yaml:"nodes,omitempty" json:"nodes,omitempty"`
	StorageClass               string            `yaml:"storageClass,omitempty" json:"storageClass,omitempty"`
}

SchedulingSpec captures node-placement inputs for system and accelerated workloads.

Selectors are YAML maps for readability; tolerations are strings in the same `key=value:effect` format the CLI accepts so users can copy/paste between command lines and config files.

type Spec

type Spec struct {
	Recipe   *RecipeSpec   `yaml:"recipe,omitempty" json:"recipe,omitempty"`
	Bundle   *BundleSpec   `yaml:"bundle,omitempty" json:"bundle,omitempty"`
	Validate *ValidateSpec `yaml:"validate,omitempty" json:"validate,omitempty"`
}

Spec contains the per-command sections.

Each section is optional: a config file used only with `aicr recipe` may populate just Recipe; one used only with `aicr bundle` may populate just Bundle. A single file may populate any combination for end-to-end workflows.

type ValidateAgentSpec

type ValidateAgentSpec struct {
	Namespace          string            `yaml:"namespace,omitempty" json:"namespace,omitempty"`
	Image              string            `yaml:"image,omitempty" json:"image,omitempty"`
	ImagePullSecrets   []string          `yaml:"imagePullSecrets,omitempty" json:"imagePullSecrets,omitempty"`
	JobName            string            `yaml:"jobName,omitempty" json:"jobName,omitempty"`
	ServiceAccountName string            `yaml:"serviceAccountName,omitempty" json:"serviceAccountName,omitempty"`
	NodeSelector       map[string]string `yaml:"nodeSelector,omitempty" json:"nodeSelector,omitempty"`
	Tolerations        []string          `yaml:"tolerations,omitempty" json:"tolerations,omitempty"`
	RequireGPU         bool              `yaml:"requireGpu,omitempty" json:"requireGpu,omitempty"`
}

ValidateAgentSpec configures the in-cluster snapshot-capture and validation-job pods. Empty fields use the validator's compiled-in defaults; selectors/tolerations omitted entirely (nil) inherit, while an explicit empty map/list (`{}` / `[]`) clears the default.

type ValidateExecutionSpec

type ValidateExecutionSpec struct {
	Phases      []string `yaml:"phases,omitempty" json:"phases,omitempty"`
	FailOnError *bool    `yaml:"failOnError,omitempty" json:"failOnError,omitempty"`
	NoCluster   bool     `yaml:"noCluster,omitempty" json:"noCluster,omitempty"`
	NoCleanup   bool     `yaml:"noCleanup,omitempty" json:"noCleanup,omitempty"`
	Timeout     string   `yaml:"timeout,omitempty" json:"timeout,omitempty"`
}

ValidateExecutionSpec controls validation behavior independent of where the agent runs.

FailOnError is a pointer because the CLI flag defaults to true. A nil value means "config did not set this slot," letting CLI defaults flow through; *false means "config explicitly opted out of fail-on-error."

Timeout is the wire-string form (e.g. "5m"); Resolve parses it to a time.Duration with errors attributed to spec.validate.execution.timeout.

type ValidateInputSpec

type ValidateInputSpec struct {
	Recipe   string `yaml:"recipe,omitempty" json:"recipe,omitempty"`
	Snapshot string `yaml:"snapshot,omitempty" json:"snapshot,omitempty"`
}

ValidateInputSpec captures the recipe + snapshot inputs to validation.

type ValidateResolved

type ValidateResolved struct {
	// RecipePath is spec.validate.input.recipe.
	RecipePath string

	// SnapshotPath is spec.validate.input.snapshot.
	SnapshotPath string

	// Namespace is spec.validate.agent.namespace.
	Namespace string

	// Image is spec.validate.agent.image.
	Image string

	// ImagePullSecrets is spec.validate.agent.imagePullSecrets. Nil if
	// config did not set the field.
	ImagePullSecrets []string

	// JobName is spec.validate.agent.jobName.
	JobName string

	// ServiceAccountName is spec.validate.agent.serviceAccountName.
	ServiceAccountName string

	// NodeSelector is spec.validate.agent.nodeSelector. Nil if unset;
	// non-nil empty if `{}` was explicit.
	NodeSelector map[string]string

	// Tolerations is the parsed spec.validate.agent.tolerations slice.
	// Nil if config did not set the field.
	Tolerations []corev1.Toleration

	// RequireGPU is spec.validate.agent.requireGpu.
	RequireGPU bool

	// Phases is spec.validate.execution.phases. Nil if unset.
	Phases []string

	// FailOnError is spec.validate.execution.failOnError. Nil pointer
	// signals "config did not set the field" so the caller can defer to
	// the CLI flag's default.
	FailOnError *bool

	// NoCluster is spec.validate.execution.noCluster.
	NoCluster bool

	// NoCleanup is spec.validate.execution.noCleanup.
	NoCleanup bool

	// Timeout is the parsed spec.validate.execution.timeout. Nil pointer
	// signals "config did not set the field" so callers can fall through
	// to the CLI flag's default duration; non-nil preserves an explicit
	// "0s" / disabled-timeout value distinct from absence.
	Timeout *time.Duration

	// Nil when spec.validate.evidence.cncf is unset.
	EvidenceCNCF *EvidenceCNCFResolved

	// Nil when spec.validate.evidence.attestation is unset.
	EvidenceAttestation *EvidenceAttestationResolved
}

ValidateResolved is the typed-domain projection of ValidateSpec produced by (*ValidateSpec).Resolve. Conversion from the wire form happens exactly once at this boundary; CLI consumers layer flag overrides on top of these values rather than re-parsing the spec strings.

Zero values mean "config did not set this field." Maps and slices preserve nil-vs-explicitly-empty from the wire spec — callers can detect whether a user wrote `nodeSelector: {}` to clear an inherited default vs. omitted the field entirely.

type ValidateSpec

type ValidateSpec struct {
	Input     *ValidateInputSpec     `yaml:"input,omitempty" json:"input,omitempty"`
	Agent     *ValidateAgentSpec     `yaml:"agent,omitempty" json:"agent,omitempty"`
	Execution *ValidateExecutionSpec `yaml:"execution,omitempty" json:"execution,omitempty"`
	Evidence  *EvidenceSpec          `yaml:"evidence,omitempty" json:"evidence,omitempty"`
}

ValidateSpec captures the inputs to `aicr validate`. Evidence emission (both CNCF AI Conformance markdown and the recipe-evidence v1 bundle) is configured via the Evidence umbrella (EvidenceSpec) — see that type for the per-kind shape and the corresponding `aicr validate --…` flag surface.

func (*ValidateSpec) Resolve

func (v *ValidateSpec) Resolve() (*ValidateResolved, error)

Resolve converts a ValidateSpec from the wire-string form to a typed ValidateResolved. It is nil-receiver tolerant and never returns a nil pointer — callers reach into fields, so nil would just relocate the nil-pointer dereference.

Errors are attributed to their source spec path (for example, "spec.validate.agent.tolerations") so callers can surface the location of invalid input without reconstructing the path themselves.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL