API Reference¶
Packages¶
langop.io/v1alpha1¶
Package v1alpha1 contains API Schema definitions for the language v1alpha1 API group
Resource Types¶
- LanguageAgent
- LanguageAgentRuntime
- LanguageAgentSelfConfig
- LanguageCluster
- LanguageModel
- LanguagePersona
- LanguageTool
AgentMonitoringSpec¶
AgentMonitoringSpec defines Prometheus Operator integration for a LanguageAgent.
Appears in: - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
serviceMonitor AgentServiceMonitorSpec |
ServiceMonitor configures a ServiceMonitor resource for this agent. | Optional: {} |
|
rules PrometheusRuleGroup array |
Rules defines PrometheusRule groups for this agent. When non-empty, the operator creates a PrometheusRule resource. |
Optional: {} |
AgentNetworkPolicies¶
AgentNetworkPolicies defines user-supplied ingress and egress rules for an agent workload. The shape mirrors the native Kubernetes NetworkPolicySpec so that rules can be copied verbatim from real NetworkPolicy manifests.
Appears in: - LanguageAgentSpec - LanguageClusterSpec - LanguageToolSpec
| Field | Description | Default | Validation |
|---|---|---|---|
ingress NetworkIngressRule array |
Ingress rules — each entry allows traffic into the workload from the listed sources. | Optional: {} |
|
egress NetworkEgressRule array |
Egress rules — each entry allows traffic from the workload to the listed destinations. | Optional: {} |
AgentPort¶
AgentPort describes a single network port that an agent container exposes.
Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name uniquely identifies this port within the agent (e.g., "web", "ws"). Used as the Service port name; must conform to Kubernetes port-name rules. |
MaxLength: 15 Pattern: ^[a-z][a-z0-9-]*$ Required: {} |
|
port integer |
Port is the port number the container listens on. | Maximum: 65535 Minimum: 1 Required: {} |
|
protocol Protocol |
Protocol is the transport protocol. Defaults to TCP. | TCP | Enum: [TCP UDP SCTP] Optional: {} |
expose boolean |
Expose controls whether ingress/HTTPRoute routes to this port. At most one port should have expose: true; if none, the first port is used. |
false | Optional: {} |
AgentServiceMonitorSpec¶
AgentServiceMonitorSpec configures a Prometheus Operator ServiceMonitor for an agent.
Appears in: - AgentMonitoringSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled controls whether a ServiceMonitor is created for this agent. | ||
port string |
Port is the name of the service port to scrape for metrics. Defaults to the name of the first port in spec.ports, or "http" if no ports are defined. |
Optional: {} |
|
path string |
Path is the HTTP path to scrape for metrics. Defaults to /metrics. | Optional: {} |
|
interval string |
Interval is the scrape interval (e.g. "30s"). Uses the Prometheus default when omitted. | Optional: {} |
|
scrapeTimeout string |
ScrapeTimeout is the per-scrape timeout. Uses the Prometheus default when omitted. | Optional: {} |
|
labels object (keys:string, values:string) |
Labels are additional labels added to the ServiceMonitor metadata. | Optional: {} |
AutoscalingSpec¶
AutoscalingSpec configures a HorizontalPodAutoscaler for the deployment.
Appears in: - DeploymentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
minReplicas integer |
MinReplicas is the lower bound for replicas the HPA can scale down to. Defaults to 1 if not specified. |
Minimum: 1 Optional: {} |
|
maxReplicas integer |
MaxReplicas is the upper bound for replicas the HPA can scale up to. | Minimum: 1 |
|
metrics MetricSpec array |
Metrics specifies which metrics to use for scaling. Defaults to 80% average CPU utilization if not specified. |
Optional: {} |
ClaudeCodeConfig¶
ClaudeCodeConfig holds configuration specific to the claude-code runtime. Effective only when spec.runtime is "claude-code".
Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled activates claude-code credential management for this agent. Set to true in a LanguageAgentRuntime to trigger ANTHROPIC_API_KEY injection without requiring any explicit config on the LanguageAgent. |
false | Optional: {} |
apiKey string |
APIKey is the Anthropic API key (inline). The operator creates a managed Secret and injects it as ANTHROPIC_API_KEY. When omitted, the operator injects a gateway-routed placeholder so all LLM traffic flows through ANTHROPIC_BASE_URL → LiteLLM gateway. Mutually exclusive with APIKeyRef. |
Optional: {} |
|
apiKeyRef SecretReference |
APIKeyRef references a Secret containing the Anthropic API key. The operator reads the key specified by apiKeyRef.key (default "api-key") and injects it as ANTHROPIC_API_KEY into the agent container. Mutually exclusive with APIKey. |
Optional: {} |
|
maxTurns integer |
MaxTurns limits the number of agentic turns per request. Sets CLAUDE_CODE_MAX_TURNS in the agent container. |
Optional: {} |
ClusterCapacitySpec¶
ClusterCapacitySpec declares hard limits enforced via a ResourceQuota in the cluster's namespace.
Appears in: - LanguageClusterSpec
| Field | Description | Default | Validation |
|---|---|---|---|
maxAgents integer |
MaxAgents is the maximum number of LanguageAgent objects allowed. | Optional: {} |
|
maxModels integer |
MaxModels is the maximum number of LanguageModel objects allowed. | Optional: {} |
|
maxTools integer |
MaxTools is the maximum number of LanguageTool objects allowed. | Optional: {} |
|
maxPersonas integer |
MaxPersonas is the maximum number of LanguagePersona objects allowed. | Optional: {} |
|
maxCPU Quantity |
MaxCPU is the aggregate CPU limit for all pods in the cluster namespace. Maps to limits.cpu in the namespace ResourceQuota. Example: "4", "2500m" |
Optional: {} |
|
maxMemory Quantity |
MaxMemory is the aggregate memory limit for all pods in the cluster namespace. Maps to limits.memory in the namespace ResourceQuota. Example: "8Gi", "512Mi" |
Optional: {} |
ClusterCapacityStatus¶
ClusterCapacityStatus reports observed resource usage in the cluster's namespace.
Appears in: - LanguageClusterStatus
| Field | Description | Default | Validation |
|---|---|---|---|
agentCount integer |
AgentCount is the number of LanguageAgent objects in the cluster namespace. | ||
modelCount integer |
ModelCount is the number of LanguageModel objects in the cluster namespace. | ||
toolCount integer |
ToolCount is the number of LanguageTool objects in the cluster namespace. | ||
personaCount integer |
PersonaCount is the number of LanguagePersona objects in the cluster namespace. | ||
totalCPULimits Quantity |
TotalCPULimits is the sum of limits.cpu across all agent pod specs. | Optional: {} |
|
totalMemoryLimits Quantity |
TotalMemoryLimits is the sum of limits.memory across all agent pod specs. | Optional: {} |
DeploymentSpec¶
DeploymentSpec groups Kubernetes deployment configuration that is common across LanguageAgent, LanguageTool, and LanguageCluster gateway deployments. All fields are optional; controllers only read the fields relevant to their resource.
Appears in: - GatewaySpec - LanguageAgentRuntimeSpec - LanguageAgentSpec - LanguageToolSpec
| Field | Description | Default | Validation |
|---|---|---|---|
replicas integer |
Replicas is the number of pod replicas to run. | Minimum: 0 Optional: {} |
|
imagePullPolicy PullPolicy |
ImagePullPolicy defines when to pull the container image. | Enum: [Always Never IfNotPresent] Optional: {} |
|
imagePullSecrets LocalObjectReference array |
ImagePullSecrets is a list of references to secrets for pulling images. | Optional: {} |
|
env EnvVar array |
Env contains environment variables for the container. | Optional: {} |
|
envFrom EnvFromSource array |
EnvFrom sources to populate environment variables. | Optional: {} |
|
resources ResourceRequirements |
Resources defines compute resource requirements. | Optional: {} |
|
nodeSelector object (keys:string, values:string) |
NodeSelector is a selector which must match a node's labels. | Optional: {} |
|
affinity Affinity |
Affinity defines pod affinity and anti-affinity rules. | Optional: {} |
|
tolerations Toleration array |
Tolerations allow pods to schedule onto nodes with matching taints. | Optional: {} |
|
topologySpreadConstraints TopologySpreadConstraint array |
TopologySpreadConstraints describes how pods should spread across topology domains. | Optional: {} |
|
serviceAccountName string |
ServiceAccountName is the name of the ServiceAccount to use. | Optional: {} |
|
serviceAccountAnnotations object (keys:string, values:string) |
ServiceAccountAnnotations are annotations to add to the operator-managed ServiceAccount. Use this to attach cloud workload identity bindings, e.g. AWS IRSA, GCP WI, AKS WI. Ignored when ServiceAccountName is set. |
Optional: {} |
|
roleRules PolicyRule array |
RoleRules are additional RBAC policy rules appended to the operator-managed Role. Use this to grant the agent extra in-cluster permissions beyond the defaults (configmaps get/list, pods get/list/watch). Ignored when ServiceAccountName is set. |
Optional: {} |
|
securityContext PodSecurityContext |
SecurityContext holds pod-level security attributes. | Optional: {} |
|
volumeMounts VolumeMount array |
VolumeMounts to mount into the container. | Optional: {} |
|
volumes Volume array |
Volumes to attach to the pod. | Optional: {} |
|
podAnnotations object (keys:string, values:string) |
PodAnnotations are annotations to add to the Pods. | Optional: {} |
|
podLabels object (keys:string, values:string) |
PodLabels are additional labels to add to the Pods. | Optional: {} |
|
initContainers Container array |
InitContainers are additional init containers injected before the main container starts. | Optional: {} |
|
livenessProbe Probe |
LivenessProbe defines the liveness probe for the container. | Optional: {} |
|
readinessProbe Probe |
ReadinessProbe defines the readiness probe for the container. | Optional: {} |
|
startupProbe Probe |
StartupProbe defines the startup probe for the container. | Optional: {} |
|
command string array |
Command overrides the container entrypoint. | Optional: {} |
|
args string array |
Args overrides the container command arguments. | Optional: {} |
|
serviceType ServiceType |
ServiceType specifies the type of Service to create (ClusterIP, NodePort, LoadBalancer). | Enum: [ClusterIP NodePort LoadBalancer] Optional: {} |
|
serviceAnnotations object (keys:string, values:string) |
ServiceAnnotations are annotations to add to the Service. | Optional: {} |
|
autoscaling AutoscalingSpec |
Autoscaling enables and configures a HorizontalPodAutoscaler for this deployment. When set, the HPA manages the replica count; spec.deployment.replicas is used as the initial desired count only and is no longer written on each reconcile. |
Optional: {} |
GatewaySpec¶
GatewaySpec configures the shared LiteLLM gateway deployed per LanguageCluster.
Appears in: - LanguageClusterSpec
| Field | Description | Default | Validation |
|---|---|---|---|
deployment DeploymentSpec |
Deployment configures the Kubernetes deployment for the gateway pod. | Optional: {} |
IngressConfig¶
IngressConfig defines ingress configuration
Appears in: - LanguageClusterSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled controls whether an Ingress is created for the gateway. Defaults to true when cluster.spec.domain is set. |
Optional: {} |
|
tls IngressTLSConfig |
TLS configuration for agent webhooks | Optional: {} |
|
className string |
ClassName specifies the IngressClass to use (maps to spec.ingressClassName on the Ingress object). | Optional: {} |
IngressTLSConfig¶
IngressTLSConfig defines TLS configuration
Appears in: - IngressConfig
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled controls whether TLS is enabled for webhooks. Defaults to true; set to false to disable TLS. |
true | Optional: {} |
secretName string |
SecretName is the name of an existing TLS secret (bring-your-own certificate). When set, cert-manager integration is skipped and this secret is used directly. |
Optional: {} |
LanguageAgent¶
LanguageAgent is the Schema for the languageagents API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageAgent |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageAgentSpec |
|||
status LanguageAgentStatus |
LanguageAgentRuntime¶
LanguageAgentRuntime is the Schema for the languageagentruntimes API. It defines a reusable preset for LanguageAgent deployments, analogous to an IngressClass. Admins create runtimes; users reference them via spec.runtime on a LanguageAgent.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageAgentRuntime |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageAgentRuntimeSpec |
LanguageAgentRuntimeSpec¶
LanguageAgentRuntimeSpec defines a preset configuration for LanguageAgent deployments. All fields are optional; unset fields leave the agent's own spec in effect. When a LanguageAgent references a runtime, the runtime's fields are merged as defaults: scalars fill in zeros/nils (agent wins if set), lists are runtime-first then agent-appended.
Appears in: - LanguageAgentRuntime
| Field | Description | Default | Validation |
|---|---|---|---|
image string |
Image is the default container image for agents using this runtime. Agents may override this. When a runtime is referenced, spec.image on the agent is optional. |
Optional: {} |
|
ports AgentPort array |
Ports defines default ports for agents using this runtime. Replace semantics: when the agent defines spec.ports, runtime ports are ignored entirely. |
Optional: {} |
|
workspace WorkspaceSpec |
Workspace provides default size, storageClass, and mountPath for the agent's workspace. Workspace storage is always provisioned; this presets its parameters. Agents may override individual workspace fields. |
Optional: {} |
|
deployment DeploymentSpec |
Deployment provides default Kubernetes pod and container configuration. Scalars (args, command, resources, probes, etc.) are used when the agent has none set. Lists (initContainers, env, volumes, volumeMounts, envFrom) are runtime-first, agent-appended. |
Optional: {} |
|
openclaw OpenclawConfig |
Openclaw provides default openclaw credential configuration for agents using this runtime. When set, the operator auto-generates OPENCLAW_GATEWAY_TOKEN per agent unless overridden. |
Optional: {} |
|
opencode OpencodeConfig |
Opencode provides default opencode credential configuration for agents using this runtime. When set, the operator auto-generates OPENCODE_SERVER_PASSWORD per agent unless overridden. |
Optional: {} |
|
claudeCode ClaudeCodeConfig |
ClaudeCode provides default claude-code credential configuration for agents using this runtime. When set, the operator injects ANTHROPIC_API_KEY per agent unless overridden. |
Optional: {} |
LanguageAgentSelfConfig¶
LanguageAgentSelfConfig is submitted by an agent pod to request runtime modifications to its own LanguageAgent spec. The controller validates the request against the parent's spec.selfConfigure allowlist before patching.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageAgentSelfConfig |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageAgentSelfConfigSpec |
|||
status LanguageAgentSelfConfigStatus |
LanguageAgentSelfConfigSpec¶
LanguageAgentSelfConfigSpec defines the desired self-modification.
Appears in: - LanguageAgentSelfConfig
| Field | Description | Default | Validation |
|---|---|---|---|
instanceRef string |
InstanceRef is the name of the LanguageAgent to modify. Must be in the same namespace. | MinLength: 1 Required: {} |
|
addTools string array |
AddTools lists LanguageTool names to append to spec.tools on the parent agent. | Optional: {} |
|
removeTools string array |
RemoveTools lists LanguageTool names to remove from spec.tools on the parent agent. | Optional: {} |
|
addModels string array |
AddModels lists LanguageModel names to append to spec.models on the parent agent. | Optional: {} |
|
removeModels string array |
RemoveModels lists LanguageModel names to remove from spec.models on the parent agent. | Optional: {} |
|
addEnvVars SelfConfigEnvVar array |
AddEnvVars lists plain-value environment variables to inject into the parent agent's spec.deployment.env. Existing vars with the same name are overwritten. SecretKeyRef and other value sources are not supported. |
Optional: {} |
|
updateInstructions string |
UpdateInstructions, when non-empty, replaces spec.instructions on the parent agent. | Optional: {} |
|
addRoleRules PolicyRule array |
AddRoleRules lists RBAC policy rules to append to spec.deployment.roleRules on the parent agent. Duplicate rules (identical APIGroups+Resources+Verbs) are de-duplicated. |
Optional: {} |
LanguageAgentSelfConfigStatus¶
LanguageAgentSelfConfigStatus reflects the observed state of a self-config request.
Appears in: - LanguageAgentSelfConfig
| Field | Description | Default | Validation |
|---|---|---|---|
phase SelfConfigPhase |
Phase is the current processing state. | Enum: [Pending Applied Failed Denied] Optional: {} |
|
message string |
Message provides a human-readable explanation of the current phase. | Optional: {} |
|
completionTime Time |
CompletionTime is set when the request reaches a terminal phase (Applied, Failed, Denied). The CR is automatically deleted 1 hour after this time. |
Optional: {} |
LanguageAgentSpec¶
LanguageAgentSpec defines the desired state of LanguageAgent
Appears in: - LanguageAgent
| Field | Description | Default | Validation |
|---|---|---|---|
runtime string |
Runtime is the name of a LanguageAgentRuntime that provides preset configuration (image, port, init containers, env vars, probes, etc.). When set, spec.image is optional; the runtime provides a default. |
Optional: {} |
|
image string |
Image is the container image to run for this agent. Required unless spec.runtime is set (the runtime provides a default image). |
Pattern: ^([a-z0-9]+([._-][a-z0-9]+)*\/)*[a-z0-9]+([._-][a-z0-9]+)*(:[a-z0-9]+([._-][a-z0-9]+)*)?$ Optional: {} |
|
models ModelReference array |
Models is a list of LanguageModel references this agent can use | Optional: {} |
|
tools ToolReference array |
Tools is a list of LanguageTool references available to this agent | Optional: {} |
|
persona string |
Persona is the name of a LanguagePersona this agent uses | Optional: {} |
|
instructions string |
Instructions provides system instructions for the agent. Delivered as the top-level "instructions" field in /etc/agent/config.yaml. |
Optional: {} |
|
workspace WorkspaceSpec |
Workspace defines persistent storage for the agent | Optional: {} |
|
networkPolicies AgentNetworkPolicies |
NetworkPolicies defines ingress and egress rules for this agent. Rules mirror the native Kubernetes NetworkPolicy shape. |
Optional: {} |
|
ports AgentPort array |
Ports defines all network ports this agent exposes. At most one entry should have expose: true (the ingress target); if none are marked, the first port is used for ingress routing. Defaults to a single HTTP port on 8080 when not set. |
Optional: {} |
|
deployment DeploymentSpec |
Deployment groups Kubernetes-specific pod and container configuration. | Optional: {} |
|
opencode OpencodeConfig |
Opencode holds configuration specific to the opencode runtime. Only effective when spec.runtime is "opencode". |
Optional: {} |
|
openclaw OpenclawConfig |
Openclaw holds configuration specific to the openclaw runtime. Only effective when spec.runtime is "openclaw". |
Optional: {} |
|
claudeCode ClaudeCodeConfig |
ClaudeCode holds configuration specific to the claude-code runtime. Only effective when spec.runtime is "claude-code". |
Optional: {} |
|
selfConfigure SelfConfigureSpec |
SelfConfigure controls whether this agent may submit LanguageAgentSelfConfig requests to modify its own spec at runtime. When enabled, the operator grants the agent's ServiceAccount permission to create LanguageAgentSelfConfig resources. |
Optional: {} |
|
monitoring AgentMonitoringSpec |
Monitoring configures Prometheus Operator integration for this agent. When set, the operator creates a ServiceMonitor and/or PrometheusRule resource. Requires prometheus-operator to be installed in the cluster; silently skipped otherwise. |
Optional: {} |
LanguageAgentStatus¶
LanguageAgentStatus defines the observed state of LanguageAgent
Appears in: - LanguageAgent
| Field | Description | Default | Validation |
|---|---|---|---|
phase string |
Phase represents the current phase of the agent | Enum: [Pending Running Failed Updating Degraded] Optional: {} |
|
conditions Condition array |
Conditions represent the latest available observations of the agent's state | Optional: {} |
|
activeReplicas integer |
ActiveReplicas is the number of agent pods currently running | Optional: {} |
|
readyReplicas integer |
ReadyReplicas is the number of agent pods ready | Optional: {} |
|
uuid string |
UUID is a unique identifier for this agent instance Not used for webhook routing; webhooks are routed via agent name (e.g., |
Optional: {} |
|
webhookURLs string array |
WebhookURLs contains the URLs where this agent can receive webhooks | Optional: {} |
|
observedGeneration integer |
ObservedGeneration is the most recent generation observed by the controller. It corresponds to the metadata.generation of the LanguageAgent at the time the controller last processed it. Watchers can use this to detect when the status reflects a stale version of the spec. |
Optional: {} |
|
workspacePVCName string |
WorkspacePVCName is the name of the retained workspace PVC after agent deletion. Only set when spec.workspace.retain is true. |
Optional: {} |
|
managedResources ManagedResource array |
ManagedResources is the inventory of Kubernetes resources created and owned by this controller on behalf of this LanguageAgent. The list is replaced atomically on every successful reconcile. |
Optional: {} |
LanguageCluster¶
LanguageCluster is the Schema for the languageclusters API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageCluster |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageClusterSpec |
|||
status LanguageClusterStatus |
LanguageClusterSpec¶
LanguageClusterSpec defines the desired state of LanguageCluster
Appears in: - LanguageCluster
| Field | Description | Default | Validation |
|---|---|---|---|
domain string |
Domain is the base domain for the cluster and agent webhook routing. Agent webhooks will be accessible at Example: "ai.theryans.io" results in webhooks like "my-agent.ai.theryans.io" |
Optional: {} |
|
ingress IngressConfig |
Ingress defines ingress configuration for the cluster | Optional: {} |
|
networkPolicies AgentNetworkPolicies |
NetworkPolicies defines ingress and egress rules for agents in this cluster. Rules mirror the native Kubernetes NetworkPolicy shape. |
Optional: {} |
|
gateway GatewaySpec |
Gateway configures the shared LiteLLM gateway deployed per cluster | Optional: {} |
|
capacity ClusterCapacitySpec |
Capacity declares hard limits enforced via a ResourceQuota in the cluster's namespace. When set, the controller creates a ResourceQuota named "langop-quota". When unset, any existing "langop-quota" is deleted. |
Optional: {} |
LanguageClusterStatus¶
LanguageClusterStatus defines the observed state
Appears in: - LanguageCluster
| Field | Description | Default | Validation |
|---|---|---|---|
phase string |
Phase of the cluster | Enum: [Pending Ready Failed] |
|
conditions Condition array |
Optional: {} |
||
gatewayEndpoint string |
GatewayEndpoint is the in-cluster URL for the shared LiteLLM gateway | Optional: {} |
|
gatewayReady boolean |
GatewayReady indicates whether the shared gateway Deployment is available. Pointer distinguishes "not yet reconciled" (nil) from "known not ready" (false). |
Optional: {} |
|
capacity ClusterCapacityStatus |
Capacity reports observed resource usage in this cluster's namespace. | Optional: {} |
|
observedGeneration integer |
ObservedGeneration is the most recent generation observed by the controller. It corresponds to the metadata.generation of the LanguageCluster at the time the controller last processed it. Watchers can use this to detect when the status reflects a stale version of the spec. |
Optional: {} |
|
managedResources ManagedResource array |
ManagedResources is the inventory of Kubernetes resources created and owned by this controller on behalf of this LanguageCluster. The list is replaced atomically on every successful reconcile. |
Optional: {} |
LanguageModel¶
LanguageModel is the Schema for the languagemodels API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageModel |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageModelSpec |
|||
status LanguageModelStatus |
LanguageModelSpec¶
LanguageModelSpec defines the desired state of LanguageModel
Appears in: - LanguageModel
| Field | Description | Default | Validation |
|---|---|---|---|
provider string |
Provider specifies the LLM provider type | Enum: [openai anthropic openai-compatible azure bedrock vertex custom] Required: {} |
|
modelName string |
ModelName is the specific model identifier (e.g., "gpt-4", "claude-3-opus") | MinLength: 1 Required: {} |
|
endpoint string |
Endpoint is the API endpoint URL (required for openai-compatible, azure, custom) | Optional: {} |
|
apiKeySecretRef SecretReference |
APIKeySecretRef references a secret containing the API key | Optional: {} |
|
rateLimits RateLimitSpec |
RateLimits defines rate limiting configuration | Optional: {} |
|
timeout string |
Timeout specifies request timeout duration (e.g., "5m", "30s") | 5m | Pattern: ^[0-9]+(ns\|us\|µs\|ms\|s\|m\|h)$ Optional: {} |
LanguageModelStatus¶
LanguageModelStatus defines the observed state of LanguageModel
Appears in: - LanguageModel
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer |
ObservedGeneration reflects the generation of the most recently observed LanguageModel | Optional: {} |
|
phase string |
Phase represents the current phase of the model (Pending, Ready, Failed) | Enum: [Pending Ready Failed] Optional: {} |
|
conditions Condition array |
Conditions represent the latest available observations of the model's state | Optional: {} |
|
message string |
Message provides human-readable details about the current state | Optional: {} |
LanguagePersona¶
LanguagePersona is the Schema for the languagepersonas API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguagePersona |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguagePersonaSpec |
|||
status LanguagePersonaStatus |
LanguagePersonaSpec¶
LanguagePersonaSpec defines the desired state of LanguagePersona
Appears in: - LanguagePersona
| Field | Description | Default | Validation |
|---|---|---|---|
tone string |
Tone describes the agent's communication style e.g. "professional", "concise and direct", "warm and encouraging" |
Optional: {} |
|
personality string |
Personality describes the agent's character and behavioural traits e.g. "curious and methodical, always explains reasoning step by step" |
Optional: {} |
|
expertise string |
Expertise describes the agent's domain knowledge and skills e.g. "senior software engineer specialising in distributed systems and Go" |
Optional: {} |
LanguagePersonaStatus¶
LanguagePersonaStatus defines the observed state of LanguagePersona
Appears in: - LanguagePersona
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer |
ObservedGeneration reflects the generation of the most recently observed LanguagePersona | Optional: {} |
|
phase string |
Phase represents the current phase (Pending, Ready, Failed) | Enum: [Pending Ready Failed] Optional: {} |
|
conditions Condition array |
Conditions represent the latest available observations of the persona's state | Optional: {} |
LanguageTool¶
LanguageTool is the Schema for the languagetools API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
langop.io/v1alpha1 |
||
kind string |
LanguageTool |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec LanguageToolSpec |
|||
status LanguageToolStatus |
LanguageToolSpec¶
LanguageToolSpec defines the desired state of LanguageTool
Appears in: - LanguageTool
| Field | Description | Default | Validation |
|---|---|---|---|
image string |
Image is the container image to run for this tool | MinLength: 1 Required: {} |
|
type string |
Type specifies the tool protocol type. Only "mcp" is currently implemented. | mcp | Enum: [mcp] |
deploymentMode string |
DeploymentMode specifies how this tool should be deployed - "service": Deployed as a standalone Deployment+Service (default, shared across agents) - "sidecar": Deployed as a sidecar container in each agent pod (dedicated, with workspace access) |
service | Enum: [service sidecar] Optional: {} |
port integer |
Port is the port the tool listens on | 8080 | Maximum: 65535 Minimum: 1 |
deployment DeploymentSpec |
Deployment groups Kubernetes-specific pod and container configuration. | Optional: {} |
|
networkPolicies AgentNetworkPolicies |
NetworkPolicies defines ingress and egress rules for this tool. Rules mirror the native Kubernetes NetworkPolicy shape. |
Optional: {} |
LanguageToolStatus¶
LanguageToolStatus defines the observed state of LanguageTool
Appears in: - LanguageTool
| Field | Description | Default | Validation |
|---|---|---|---|
observedGeneration integer |
ObservedGeneration reflects the generation of the most recently observed LanguageTool | Optional: {} |
|
phase string |
Phase represents the current phase of the tool (Pending, Running, Failed, Updating, Degraded) | Enum: [Pending Running Failed Updating Degraded] Optional: {} |
|
conditions Condition array |
Conditions represent the latest available observations of the tool's state | Optional: {} |
|
endpoint string |
Endpoint is the service endpoint where the tool is accessible | Optional: {} |
|
toolSchemas ToolSchema array |
ToolSchemas contains the complete MCP tool schemas discovered from this service | Optional: {} |
|
readyReplicas integer |
ReadyReplicas is the number of pods ready and passing health checks | Optional: {} |
|
availableReplicas integer |
AvailableReplicas is the number of pods targeted by this LanguageTool with at least one available condition | Optional: {} |
|
updatedReplicas integer |
UpdatedReplicas is the number of pods targeted by this LanguageTool that have the desired spec | Optional: {} |
|
unavailableReplicas integer |
UnavailableReplicas is the number of pods targeted by this LanguageTool that are unavailable | Optional: {} |
ManagedResource¶
ManagedResource describes a single Kubernetes resource created and owned by this operator on behalf of a LanguageAgent or LanguageCluster. The combination of Group+Kind+Namespace+Name uniquely identifies the resource.
Appears in: - LanguageAgentStatus - LanguageClusterStatus
| Field | Description | Default | Validation |
|---|---|---|---|
group string |
Group is the API group of the resource. Empty string means the core API group (e.g. ConfigMap, Service, PersistentVolumeClaim). |
Optional: {} |
|
kind string |
Kind is the Kubernetes resource kind (e.g. "Deployment", "ConfigMap"). | ||
name string |
Name is the name of the resource. | ||
namespace string |
Namespace is the namespace of the resource. Empty for cluster-scoped resources (e.g. Namespace). |
Optional: {} |
ModelReference¶
ModelReference references a LanguageModel
Appears in: - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the LanguageModel | MaxLength: 63 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ Required: {} |
|
role string |
Role defines the purpose of this model — a hint for the agent runtime for model selection (e.g. prefer role=primary for general calls, role=reasoning for chain-of-thought). The operator does not enforce routing by role; it is surfaced in the agent config (agent.json). |
primary | Enum: [primary fallback reasoning tool-calling summarization] Optional: {} |
priority integer |
Priority for model selection — a hint for the agent runtime (lower value = higher priority). The operator does not enforce priority; it is surfaced in the agent config (agent.json). |
Optional: {} |
NetworkEgressRule¶
NetworkEgressRule is one egress rule: zero or more destination peers, zero or more ports. Mirrors networkingv1.NetworkPolicyEgressRule.
Appears in: - AgentNetworkPolicies
| Field | Description | Default | Validation |
|---|---|---|---|
to NetworkPeer array |
To lists the destinations this workload is allowed to reach. | Optional: {} |
|
ports NetworkPort array |
Ports lists the destination ports to allow. | Optional: {} |
NetworkIngressRule¶
NetworkIngressRule is one ingress rule: zero or more source peers, zero or more ports. Mirrors networkingv1.NetworkPolicyIngressRule.
Appears in: - AgentNetworkPolicies
| Field | Description | Default | Validation |
|---|---|---|---|
from NetworkPeer array |
From lists the sources allowed to send traffic to this workload. | Optional: {} |
|
ports NetworkPort array |
Ports lists the ports on which to allow incoming traffic. | Optional: {} |
NetworkPeer¶
NetworkPeer defines the source/destination of network traffic
Appears in: - NetworkEgressRule - NetworkIngressRule
| Field | Description | Default | Validation |
|---|---|---|---|
group string |
Group selects pods with matching langop.io/group label Used to allow communication with specific labeled resources |
Optional: {} |
|
cidr string |
CIDR block | Optional: {} |
|
dns string array |
DNS names (supports wildcards with ) Examples: "api.openai.com", ".googleapis.com" |
Optional: {} |
|
service ServiceReference |
Kubernetes service reference | Optional: {} |
|
namespaceSelector LabelSelector |
Namespace selector (for cross-namespace rules) | Optional: {} |
|
podSelector LabelSelector |
Pod selector (within namespace) | Optional: {} |
NetworkPort¶
NetworkPort defines a port and protocol
Appears in: - NetworkEgressRule - NetworkIngressRule
| Field | Description | Default | Validation |
|---|---|---|---|
protocol string |
Protocol (TCP, UDP, SCTP) | TCP | Enum: [TCP UDP SCTP] Optional: {} |
port integer |
Port number | Maximum: 65535 Minimum: 1 |
OpenclawConfig¶
OpenclawConfig holds configuration specific to the openclaw runtime. Effective only when spec.runtime is "openclaw".
Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled activates openclaw credential management for this agent. Set to true in a LanguageAgentRuntime to trigger auto-generation of OPENCLAW_GATEWAY_TOKEN without requiring any explicit config on the LanguageAgent. |
false | Optional: {} |
token string |
Token is the gateway authentication token (inline). The operator creates a managed Secret and injects it via envFrom. Mutually exclusive with TokenRef. |
Optional: {} |
|
tokenRef RuntimeSecretRef |
TokenRef references a Secret whose keys are injected via envFrom. The Secret must contain OPENCLAW_GATEWAY_TOKEN. Mutually exclusive with Token. |
Optional: {} |
OpencodeConfig¶
OpencodeConfig holds configuration specific to the opencode runtime. Effective only when spec.runtime is "opencode".
Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled activates opencode credential management for this agent. Set to true in a LanguageAgentRuntime to trigger auto-generation of credentials without requiring any explicit config on the LanguageAgent. |
false | Optional: {} |
username string |
Username for HTTP Basic Auth. Defaults to "opencode" if not set. Sets OPENCODE_SERVER_USERNAME in the agent container. |
Optional: {} |
|
password string |
Password is the HTTP Basic Auth password (inline). The operator creates a managed Secret and injects it via envFrom. Mutually exclusive with PasswordRef. |
Optional: {} |
|
passwordRef RuntimeSecretRef |
PasswordRef references a Secret whose keys are injected via envFrom. The Secret must contain OPENCODE_SERVER_PASSWORD (and optionally OPENCODE_SERVER_USERNAME). Mutually exclusive with Password. |
Optional: {} |
PrometheusAlertingRule¶
PrometheusAlertingRule defines a single Prometheus alerting or recording rule.
Appears in: - PrometheusRuleGroup
| Field | Description | Default | Validation |
|---|---|---|---|
alert string |
Alert is the alert name. Leave empty for recording rules. | Optional: {} |
|
record string |
Record is the output metric name for recording rules. Leave empty for alerting rules. | Optional: {} |
|
expr string |
Expr is the PromQL expression evaluated at each evaluation cycle. | Required: {} |
|
for string |
For is the duration the condition must be true before the alert fires. Only valid for alerting rules. |
Optional: {} |
|
labels object (keys:string, values:string) |
Labels are labels attached to the alert or recording rule. | Optional: {} |
|
annotations object (keys:string, values:string) |
Annotations are annotations attached to the alert. Only valid for alerting rules. | Optional: {} |
PrometheusRuleGroup¶
PrometheusRuleGroup defines a group of Prometheus alerting or recording rules.
Appears in: - AgentMonitoringSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the rule group. | Required: {} |
|
interval string |
Interval is the evaluation interval for this group. Uses the Prometheus default when omitted. | Optional: {} |
|
rules PrometheusAlertingRule array |
Rules is the list of alerting or recording rules in this group. | MinItems: 1 |
RateLimitSpec¶
RateLimitSpec defines rate limiting configuration
Appears in: - LanguageModelSpec
| Field | Description | Default | Validation |
|---|---|---|---|
requestsPerMinute integer |
RequestsPerMinute limits requests per minute | Optional: {} |
|
tokensPerMinute integer |
TokensPerMinute limits tokens per minute | Optional: {} |
RuntimeSecretRef¶
RuntimeSecretRef references a Secret in the same namespace. All keys in the Secret are injected as env vars via envFrom.
Appears in: - OpenclawConfig - OpencodeConfig
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the Secret. | Required: {} |
SecretReference¶
SecretReference references a Kubernetes Secret
Appears in: - ClaudeCodeConfig - LanguageModelSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the secret | Required: {} |
|
key string |
Key is the key within the secret containing the value | api-key | Optional: {} |
SelfConfigAction¶
Underlying type: string
SelfConfigAction is a category of self-modification an agent may request.
Validation: - Enum: [tools models envVars instructions roleRules]
Appears in: - SelfConfigureSpec
| Field | Description |
|---|---|
tools |
SelfConfigActionTools allows the agent to add or remove tool references. |
models |
SelfConfigActionModels allows the agent to add or remove model references. |
envVars |
SelfConfigActionEnvVars allows the agent to inject plain-value environment variables. |
instructions |
SelfConfigActionInstructions allows the agent to replace its system instructions. |
roleRules |
SelfConfigActionRoleRules allows the agent to append RBAC policy rules to its Role. |
SelfConfigEnvVar¶
SelfConfigEnvVar is a plain-value environment variable injected by a self-config request. SecretKeyRef and other value sources are intentionally not supported.
Appears in: - LanguageAgentSelfConfigSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name of the environment variable. | MinLength: 1 Required: {} |
|
value string |
Value is the literal string value of the variable. | Required: {} |
SelfConfigPhase¶
Underlying type: string
SelfConfigPhase reflects the current processing state of a LanguageAgentSelfConfig.
Validation: - Enum: [Pending Applied Failed Denied]
Appears in: - LanguageAgentSelfConfigStatus
| Field | Description |
|---|---|
Pending |
SelfConfigPhasePending means the request has not yet been processed. |
Applied |
SelfConfigPhaseApplied means the requested changes were patched onto the parent LanguageAgent. |
Failed |
SelfConfigPhaseFailed means the controller encountered an error while processing the request. |
Denied |
SelfConfigPhaseDenied means the request was rejected due to policy (not enabled, or action not allowed). |
SelfConfigureSpec¶
SelfConfigureSpec controls whether a LanguageAgent may submit LanguageAgentSelfConfig requests to modify its own spec at runtime.
Appears in: - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled gates all self-configuration. When false, any LanguageAgentSelfConfig targeting this agent is immediately Denied. |
false | Optional: {} |
allowedActions SelfConfigAction array |
AllowedActions is the allowlist of self-config categories the agent may request. If empty while Enabled=true, all actions are denied. |
Enum: [tools models envVars instructions roleRules] Optional: {} |
ServiceReference¶
ServiceReference identifies a Kubernetes Service
Appears in: - NetworkPeer
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Service name | Required: {} |
|
namespace string |
Service namespace (defaults to same namespace if omitted) | Optional: {} |
ToolProperty¶
ToolProperty defines an individual parameter or return field
Appears in: - ToolSchemaDefinition
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type is the JSON schema type (string, integer, boolean, etc.) | ||
description string |
Description explains what this property represents | Optional: {} |
|
example string |
Example provides an example value as a JSON string | Optional: {} |
ToolReference¶
ToolReference references a LanguageTool
Appears in: - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the LanguageTool | MaxLength: 63 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ Required: {} |
|
enabled boolean |
Enabled indicates if this tool is available to the agent. Defaults to true. Set to false to explicitly disable the tool without removing it. |
true | Optional: {} |
ToolSchema¶
ToolSchema represents the complete schema of an MCP tool
Appears in: - LanguageToolStatus
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the tool identifier | ||
description string |
Description is a human-readable description of the tool | Optional: {} |
|
inputSchema ToolSchemaDefinition |
InputSchema defines the parameters this tool accepts | Optional: {} |
ToolSchemaDefinition¶
ToolSchemaDefinition defines parameter or return value structure
Appears in: - ToolSchema
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type is the JSON schema type (object, array, string, etc.) | Optional: {} |
|
properties object (keys:string, values:ToolProperty) |
Properties defines object properties (for type: object) | Optional: {} |
|
required string array |
Required lists required property names (for type: object) | Optional: {} |
WorkspaceSpec¶
WorkspaceSpec defines persistent workspace storage for an agent
Appears in: - LanguageAgentRuntimeSpec - LanguageAgentSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled controls whether to create a workspace volume. Defaults to true. Set to false to explicitly disable without removing the workspace config. |
true | Optional: {} |
size string |
Size is the requested storage size (e.g., "10Gi", "1.5Ti", "500Mi") Supports integer and decimal quantities with standard Kubernetes suffixes |
10Gi | MinLength: 1 Pattern: ^([0-9]*\.?[0-9]+)(Ei\|Pi\|Ti\|Gi\|Mi\|Ki\|E\|P\|T\|G\|M\|K\|m)?$ Optional: {} |
storageClassName string |
StorageClassName specifies the StorageClass for the PVC If not specified, uses the cluster default |
Optional: {} |
|
accessMode string |
AccessMode defines the volume access mode | ReadWriteOnce | Enum: [ReadWriteOnce ReadWriteMany] Optional: {} |
mountPath string |
MountPath is where the workspace is mounted in containers | /workspace | Optional: {} |
retain boolean |
Retain prevents the workspace PVC from being deleted when the agent is deleted. When true, the PVC's ownerReference is removed during cleanup so Kubernetes GC does not collect it. The orphaned PVC name is surfaced in status.workspacePVCName. Defaults to false. |
false | Optional: {} |
initialFiles object (keys:string, values:string) |
InitialFiles are seeded into the workspace PVC on first boot only. Keys are filenames (must be valid ConfigMap keys: alphanumeric, '.', '-', '_'). Files are not overwritten if they already exist on the PVC. |
Optional: {} |
|
seedConfigMapRef LocalObjectReference |
SeedConfigMapRef references an external ConfigMap whose keys are filenames and values are file contents. Merged with InitialFiles; InitialFiles wins on collision. |
Optional: {} |