Naming and Label Conventions

Naming and Label Conventions#

AIM Engine creates derived resources (AIMProfile, InferenceService, HTTPRoute, PVCs, Jobs, etc.) that do not share their parent’s name. This page documents the naming algorithm, the canonical labels you’ll see on AIM-managed resources, and how to query them.

Derived naming#

Algorithm#

Derived names are generated by GenerateDerivedName, which produces deterministic, RFC 1123-compliant names:

Sanitize each name part — lowercase, replace non-alphanumeric characters with -, trim leading/trailing dashes.
Hash — compute SHA-256 of the inputs (sorted deterministically), truncate to a configured hex length.
Assemble — join sanitized parts with -, append -<hash>.
Fit — if the result exceeds 63 characters, iteratively shorten the longest part until it fits.

Why derived names?#

Kubernetes names have a 63-character limit. AIM Engine often needs to encode multiple dimensions (model name, accelerator, precision, service name) into one name. The hash suffix guarantees uniqueness when parts are truncated.

Important

Derived resource names are not predictable from the parent name alone. Always use labels (not name matching) to find child resources.

v1alpha2 derived resource names#

Resource	Created by	Name parts	Hash source
`AIMProfileSet` (child of model)	`AIMModel.spec.profiles`	`[modelName, "profiles"]`	model UID + derivation spec
`AIMClusterProfileSet` (child of cluster model)	`AIMClusterModel.spec.profiles`	`[modelName, "profiles"]`	cluster model UID + derivation spec
Derived `AIMProfile`	`AIMProfileSet`	`[profileSetName, accelOrAlias]`	source profile + overrides
Overlay `AIMProfile`	`AIMService.spec.profileOverrides`	`[seedName, serviceName, "overlay"]`	service UID + overrides
`AIMProfileCache`	`AIMService` (when caching enabled)	`[profileName]`	namespace
`AIMArtifact`	`AIMProfileCache`	`[sourceURI]`	source URI + env + storage
Discovery `ConfigMap`	`AIMModel`	`[modelName, "discovery"]`	model + spec hash
Discovery `Job`	`AIMModel`	`[modelName, "discovery", "job"]`	spec hash
`InferenceService`	`AIMService`	`[serviceName]`	namespace
`HTTPRoute`	`AIMService`	`[serviceName]`	namespace
PVC	`AIMArtifact`	`[artifactName, "cache"]`	artifact UID
Download `Job`	`AIMArtifact`	`[artifactName, "download"]`	artifact UID

v1alpha1 derived resource names#

These are still produced for v1alpha1 resources during the deprecation window.

Resource	Created by	Name parts	Hash source
`AIMServiceTemplate` (discovered)	`AIMModel`	`[imageName, "metric-precision-gpu"]`	hash string
`AIMTemplateCache` (shared)	`AIMService` (v1alpha1)	`[templateName]`	namespace
`AIMTemplateCache` (dedicated)	`AIMService` (v1alpha1)	`[templateName, serviceName]`	service UID
`AIMModel` (from image)	`AIMService.spec.model.image`	`[imageName, imageTag]`	image URI
`AIMClusterModel`	`AIMClusterModelSource`	`[repository, tag]`	registry + repo + tag

Labels#

All AIM labels use the aim.eai.amd.com/ prefix.

v1alpha2 profile provenance labels#

The canonical label set stamped on every operator-produced AIMProfile / AIMClusterProfile. These are the labels selectors (both AIMProfileSet and AIMService) key off.

Label	Values	Set by	Used by
`aim.eai.amd.com/profile-role`	`base`, `deployable`	Model controller, AIMProfileSet controller	AIMProfileSet `selector.role`, AIMService `selector.role` (reserved)
`aim.eai.amd.com/profile-origin`	`discovered`, `derived`, `generated`, `user-authored`	Model / AIMProfileSet controllers; backfilled by AIMProfile controller for user-authored	AIMProfileSet `selector.origin`
`aim.eai.amd.com/source-model`	Name of producing AIM(Cluster)Model	Model / AIMProfileSet controllers (with controller ownerRef)	AIMProfileSet `selector.modelRef.name`, AIMService `spec.model.name` shortcut
`aim.eai.amd.com/source-model-scope`	`namespace`, `cluster`	Model / AIMProfileSet controllers	AIMProfileSet `selector.modelRef.scope`

