Skip to content

LiteLLMUser ​

Creates a user in LiteLLM for non-SSO environments. Useful for service accounts, bot users, and environments without an Identity Provider.

API Version: litellm.palena.ai/v1alpha1Kind: LiteLLMUserShort Name: lu

Example ​

yaml
apiVersion: litellm.palena.ai/v1alpha1
kind: LiteLLMUser
metadata:
  name: service-bot
spec:
  instanceRef:
    name: my-gateway
  userId: service-bot@example.com
  userEmail: service-bot@example.com
  userRole: internal_user
  maxBudget: 500
  budgetDuration: "30d"
  models:
    - gpt-4o
  teams:
    - teamRef:
        name: engineering
      role: user

Spec Fields ​

FieldTypeRequiredDefaultDescription
instanceRefInstanceRefYes—Reference to the LiteLLMInstance
userIdstringYes—Unique user identifier (typically email)
userEmailstringNo—User email address
userRolestringNointernal_userUser role (see below)
maxBudget*float64No—Maximum budget in USD
budgetDurationstringNo—Budget reset period (e.g., 30d)
models[]stringNo—Models this user can access
teams[]UserTeamMembershipNo—Team memberships
tpmLimit*intNo—Tokens per minute limit
rpmLimit*intNo—Requests per minute limit
metadatamap[string]stringNo—Custom metadata
blocked*boolNo—Disable all requests from this user without deleting 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
initialPasswordSecretRef*SecretKeyRefNo—Secret key holding an initial Admin UI login password (see Initial Password)
autoCreateKey*boolNofalseAlso mint a personal virtual key when the user is created (see Personal Keys)

User Roles ​

RoleDescription
proxy_adminFull admin access to all LiteLLM features
proxy_admin_viewerRead-only admin access
internal_userStandard user with scoped access
internal_user_viewerRead-only standard user

teams[] ​

FieldTypeDescription
teamRef*TeamRefReference to a LiteLLMTeam CR in the same namespace
teamIdstringDirect team ID (for teams not managed by a CRD)
rolestringRole within the team (default: user)
maxBudgetInTeam*float64Max budget within this team

You can use either teamRef (references a LiteLLMTeam CR by name) or teamId (direct LiteLLM team ID). The operator resolves teamRef to the team's status.litellmTeamId.

Status Fields ​

FieldTypeDescription
syncedboolWhether the user is synced to LiteLLM
litellmUserIdstringLiteLLM-assigned user ID
currentSpend*float64Current spend in USD
resolvedTeams[]ResolvedTeamMembershipResolved team memberships
lastSyncTime*TimeLast successful sync time
initialPasswordDigeststringArgon2id digest of the last password applied from initialPasswordSecretRef (never the plaintext)
conditions[]ConditionStandard conditions
bash
kubectl get lu
NAME          USERID                     ROLE            SYNCED   AGE
service-bot   service-bot@example.com    internal_user   true     1d

When to Use LiteLLMUser ​

  • Service accounts for CI/CD pipelines
  • Bot users that need API access
  • Non-SSO environments where you manage users declaratively
  • GitOps user management alongside SSO for specific accounts

When SSO/SCIM handles user provisioning, LiteLLMUser CRDs are typically not needed for human users.

Initial Password ​

initialPasswordSecretRef gives a user a password for logging in to the Admin UI, for environments without SSO. The value is read from a Secret in the CR's namespace:

yaml
apiVersion: v1
kind: Secret
metadata:
  name: alice-initial-password
stringData:
  password: "Change-Me-On-First-Login!"
---
apiVersion: litellm.palena.ai/v1alpha1
kind: LiteLLMUser
metadata:
  name: alice
spec:
  instanceRef:
    name: my-gateway
  userId: alice@example.com
  userEmail: alice@example.com
  initialPasswordSecretRef:
    name: alice-initial-password
    key: password

It is an initial password: the user is expected to change it after logging in, and the operator does not undo that.

  • The password is applied once, right after the user is created (or adopted), via POST /user/update. LiteLLM rejects a password on /user/new.
  • After that it is applied only when the Secret's value changes. Resyncs, spec edits and operator restarts never re-send it. To reset a user's password, put a new value in the Secret.
  • The operator records an Argon2id digest of the applied value in status.initialPasswordDigest to detect changes. The plaintext is never stored on the CR, logged or put in events.
  • Removing the field leaves the user's current password in LiteLLM untouched. Adding it back applies the Secret's value again.
  • Recent LiteLLM versions mark an admin-set password as requiring a reset at first login, and validate it against the proxy's password policy and breached-password check.

Progress is reported on the InitialPasswordApplied condition, separate from Synced, so a password problem never stops the rest of the user from syncing:

ReasonMeaning
AppliedThe Secret's current value is the applied password
SecretNotFound / SecretKeyMissingThe Secret or key does not exist or is empty; applied as soon as it appears
PasswordRejectedLiteLLM rejected the value (e.g. password policy); not retried until the Secret changes
ApplyFailed / SecretFetchFailedTransient failure; retried after 30s

Personal Keys ​

Left to itself, LiteLLM's /user/new also mints a personal virtual key for each new user. That key has no alias and no team, has no budget or model restriction unless the user sets them, and is not managed by any LiteLLMVirtualKey CR. The operator therefore asks LiteLLM not to create one, and users get keys only through LiteLLMVirtualKey CRs.

Set autoCreateKey: true to get LiteLLM's behaviour back. The operator does not store the key in a Secret or manage it afterwards.

The field applies only when the user is created. Changing it later neither creates nor removes a key, and users created by earlier operator versions keep any personal key they already have; remove those through the Admin UI or POST /key/delete if you don't want them.

Referencing an Instance in Another Namespace ​

A LiteLLMUser can reference an instance in another namespace only if the instance lists LiteLLMUser in spec.allowedNamespaces.kinds. That amounts to admin-level access to the proxy: such a user can be a proxy_admin with a password, and userId can name an existing user, which is then adopted and has its password reset.

Adopting Existing Users ​

If userId already exists in LiteLLM (created by SSO, the Admin UI, or before the operator was installed), /user/new returns 409. The operator then confirms through /user/info that the user exists under userId and adopts it: the id is recorded, the CR is annotated litellm.palena.ai/adopted: "true", and the user is updated to match the spec.

LiteLLM also returns 409 when userEmail belongs to a different user. In that case /user/info finds no user under userId, so nothing is adopted and the CR reports the conflict.

An adopted user is never deleted from LiteLLM when its CR is deleted, because the operator did not create it. Users the operator created are deleted on CR deletion as before.

Released under the Apache 2.0 License.