Naming and Label Conventions¶

AIM Engine creates derived resources (InferenceServices, HTTPRoutes, PVCs, Jobs, etc.) that do not share their parent's name. This page documents the naming algorithm, all label keys, and how to query AIM-managed resources.

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 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 (template name, service name, GPU model, precision) into a single name. The hash suffix guarantees uniqueness when names are truncated.

Important

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

Derived Resource Names¶

Resource	Created By	Name Parts	Hash Source
InferenceService	AIMService	`[serviceName]`	namespace
HTTPRoute	AIMService	`[serviceName]`	namespace
AIMTemplateCache (shared)	AIMService	`[templateName]`	namespace
AIMTemplateCache (dedicated)	AIMService	`[templateName, serviceName]`	service UID
AIMModel (from image)	AIMService	`[imageName, imageTag]`	image URI
AIMClusterModel	AIMClusterModelSource	`[repository, tag]`	registry + repo + tag
AIMServiceTemplate (discovered)	AIMModel	`[imageName, metric-precision-gpu]`	hash string
AIMArtifact	AIMTemplateCache	`[sourceURI]`	source URI + env + storage
PVC	AIMArtifact	`[artifactName, "cache"]`	artifact UID
Download Job	AIMArtifact	`[artifactName, "download"]`	artifact UID
Check-size Job	AIMArtifact	`[artifactName, "check-size"]`	artifact UID

Labels¶

AIM Domain Labels¶

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

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
`aim.eai.amd.com/template-cache.name`	Cache name	Identifies the owning template cache
`aim.eai.amd.com/origin`	`auto-generated`, `manual`	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`, etc.	GPU model
`aim.eai.amd.com/gpu.count`	`"1"`, `"4"`	GPU count

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

Template Labels¶

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
`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
`aim.eai.amd.com/source-model`	Model identifier	Source model reference

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 resource 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 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 Template Cache¶

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

Find Discovery Jobs for a Template¶

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

Find Download Jobs for an Artifact¶

kubectl get jobs -l aim.eai.amd.com/cache.name=<artifact-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:

Index Field	Resource	Description
`.spec.templateRef`	AIMService	Services by template reference
`.status.resolvedTemplate.name`	AIMService	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
`.spec.image`	AIMModel / AIMClusterModel	Models by image URI
`.spec.runtimeConfigName`	Multiple CRDs	Resources by runtime config
`.spec.sourceUri`	AIMArtifact	Artifacts by source URI

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