Documentation
¶
Overview ¶
Package catalog provides the declarative validator catalog. The catalog defines which validator containers exist, what phase they belong to, and how they should be executed as Kubernetes Jobs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ImagePullPolicy ¶ added in v0.12.0
func ImagePullPolicy(image string) corev1.PullPolicy
ImagePullPolicy returns the appropriate Kubernetes pull policy for a resolved validator image. The caller should pass the image that ResolveImage would return (i.e. after any env-var rewriting); callers that just installed an image from the catalog can reuse this helper so the outer validator Job and any inner workload Jobs (e.g. inference-perf's aiperf-bench Job) stay in lockstep.
Precedence (first match wins):
- Side-loaded refs (ko.local/*, kind.local/*) → Never. No registry to pull from — the image is preloaded via `kind load docker-image`.
- Digest-pinned refs (name@sha256:...) → IfNotPresent. The digest is cryptographically immutable, so a cached copy is always correct; forcing Always here would break disconnected/private clusters that preload images and make kubelet re-contact the registry every run.
- AICR_VALIDATOR_IMAGE_TAG is set → Always. The override is intended for mutable published tags (e.g. `latest`, `edge`, `main` — tags on-push.yaml recreates on every merge); re-pulling prevents node-local caches from serving stale images.
- `:latest` suffix → Always. Mutable tag by convention.
- Otherwise → IfNotPresent. Versioned tag assumed immutable enough that caching is a win.
func ResolveImage ¶ added in v0.12.0
ResolveImage applies the same image rewriting that Load uses for catalog entries, exposed for external callers that hold image references outside the catalog (for example the inner AIPerf benchmark image referenced by the inference-perf validator). Applies, in order:
- :latest tag replacement with version if version is a release (vX.Y.Z).
- If non-release and commit is a valid SHA, :latest → :sha-<commit>.
- Tag override if AICR_VALIDATOR_IMAGE_TAG is set (overrides steps 1-2 AND explicit catalog tags). Intended for feature-branch dev builds where no :sha-<commit> image has been published; typical value: `latest`.
- Registry prefix override if AICR_VALIDATOR_IMAGE_REGISTRY is set.
Images with explicit version tags are not modified by steps 1-2.
Types ¶
type CatalogMetadata ¶
CatalogMetadata contains catalog-level metadata.
type ResourceRequirements ¶
type ResourceRequirements struct {
CPU string `yaml:"cpu,omitempty"`
Memory string `yaml:"memory,omitempty"`
}
ResourceRequirements defines CPU and memory for a validator container.
type ValidatorCatalog ¶
type ValidatorCatalog struct {
APIVersion string `yaml:"apiVersion"`
Kind string `yaml:"kind"`
Metadata CatalogMetadata `yaml:"metadata"`
Validators []ValidatorEntry `yaml:"validators"`
}
ValidatorCatalog is the top-level catalog document.
func Load ¶
func Load(version, commit string) (*ValidatorCatalog, error)
Load reads and parses the validator catalog from the global DataProvider. When the --data flag provides an external directory containing validators/catalog.yaml, the external catalog is merged with the embedded catalog using merge-by-name semantics: external validators override embedded by name, and new validators are appended.
Image tag resolution (applied in order):
- If a catalog entry uses :latest and version is a release (vX.Y.Z), the tag is replaced with the CLI version for reproducibility.
- If version is a non-release dev build and commit is a valid short SHA, the tag is replaced with :sha-<commit> to match on-push.yaml image tags.
- If AICR_VALIDATOR_IMAGE_TAG is set, the resolved tag is overridden. Useful for feature-branch dev builds whose commit SHA has no published image (on-push.yaml only pushes SHA tags for commits merged to main). Common value: `latest`.
- If AICR_VALIDATOR_IMAGE_REGISTRY is set, the registry prefix is replaced.
Entries with explicit version tags (e.g., :v1.2.3) are never modified by steps 1-2 but are replaced by step 3 if that env var is set.
func Parse ¶
func Parse(data []byte) (*ValidatorCatalog, error)
Parse parses a catalog from raw YAML bytes. Exported for testing with inline catalogs without depending on the embedded file.
func (*ValidatorCatalog) ForPhase ¶
func (c *ValidatorCatalog) ForPhase(phase string) []ValidatorEntry
ForPhase returns validators filtered by phase name.
type ValidatorEntry ¶
type ValidatorEntry struct {
// Name is the unique identifier for this validator, used in Job names.
Name string `yaml:"name"`
// Phase is the validation phase: "deployment", "performance", or "conformance".
Phase string `yaml:"phase"`
// Description is a human-readable description of what this validator checks.
Description string `yaml:"description"`
// Image is the OCI image reference for the validator container.
Image string `yaml:"image"`
// Timeout is the maximum execution time for this validator.
// Maps to Job activeDeadlineSeconds.
Timeout time.Duration `yaml:"timeout"`
// Args are the container arguments.
Args []string `yaml:"args"`
// Env are environment variables to set in the container.
Env []EnvVar `yaml:"env"`
// Resources specifies container resource requests/limits.
// If nil, defaults from pkg/defaults are used.
Resources *ResourceRequirements `yaml:"resources,omitempty"`
}
ValidatorEntry defines a single validator container.
Source Files