Preparing a Kubernetes Cluster¶
Before installing Language Operator, your cluster must meet a few requirements. This guide walks through the prerequisites and how to verify them.
Supported Distributions¶
Language Operator runs on any CNCF-conformant Kubernetes 1.26+ cluster. Tested distributions:
| Distribution | Notes |
|---|---|
| k3s | Recommended for local development; includes Traefik and local-path provisioner out of the box |
| kind | Good for CI; requires manual CNI and StorageClass setup |
| EKS | Use VPC CNI + Calico for NetworkPolicy support |
| GKE | Enable "Network Policy" at cluster creation; uses built-in provisioner |
| AKS | Enable "Network Policy: Azure" or install Calico |
Prerequisites¶
Install these tools locally before proceeding:
- kubectl — configured to access your target cluster
- Helm 3.8+
- argo (optional) — the Argo Workflows CLI.
Agents run as Argo Workflows, and
argo list/logs/submitis the most direct way to inspect runs and invoke task-mode agents. Everything it does is also reachable withkubectl.
Verify:
CNI Support¶
Language Operator uses NetworkPolicy resources to isolate agents. Your cluster's CNI plugin must support NetworkPolicy enforcement. The standard CNI plugins that ship with most cloud providers do not enforce NetworkPolicy on their own.
Supported CNIs:
Verify that NetworkPolicy is enforced by checking that your CNI pods are running:
k3s
k3s ships with Flannel by default, which does not enforce NetworkPolicy. Install Cilium or Calico before deploying the operator, or disable network isolation in Helm values:
StorageClass¶
Language Operator requires a StorageClass for agent workspace PVCs created by bundled runtimes (OpenClaw, OpenCode).
List available StorageClasses:
Set config.agents.storageClassName in your Helm values to the StorageClass you want to use. If left empty, the cluster default StorageClass is used.
cert-manager¶
Language Operator uses admission webhooks, and Kubernetes only calls a webhook over TLS. cert-manager provisions and rotates that certificate. This is the only thing the operator needs cert-manager for: Ingress TLS works without it (see Ingress TLS without cert-manager), and you can run without it entirely (see Running without cert-manager).
Check if cert-manager is already installed:
If not, install it:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.3/cert-manager.yaml
kubectl wait --for=condition=Available deployment --all -n cert-manager --timeout=60s
Running without cert-manager¶
Install the operator with the admission webhooks turned off:
Field defaults still apply, because they live in the CRD schema and the API server fills them in without any webhook: workspace, resource requests and limits, and tool transport. What you lose is admission validation: cluster membership, the image registry allowlist, and the runtime and cross-field spec checks. kubectl apply accepts an invalid resource, and the problem surfaces afterwards as an operator event and a failed status condition on the resource instead of a rejected request.
To keep the webhooks with a certificate from somewhere else, set config.webhook.certManager.enabled=false instead. The chart then no longer creates the cert-manager Certificate or injects the CA, so you must create the <release>-webhook-cert TLS Secret (language-operator-webhook-cert with the release name used in the installation guide) in the operator namespace and set caBundle on the <release>-mutating-webhook and <release>-validating-webhook configurations yourself, and keep both current when the certificate rotates.
Traefik¶
Traefik is the recommended ingress controller for Language Operator. When a LanguageCluster has spec.domain set, the operator creates an Ingress resource at gateway.<domain> — Traefik handles routing and TLS termination.
k3s: Traefik is pre-installed. Verify it is running:
Note the EXTERNAL-IP of the traefik service — this is the IP your DNS records should point to.
Other clusters: Install Traefik via Helm:
helm repo add traefik https://traefik.github.io/charts
helm repo update
helm install traefik traefik/traefik \
--namespace traefik \
--create-namespace \
--set ports.web.redirectTo.port=websecure \
--set ports.websecure.tls.enabled=true
kubectl wait --for=condition=Available deployment/traefik -n traefik --timeout=60s
Retrieve the external IP once the LoadBalancer is provisioned:
Point a wildcard DNS record (*.<your-domain>) at this IP, or create individual A records for each agent domain.
Let's Encrypt¶
With cert-manager installed, configure a ClusterIssuer to automatically provision TLS certificates via Let's Encrypt.
Staging (test first)¶
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
email: your-email@example.com
privateKeySecretRef:
name: letsencrypt-staging
solvers:
- http01:
ingress:
ingressClassName: traefik
EOF
Production¶
Once staging certificates are issued successfully, switch to the production issuer:
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-production
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: your-email@example.com
privateKeySecretRef:
name: letsencrypt-production
solvers:
- http01:
ingress:
ingressClassName: traefik
EOF
Verify the issuer is ready:
kubectl get clusterissuer
# NAME READY AGE
# letsencrypt-staging True 30s
# letsencrypt-production True 30s
Using the issuer with Language Operator¶
Pass the issuer name when installing the operator:
--set config.tls.certificateIssuerName=letsencrypt-production \
--set config.tls.certificateIssuerKind=ClusterIssuer
These are included in the helm install command on the installation page. The operator uses them to annotate every gateway and agent Ingress it creates, so cert-manager automatically provisions and renews the TLS certificates.
DNS must resolve before HTTP-01 challenge
cert-manager proves domain ownership by serving a token over HTTP. Ensure your DNS records point to the Traefik IP before creating any LanguageCluster with a domain.
Ingress TLS without cert-manager¶
A LanguageCluster with spec.domain gets an Ingress for each service-mode agent (<agent>.<domain>), for the gateway (gateway.<domain>) when spec.ingress.enabled is true, and for the login page (auth.<domain>) when embedded Dex is on. None of these need cert-manager. Two settings on the cluster decide how they are served:
spec.ingress.tls.modechooses where each Ingress gets its certificate:auto(the default) uses the operator's cert-manager issuer (config.tls.certificateIssuerName). With no issuer configured, the Ingress has no TLS block.secretalways uses the existing TLS Secret named inspec.ingress.tls.secretName. SettingsecretNamewithout a mode impliessecret.nonenever adds a TLS block, even when an issuer is configured.
spec.ingress.externalScheme(httporhttps) is the scheme the outside world uses. The operator builds the OIDC issuer URL, OAuth redirect URIs and webhook URLs from it, independently of the Ingress TLS block. It defaults to the operator'sconfig.tls.externalScheme, which ishttps.
Leave config.tls.certificateIssuerName empty (the chart default) when installing the operator, and pick the case that matches your setup.
TLS terminated upstream¶
An external load balancer or reverse proxy holds the certificate and forwards plain HTTP to the ingress controller. The Ingresses need no TLS block, but users still reach the cluster over HTTPS, so the URLs the operator hands out must say https:
mode: auto with no issuer gives the same Ingress, but the operator records a warning event on each one, because it can't tell an intentional upstream setup from a forgotten issuer. mode: none states the intent and keeps the events quiet.
Bring your own certificate¶
Store a certificate that covers every host as a TLS Secret in the cluster's namespace. A wildcard for *.<domain> covers the gateway, the agents and auth.<domain>. Then point the cluster at it:
kubectl create secret tls agents-wildcard-tls \
--cert=wildcard.crt --key=wildcard.key \
--namespace <cluster-namespace>
The ingress controller terminates TLS with that Secret. You are responsible for renewing it.
Plain HTTP¶
For local and development clusters that are reached over HTTP:
To make http the default for every cluster, install the operator with --set config.tls.externalScheme=http instead of setting it per cluster.
Verifying Cluster Readiness¶
Run through this checklist before installing:
# Kubernetes version
kubectl version --short
# NetworkPolicy-capable CNI pods running
kubectl get pods -n kube-system | grep -E 'cilium|calico|weave|antrea'
# StorageClass available
kubectl get storageclass
# cert-manager running (unless installing with config.webhook.enabled=false)
kubectl get pods -n cert-manager
# Traefik running and has external IP
kubectl get svc -n kube-system traefik 2>/dev/null || kubectl get svc -n traefik traefik
# ClusterIssuers ready (only if cert-manager issues your Ingress certificates)
kubectl get clusterissuer
# Sufficient node resources (operator + Argo controller + gateway + one agent needs ~4Gi RAM)
kubectl top nodes
# Argo Workflows CRDs and controller (installed with the operator chart by default).
# The operator refuses to start without these.
kubectl get crds | grep argoproj.io
kubectl get pods -n language-operator -l app.kubernetes.io/name=argo-workflows-workflow-controller