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:

  1. Sanitize each name part — lowercase, replace non-alphanumeric characters with -, trim leading/trailing dashes.

  2. Hash — compute SHA-256 of the inputs (sorted deterministically), truncate to a configured hex length.

  3. Assemble — join sanitized parts with -, append -<hash>.

  4. 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, 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

aim.eai.amd.com/profile-source

copy

AIMProfileSet derivation

Provenance only

aim.eai.amd.com/profile-copyable

"true"

Image discovery (default); manual opt-in for hand-authored profiles

AIMProfileSet candidate eligibility

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

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.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 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.

Contents