Skip to content

LiteLLMVirtualKey ​

Generates a scoped API key and stores it in a Kubernetes Secret.

API Version: litellm.palena.ai/v1alpha1Kind: LiteLLMVirtualKeyShort Name: lk

Example ​

yaml
apiVersion: litellm.palena.ai/v1alpha1
kind: LiteLLMVirtualKey
metadata:
  name: eng-ci-key
spec:
  instanceRef:
    name: my-gateway
  keyAlias: eng-ci-key
  teamRef:
    name: engineering
  models:
    - gpt-4o
  maxBudget: "100"
  budgetDuration: "30d"
  rpmLimit: 60
  keySecretName: engineering-ci-api-key

Spec Fields ​

FieldTypeRequiredDefaultDescription
instanceRefInstanceRefYes—Reference to the LiteLLMInstance; set namespace to use an instance in another namespace that allows it. A key's teamRef and userRef stay in its own namespace, so using them across namespaces also needs those kinds listed in allowedNamespaces.kinds
keyAliasstringYes—Human-readable key alias
teamRef*TeamRefNo—Reference to a LiteLLMTeam CR in the same namespace
userRef*UserRefNo—Reference to a LiteLLMUser CR in the same namespace
models[]stringNo—Models this key can access
maxBudget*stringNo—Maximum budget in USD
budgetDurationstringNo—Budget reset period (e.g., 30d)
expiresAt*TimeNo—Key expiration time
tpmLimit*intNo—Tokens per minute limit
rpmLimit*intNo—Requests per minute limit
metadatamap[string]stringNo—Custom metadata
blocked*boolNo—Disable this key without deleting it (rejects all requests using it)
softBudget*float64No—Alert threshold in USD below maxBudget (does not block)
modelRpmLimitmap[string]intNo—Per-model requests-per-minute caps (model name → RPM)
modelTpmLimitmap[string]intNo—Per-model tokens-per-minute caps (model name → TPM)
objectPermission*ObjectPermissionNo—Grant access to MCP servers, vector stores, agents, access groups
modelMaxBudgetmap[string]stringNo—Per-model spending limits in USD (enterprise)
maxParallelRequests*intNo—Maximum concurrent requests for this key
guardrails[]stringNo—Names of LiteLLMGuardrail CRs this key opts into. Each entry must match spec.guardrailName on a guardrail bound to the same instance (enterprise)
keySecretNamestringNo{name}-keyName for the generated Secret. Only honoured before the key is minted — once status.keySecretRef is set the name is pinned, so editing it cannot orphan the only copy of the key material
keySecretTemplate*KeySecretTemplateSpecNo—Annotations and labels to apply to the generated Secret, so third-party controllers can act on it

KeySecretTemplateSpec ​

FieldTypeRequiredDefaultDescription
annotationsmap[string]stringNo—Annotations to apply to the key Secret
labelsmap[string]stringNo—Labels to apply to the key Secret. The operator’s own labels win on conflict

Status Fields ​

FieldTypeDescription
syncedboolWhether the key is synced to LiteLLM
keySecretRef*SecretKeyRefReference to the Secret containing the API key
litellmKeyTokenstringHashed token for reference
isActiveboolWhether the key is active
currentSpend*stringCurrent spend in USD
expiresAt*TimeKey expiration time
lastSyncTime*TimeLast successful sync time
conditions[]ConditionStandard conditions
bash
kubectl get lk
NAME          ALIAS         ACTIVE   SYNCED   AGE
eng-ci-key    eng-ci-key    true     true     1d

Retrieving the Generated Key ​

bash
kubectl get secret eng-ci-key-key -o jsonpath='{.data.api-key}' | base64 -d

Secret Format ​

The generated Secret contains:

yaml
apiVersion: v1
kind: Secret
metadata:
  name: eng-ci-key-key
  ownerReferences:
    - apiVersion: litellm.palena.ai/v1alpha1
      kind: LiteLLMVirtualKey
      name: eng-ci-key
type: Opaque
data:
  api-key: <base64-encoded-api-key>

See Virtual Key Secrets for more details on lifecycle and garbage collection.

Annotating the Generated Secret ​

spec.keySecretTemplate puts annotations and labels on the generated Secret, so that other controllers can act on it without an external mutating admission policy. A common use is kubernetes-reflector, which mirrors the Secret into the namespace where the consuming application runs:

yaml
apiVersion: litellm.palena.ai/v1alpha1
kind: LiteLLMVirtualKey
metadata:
  name: eng-ci-key
spec:
  instanceRef:
    name: my-gateway
  keyAlias: eng-ci-key
  keySecretTemplate:
    annotations:
      reflector.v1.k8s.emberstack.com/reflection-allowed: "true"
      reflector.v1.k8s.emberstack.com/reflection-allowed-namespaces: "apps"
      reflector.v1.k8s.emberstack.com/reflection-auto-enabled: "true"
      reflector.v1.k8s.emberstack.com/reflection-auto-namespaces: "apps"
    labels:
      app.kubernetes.io/part-of: checkout

Entries are merged, not replaced: annotations and labels added to the Secret by other controllers survive reconciliation. The flip side is that removing an entry from keySecretTemplate does not remove it from the Secret — delete it from the Secret directly.

Mirroring a Secret copies a live credential across a namespace boundary. Scope reflection-allowed-namespaces to the namespaces that genuinely need the key.

If the Generated Secret Is Deleted ​

LiteLLM stores only a hash of the key, so the material in the Secret is the only copy — it cannot be re-read from the API. If the Secret is deleted, the operator deletes the now-unusable key from LiteLLM, mints a replacement, and writes a fresh Secret, emitting a KeySecretMissing warning event. Consumers must re-read the Secret to pick up the new key.

Released under the Apache 2.0 License.