v1alpha2 profile annotations#

These carry provenance or controller compatibility state that nothing selects on, so they are annotations, not labels — a label selector will never match them.

Annotation	Values	Set by	Used by
`aim.eai.amd.com/profile-source`	`image`, `copy`, `generated`	AIMModel discovery/generation or AIMProfileSet derivation	Origin classification (`status.origin`)
`aim.eai.amd.com/profile-copyable`	`"true"`	Image discovery (default); manual opt-in for hand-authored profiles	AIMProfileSet candidate eligibility
`aim.eai.amd.com/profile-generation-fallback`	RuntimeConfig fallback name	AIMModel generation	Retaining a generated profile when its hardware disappears
`aim.eai.amd.com/profile-yaml-contract`	JSON object with `codec`, `metadataFields`, and optional `extensions`	Image discovery; inherited by AIMProfileSet derivation and AIMService overlays	Rendering the source-compatible profile YAML mounted into the runtime

profile-yaml-contract is controller-owned diagnostic state. Typical values identify the aim-profile/v1 codec and list the metadata fields present in the source. The optional extensions object retains source-owned fields that AIM Engine does not model, for example metadata.capabilities. Profiles without source YAML provenance use the strict canonical accelerator v1 format. Discovered and derived profiles require the annotation; projection waits for their producer to backfill it instead of guessing. Unknown fields in the contract envelope, unknown codec identifiers, malformed contracts, and contracts larger than 64 KiB are rejected explicitly during derivation or runtime projection.

Hand-authored profiles

The source-model and source-model-scope labels are derived from controller ownerReferences (or propagated labels for AIMProfileSet-owned profiles). The operator strips them every reconcile from any profile without an AIM controller owner. Hand-authored profiles that need to be reachable by modelRef.name must be onboarded through an AIMModel/AIMProfileSet — they cannot fake provenance with manually-applied labels. See Profiles.

Ownership and identity#

Label	Value	Purpose
`aim.eai.amd.com/service.name`	Service name	Framework-applied owner label (`{controller}.name`) for AIMService-managed resources
`aim.eai.amd.com/model`	Model name	Identifies the owning model
`aim.eai.amd.com/template`	Template name	Identifies the owning template (v1alpha1)
`aim.eai.amd.com/template-cache.name`	Cache name	Identifies the owning template cache (v1alpha1)
`aim.eai.amd.com/origin`	`auto-generated`, `manual`, `derived`	How the resource was created
`aim.eai.amd.com/managed-by`	`aim-controller`	Marks operator-managed resources
`aim.eai.amd.com/component`	`inference`, `discovery`, `cache`, `check-size`	Functional role of the resource

Runtime attributes#

Label	Value	Purpose
`aim.eai.amd.com/metric`	`latency`, `throughput`	Optimization metric
`aim.eai.amd.com/precision`	`fp8`, `fp16`, `bf16`, …	Numeric precision
`aim.eai.amd.com/gpu.model`	`MI300X`, `MI325X`, …	GPU model
`aim.eai.amd.com/gpu.count`	`"1"`, `"4"`	GPU count

Projected KServe `ServingRuntime` / `ClusterServingRuntime` metadata#

Stamped on every projected KServe ServingRuntime / ClusterServingRuntime (and its colocated profile ConfigMap) so a native / bring-your-own-KServe consumer can trace and inspect the runtime without reversing its hashed object name. See Bring Your Own KServe.

Per-profile KServe ServingRuntime / ClusterServingRuntime objects are named aim-<truncated-profile>-<hash> (hashed, not reversible); the Reduced/Both model-slug primary is named aim-<model-slug> (readable, autoSelect off). The aim- prefix is reserved for AIM Engine — do not hand-author objects under it.

