Skip to content

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/submit is the most direct way to inspect runs and invoke task-mode agents. Everything it does is also reachable with kubectl.

Verify:

kubectl version --client
helm version

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:

kubectl get pods -n kube-system | grep -E 'cilium|calico|weave|antrea'

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:

helm install language-operator language-operator/language-operator \
  --set networkIsolation.enabled=false

StorageClass

Language Operator requires a StorageClass for agent workspace PVCs created by bundled runtimes (OpenClaw, OpenCode).

List available StorageClasses:

kubectl get storageclass

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:

kubectl get pods -n cert-manager

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:

--set config.webhook.enabled=false

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:

kubectl get pods -n kube-system | grep traefik
kubectl get svc -n kube-system traefik

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:

kubectl get svc -n traefik traefik

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.mode chooses 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.
    • secret always uses the existing TLS Secret named in spec.ingress.tls.secretName. Setting secretName without a mode implies secret.
    • none never adds a TLS block, even when an issuer is configured.
  • spec.ingress.externalScheme (http or https) 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's config.tls.externalScheme, which is https.

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:

spec:
  domain: agents.example.com
  ingress:
    tls:
      mode: none
    externalScheme: 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>
spec:
  domain: agents.example.com
  ingress:
    tls:
      mode: secret
      secretName: agents-wildcard-tls

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:

spec:
  domain: agents.127.0.0.1.nip.io
  ingress:
    tls:
      mode: none
    externalScheme: 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