Enterprise License
The operator supports convention-based activation of LiteLLM Enterprise features. When a license Secret is detected, the operator injects the LITELLM_LICENSE environment variable into the proxy Deployment. No CRD fields are required — the operator discovers the Secret automatically.
How It Works
- You create a Kubernetes Secret containing your LiteLLM Enterprise license key
- The operator detects the Secret during reconciliation
- The
LITELLM_LICENSEenv var is injected into the Deployment viasecretKeyRef(the license value is never read into operator memory) - LiteLLM validates the license at startup and enables enterprise features
- License status is reported in
.status.license
The operator watches license Secrets and triggers a rolling restart of the Deployment when a license is added, updated, or removed.
Secret Convention
Naming
The operator checks for Secrets in this order (first match wins):
{instance-name}-license— per-instance overridelitellm-license— namespace-wide fallback (covers all instances in the namespace)
Structure
The Secret must be Opaque with a license-key key:
apiVersion: v1
kind: Secret
metadata:
name: my-gateway-license # or litellm-license for shared
namespace: litellm
type: Opaque
stringData:
license-key: "your-litellm-enterprise-license-key"Per-Instance License
Create a Secret named {instance-name}-license:
kubectl create secret generic my-gateway-license \
--from-literal=license-key='your-litellm-enterprise-license-key'This activates the license only for the my-gateway instance.
Namespace-Wide License
Create a Secret named litellm-license:
kubectl create secret generic litellm-license \
--from-literal=license-key='your-litellm-enterprise-license-key'This activates the license for all LiteLLMInstance resources in the namespace. A per-instance Secret always takes precedence over the namespace-wide fallback.
Checking License Status
kubectl get litellminstance my-gateway -o jsonpath='{.status.license}'{"active": true, "secretName": "my-gateway-license"}When no license Secret is found:
{"active": false}Enterprise Feature Errors
If a downstream resource (Model, Team, User, VirtualKey) attempts an operation that requires an enterprise license and LiteLLM returns a 403 error, the operator sets a clear status condition:
status:
conditions:
- type: Synced
status: "False"
reason: EnterpriseLicenseRequired
message: "This feature requires a LiteLLM Enterprise license. Create a license Secret to activate."The operator does not requeue the resource in this case — the condition persists until the user creates a license Secret, which triggers reconciliation of the LiteLLMInstance and eventually the downstream resources.
Enterprise Features Supported by the Operator
The following CRD fields configure LiteLLM Enterprise features and require an active license:
- JWT authentication —
spec.jwtAuthenables API-level authentication via JWT tokens from identity providers. See JWT/OAuth2 Auth - OAuth2 authentication —
spec.oauth2Authenables machine-to-machine authentication by mapping JWT fields to LiteLLM attributes. See JWT/OAuth2 Auth - IP allowlisting —
spec.security.ipAllowlistrestricts API access to specific IPs/CIDRs - Max request/response size —
spec.security.ipAllowlist.maxRequestSizeMB/maxResponseSizeMB - Per-model spending limits on virtual keys —
spec.modelMaxBudgetonLiteLLMVirtualKey - Per-key / per-team guardrail assignment —
spec.guardrails []stringonLiteLLMVirtualKeyandLiteLLMTeam. DeclaringLiteLLMGuardrailCRs and rendering them into the proxy config works on open-source LiteLLM; opting a specific key or team into a guardrail is enterprise-only and will surface asEnterpriseLicenseRequiredif no license is active. See LiteLLMGuardrail for details.
When JWT or OAuth2 auth is configured without a license Secret, the operator sets an EnterpriseFeaturesConfigured warning condition on the LiteLLMInstance status and emits a warning event. The proxy config is still generated — LiteLLM will enforce the license requirement at runtime.
Removing a License
Delete the license Secret:
kubectl delete secret my-gateway-licenseThe operator detects the deletion, removes the LITELLM_LICENSE env var from the Deployment, and triggers a rolling restart. The status updates to license.active: false.
Design Decisions
- No separate CRD — a Secret naming convention keeps things simple and avoids CRD proliferation
- No operator-side validation — the operator passes the license key through to LiteLLM, which owns the license format and validation
- No owner reference — the license Secret is user-managed and must survive
LiteLLMInstancedeletion - Secret-only storage — the license key is referenced via
secretKeyRefand never stored in the operator's memory or logs
