Skip to main content

Kubernetes Naming Conventions

Introduction

The Virtual Human (VH) platform runs multiple independent Virtual Human instances inside a shared Kubernetes cluster. To maintain clarity, consistency, and scalability across all environments (dev, test, prod), a standardized naming convention is required for Kubernetes resources.

This document defines the naming rules for:

  • Namespaces
  • Deployments
  • Services
  • ConfigMaps and Secrets
  • Labels

These conventions ensure predictable structure, avoid naming collisions, and make the VH system easy to operate, monitor, and automate across teams.

Kubernetes Naming Conventions

Namespace Naming Convention​

Each Virtual Human must run in its own Kubernetes namespace to provide isolation and resource separation.

Pattern​

vh-<env>-<vhId>

Definitions​

FieldDescription
<env>Environment: dev, test, prod
<vhId>Unique Virtual Human identifier (e.g., vh01, vh42)

Examples​

vh-dev-vh01
vh-dev-vh42
vh-test-vh05
vh-prod-vh10

Namespaces ensure that all resources belonging to one Virtual Human remain isolated from others.

Deployment Naming Convention​

Deployments represent the containerized components that make up a Virtual Human instance.

Pattern​

<component>-<vhId>

Definitions​

FieldDescription
<component>System component (e.g., LLM, mood processor, embodiment, controller)
<vhId>Virtual Human identifier

Examples​

llm-vh42
moodproc-vh42
controller-vh01
embody-vh05

This pattern makes it immediately clear which Virtual Human instance each component belongs to.

Service Naming Convention​

A Kubernetes Service provides a stable network identity for reaching a deployment, regardless of pod restarts or scaling.

Services must be named consistently so internal communication remains predictable.

Pattern​

<component>-svc

Definitions​

FieldDescription
<component>System component
svcIndicates the resource is a Kubernetes service

Examples​

llm-svc
moodproc-svc
controller-svc
embody-svc

All services are created within the Virtual Human namespace, meaning they resolve to DNS entries like:

llm-svc.<namespace>.svc.cluster.local

ConfigMaps and Secrets​

Configuration and sensitive data must use clear and consistent naming.

ConfigMap Pattern​

<component>-config

Secret Pattern​

<component>-secret

Examples​

llm-config
controller-secret
moodproc-config

If configuration is Virtual Human–specific rather than global, the Virtual Human identifier may be appended:

llm-vh42-config
llm-vh42-secret

Required Labels for All Resources

Labels allow efficient filtering, monitoring (for example using Prometheus or Grafana), debugging, and automation.

Every Kubernetes resource associated with the Virtual Human platform must include the following labels.

Label Structure​

metadata:
  labels:
    project: virtual-human
    env: <env>
    vhId: <vhId>
    component: <component>

Example​

labels:
  project: virtual-human
  env: dev
  vhId: vh42
  component: llm

Example Queries​

These labels enable useful operational queries such as:

kubectl get pods -l vhId=vh42
kubectl get deployments -l component=llm
kubectl logs -l project=virtual-human