Naming and Label Conventions

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:

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

  2. Hash — compute SHA-256 of 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 (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