Label	Value	Purpose
`aim.eai.amd.com/profile`	Sanitized backing profile name	Correlator back to the profile (selectable)
`aim.eai.amd.com/model`	Sanitized model slug	Filter `ServingRuntime` / `ClusterServingRuntime` objects by the model they serve
`aim.eai.amd.com/precision`	`fp8`, `fp16`, …	Filter by numeric precision
`aim.eai.amd.com/accelerator-class`	`MI300X`, …	Filter by accelerator class
`aim.eai.amd.com/runtime-projection`	`eager`, `lazy`	How it was materialized — `eager` (by the profile) or `lazy` (namespaced `ServingRuntime` shadow via the `ServingRuntime`-keyed controller). Provenance, not health
`aim.eai.amd.com/runtime-projection-state`	`projected`	Projection provenance surfaced on the `ServingRuntime` / `ClusterServingRuntime` object. `projected` is the only value stamped; the degraded transition is reported on the profile’s `RuntimeProjected` condition, not this label

Annotation	Value	Purpose
`aim.eai.amd.com/projected.profile`	Untruncated backing profile name	Recover the identity the hashed object name hides
`aim.eai.amd.com/projected.aim-id`	Backing profile `aimId`	Model architecture identifier
`aim.eai.amd.com/projected.model-id`	Backing profile `modelId`	Served model id
`aim.eai.amd.com/projected.precision`	Backing profile precision	—
`aim.eai.amd.com/projected.metric`	Backing profile metric	—
`aim.eai.amd.com/runtime-projection-message`	Human-readable note	Companion to `runtime-projection-state`; points to the profile’s `RuntimeProjected` condition
`aim.eai.amd.com/runtime-projection-content-hash`	SHA-256 digest	Stamped identically on a complete namespaced `ServingRuntime` / `ConfigMap` pair from workload-affecting content; AIMService waits for both hashes to match the current profile/cache projection before reconciling its `InferenceService`

A projected ServingRuntime / ClusterServingRuntime also carries an owner reference to its backing AIMProfile / AIMClusterProfile, which is what garbage-collects it when the profile is deleted.

Cache labels#

Label	Value	Purpose
`aim.eai.amd.com/cache-type`	`temp`, `persistent`, `dedicated`	PVC cache type
`aim.eai.amd.com/cache.type`	`artifact`, `template-cache`	Cache resource type
`aim.eai.amd.com/cache.name`	Artifact name	Identifies the cache resource
`aim.eai.amd.com/model.source`	`huggingface`, `s3`	Model download source

v1alpha1 template labels#

These remain in use on v1alpha1 templates and v1alpha1-managed downstream resources during the deprecation window.

Label	Value	Purpose
`aim.eai.amd.com/template.name`	Template name	On artifacts — parent template
`aim.eai.amd.com/template.scope`	`Namespace`, `Cluster`	Template scope (note capitalisation differs from the v1alpha2 `source-model-scope` label, which uses lowercase)
`aim.eai.amd.com/template.index`	`"0"`, `"1"`	Profile index in template
`aim.eai.amd.com/template.metric`	`latency`, `throughput`	Template metric
`aim.eai.amd.com/template.precision`	`fp8`, `fp16`	Template precision
`aim.eai.amd.com/template.alias`	User alias	Custom template alias
`aim.eai.amd.com/custom-model`	`"true"`	Marks custom model templates

Accelerator detection labels#

Labels written by the AcceleratorDetector DaemonSet via NFD. These use the value-in-key pattern — each hardware identifier is a separate label key, matched with the Exists operator. The label value carries the accelerator count.

Label pattern	Example key	Example value	Purpose
`feature.node.kubernetes.io/aim-accelerator.{model}`	`aim-accelerator.MI300X`	`"8"`	Specific GPU or CPU model
`feature.node.kubernetes.io/aim-accelerator.{family}`	`aim-accelerator.GPU`	`"8"`	Accelerator family (`GPU`/`CPU`) for generic profiles
`feature.node.kubernetes.io/aim-accelerator.vendor.{family}.{vendor}`	`aim-accelerator.vendor.GPU.NVIDIA`	`"8"`	Accelerator vendor, keyed per family so cross-vendor nodes don’t conflict
`feature.node.kubernetes.io/aim-accelerator.partitioning-scheme.{scheme}`	`aim-accelerator.partitioning-scheme.CPX-NPS4`	`"64"`	GPU partition state — the `default` sentinel (canonical-unpartitioned or non-partitionable hardware) or an explicit `<Compute>-<Memory>` scheme. Matched by `AIMProfile.spec.acceleratorPartitioningMode` via `Exists`/`DoesNotExist`

