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 ¶
const TrustedValidatorRepoPrefix = "ghcr.io/nvidia/aicr-validators/"
TrustedValidatorRepoPrefix is the repository namespace whose tag conventions AICR's own workflows enforce: on-tag.yaml freezes :vX.Y.Z there, on-push.yaml writes :sha-<commit> there, and the UAT lanes write :uat-<run_id> there. Those guarantees are properties of the publisher, not of the tag text.
Variables ¶
This section is empty.
Functions ¶
func IsImmutableRef ¶ added in v0.22.0
IsImmutableRef reports whether image is a reference that dereferences to the same content every time it is resolved. It is an allowlist: anything not positively recognized — including a tag shape or registry added later — is reported mutable so a caller gating on provenance fails closed.
Two ways to qualify:
- A digest-pinned ref (name@<alg>:<hex>), from any registry. The digest is the pin, so no publisher promise is needed.
- A tag AICR's CI freezes, AND a repository under TrustedValidatorRepoPrefix where that freezing actually happens: :vX.Y.Z and :vX.Y.Z-<prerelease> (on-tag.yaml; the goreleaser -next snapshot string is excluded — no image is ever published under it), :sha-<40-hex> (on-push.yaml), and :uat-<run_id> (the UAT lanes, scoped to one run of one commit, so a re-run rebuilds the same source).
The prefix requirement is the load-bearing half. Tag syntax is not proof of immutability: a third-party or mirrored registry reached via an external catalog or AICR_VALIDATOR_IMAGE_REGISTRY may repoint its own :v1.0.0 freely, and nothing in this repository constrains it. Such a ref must be digest- pinned to vouch for provenance.
Mutable: :edge and :latest (both advance by design — see the publishing table in docs/contributor/validator.md), an untagged ref (an implicit :latest), any tag outside the trusted prefix, and every other tag.
Within the trusted prefix this is the inverse contract of ResolveImage: every tag ResolveImage derives on its own must be accepted, so the two must be changed together. A new resolution path added without a matching shape below fails TestIsImmutableRefAcceptsResolveImageOutput rather than a UAT lane.
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 looks like a release tag published by on-tag.yaml — strict (vX.Y.Z) or a pre-release suffix (vX.Y.Z-rc1, vX.Y.Z-beta, vX.Y.Z-alpha.1). Goreleaser snapshot strings (suffix -next) are NOT releases and fall through to step 2.
- 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 ¶
type CatalogMetadata = v1.CatalogMetadata
Re-exported types from pkg/validator/v1 so callers that work with the catalog do not have to import the wire-format package directly.
type EnvVar ¶
Re-exported types from pkg/validator/v1 so callers that work with the catalog do not have to import the wire-format package directly.
type ResourceRequirements ¶
type ResourceRequirements = v1.ResourceRequirements
Re-exported types from pkg/validator/v1 so callers that work with the catalog do not have to import the wire-format package directly.
type ValidatorCatalog ¶
type ValidatorCatalog = v1.ValidatorCatalog
Re-exported types from pkg/validator/v1 so callers that work with the catalog do not have to import the wire-format package directly.
func LoadWithDataProvider ¶ added in v0.14.0
func LoadWithDataProvider(ctx context.Context, dp recipe.DataProvider, version, commit string) (*ValidatorCatalog, error)
LoadWithDataProvider reads and parses the validator catalog from dp using the supplied context for cancellation/timeout. A nil dp defaults to the embedded recipe data; callers that want a layered `--data` overlay must pass their own layered provider. When the catalog file is present, the external catalog is merged with the embedded one 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 looks like a release tag published by on-tag.yaml (vX.Y.Z or vX.Y.Z-<prerelease>, but not the goreleaser snapshot suffix -next), 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.
type ValidatorEntry ¶
type ValidatorEntry = v1.ValidatorEntry
Re-exported types from pkg/validator/v1 so callers that work with the catalog do not have to import the wire-format package directly.
Source Files