Both axes use the value-in-key pattern; the value (accelerator/partition count) is informational only and the matcher keys off the label key. See Accelerator Detection for details on label production.

Standard Kubernetes labels#

Label	Value	Purpose
`app.kubernetes.io/managed-by`	`aim-{controller}-controller`	Controller that owns the child resource
`app.kubernetes.io/component`	`inference`, `routing`, `model-storage`, `discovery`	Functional component
`app.kubernetes.io/name`	`aim-discovery`, `aim-engine`	Application name

Controller labels#

The reconciler adds aim.eai.amd.com/{controller}.name = <parent-name> to all managed children. For example, a resource managed by the AIMService controller gets:

aim.eai.amd.com/service.name: qwen-chat

Querying AIM resources#

Find profiles owned by a specific model#

# Namespace-scoped
kubectl get aimprofile -l aim.eai.amd.com/source-model=qwen-qwen3-32b -n ml-team

# Cluster-scoped
kubectl get aimclusterprofile -l aim.eai.amd.com/source-model=qwen-qwen3-32b

Find all base profiles#

kubectl get aimprofile -A -l aim.eai.amd.com/profile-role=base

Find user-authored profiles#

kubectl get aimprofile -A -l aim.eai.amd.com/profile-origin=user-authored

Find all resources for a service#

kubectl get all -l aim.eai.amd.com/service.name=qwen-chat -n <namespace>

Find the InferenceService for a service#

kubectl get inferenceservice -l aim.eai.amd.com/service.name=qwen-chat -n <namespace>

Find artifacts for a profile cache#

kubectl get aimartifact -l aim.eai.amd.com/profile-cache.name=<cache-name> -n <namespace>

Find projected KServe `ClusterServingRuntime` objects for a model#

kubectl get clusterservingruntime \
  -l aim.eai.amd.com/model=qwen-qwen3-32b \
  -L aim.eai.amd.com/runtime-projection-state,aim.eai.amd.com/runtime-projection

Find discovery jobs for a model#

kubectl get jobs -l aim.eai.amd.com/model=<model-name> -n <namespace>

Find all auto-generated resources#

kubectl get aimmodel -l aim.eai.amd.com/origin=auto-generated --all-namespaces

Field indexers#

The operator maintains field indexes for efficient lookups. The full set used by v1alpha2 controllers:

Index key	Resource	Description
`.spec.image`	`AIMModel`, `AIMClusterModel`	Models by image URI
`.spec.selector.aimId`	`AIMProfileSet`, `AIMClusterProfileSet`, `AIMService`	Resources by selector aimId
`.spec.selector.modelRef.name`	`AIMProfileSet`, `AIMClusterProfileSet`, `AIMService`	Resources by selected source model
`.spec.sourceRef`	`AIMProfileSet`, `AIMClusterProfileSet`	Profile sets by source discovery cache
`.spec.aimId`	`AIMProfile`, `AIMClusterProfile`	Profiles by aimId
`.spec.profileName`	`AIMProfileCache`	Caches by target profile name
`.spec.sourceUri`	`AIMArtifact`	Artifacts by source URI
`.spec.runtimeConfigName`	Multiple CRDs	Resources by runtime config

v1alpha1-only indexers (still active during deprecation):

Index key	Resource	Description
`.spec.templateRef`	`AIMService` (v1alpha1)	Services by template reference
`.status.resolvedTemplate.name`	`AIMService` (v1alpha1)	Services by resolved template
`.spec.templateName`	`AIMTemplateCache`	Caches by template name
`.spec.templateScope`	`AIMTemplateCache`	Caches by template scope
`.spec.modelName`	`AIMServiceTemplate`	Templates by model name

Some index key names are legacy internal identifiers (for example, .spec.templateRef) and may not exactly match the current CRD JSON field path.