π OpenHands: AI-Driven Development
feat(helm): add Helm chart for StatefulSet deployment (#1641)
Robert Brennan30af61735c07
diff --git a/helm/agent-canvas/.helmignore b/helm/agent-canvas/.helmignorenew file mode 100644index 0000000000..4275a16bb0--- /dev/null+++ b/helm/agent-canvas/.helmignore@@ -0,0 +1,18 @@+# Patterns to ignore when packaging Helm charts.+.DS_Store+.git/+.gitignore+.bzr/+.hg/+.svn/+*.swp+*.tmp+*.orig+*.bak+# CI / test+.github/+.circleci/+.travis.yml+# Editor+.idea/+.vscode/diff --git a/helm/agent-canvas/Chart.yaml b/helm/agent-canvas/Chart.yamlnew file mode 100644index 0000000000..0856cbd064--- /dev/null+++ b/helm/agent-canvas/Chart.yaml@@ -0,0 +1,26 @@+apiVersion: v2+name: agent-canvas+description: |+ Helm chart for running the OpenHands agent-canvas all-in-one image+ (frontend + agent-server + automation) as a StatefulSet with persistent+ storage, ingress, and optional cluster RBAC.+type: application+# Chart-level version. Bump on chart changes.+version: 0.1.0+# Default appVersion pins the published agent-canvas image tag from+# config/defaults.json (`versions.agentCanvas`). Override via+# `--set image.tag=...` to pull a different build (e.g. `main`, `latest`,+# or a `sha-<git-sha>` tag).+appVersion: "1.2.0"+kubeVersion: ">=1.24.0-0"+home: https://github.com/OpenHands/agent-canvas+sources:+ - https://github.com/OpenHands/agent-canvas+keywords:+ - openhands+ - agent+ - ai+ - agent-canvas+maintainers:+ - name: OpenHands+ url: https://github.com/OpenHandsdiff --git a/helm/agent-canvas/README.md b/helm/agent-canvas/README.mdnew file mode 100644index 0000000000..0f0dba1627--- /dev/null+++ b/helm/agent-canvas/README.md@@ -0,0 +1,214 @@+# agent-canvas Helm chart++Helm chart for running the [OpenHands agent-canvas](https://github.com/OpenHands/agent-canvas)+all-in-one image (frontend + agent-server + automation) on Kubernetes as a+`StatefulSet` with persistent storage, an `Ingress`, and optional in-cluster+RBAC.++> [!WARNING]+> This Helm chart is experimental. Agent Canvas is an unauthenticated, single-tenant application. This helm chart doesn't address scale or zero-downtime deployments.++## When to use this++This chart turns a Kubernetes cluster into a shared, always-on Agent Canvas+backend: one pod running the UI, agent-server, and automation stack, with a+PVC that survives pod restarts and image upgrades. It's a good fit when you+want:++- **A self-hosted, persistent backend** instead of the laptop-friendly Docker+ setup β so conversations, secrets, and the automation SQLite DB persist+ across restarts without you managing the volume by hand.+- **An internal "vibecoding" platform.** With [RBAC enabled](#rbac), give the+ agent a skill that teaches it to deploy the small web apps it builds+ straight into the cluster. From that point on, anyone with access to the+ Agent Canvas UI can build and ship code into the cluster β and save it to+ GitHub β with just a prompt. No pipelines, no manual `kubectl`, no+ hand-written manifests.++Put it behind an authenticated ingress before exposing it to the internet (see+the [Security](#security) notes).++## Relationship to OpenHands Enterprise++Agent Canvas is an **unauthenticated, single-tenant** application. This chart+runs exactly that: **one** shared instance where all agents are comingled on+the same pod and PVC, with no built-in auth, RBAC for users, or tenant+isolation. It's well suited to a single team or individual running their own+backend.++[OpenHands Enterprise (OHE)](https://www.all-hands.ai/enterprise) is the+productized upgrade path when you need a hardened, multi-user deployment. OHE+adds:++- **Authentication** (SSO / SAML / OIDC) so users must log in.+- **Role-based access control** over who can run agents and manage the+ deployment.+- **Multi-tenancy** so different teams get isolated spaces.+- **Isolated agent sandboxes** β each agent run gets its own container rather+ than every agent sharing the pod's filesystem.++Use this chart for self-hosted, single-tenant setups; reach for OHE when you+need authentication, multi-tenancy, or isolated agent execution.++## TL;DR++```bash+helm install agent-canvas ./helm/agent-canvas+```++## What gets deployed++| Resource | Purpose |+| ----------------------------------- | ---------------------------------------------------------------------------------- |+| `StatefulSet` | Single-replica pod running the all-in-one image (frontend + agent-server + automation). |+| `PersistentVolumeClaim` (per pod) | Backs `~/.openhands` and `~/workspace` (both mounted from the same PVC via `subPath`): settings, encrypted secrets, conversation history, automation SQLite DB, cloned repos, generated files. |+| `Service` (`ClusterIP` by default) | Cluster-internal endpoint on port 8000. |+| `Service` (headless) | Required by the `StatefulSet` for stable pod DNS. |+| `ServiceAccount` | Stable identity the pod runs under. Bindings depend on `rbac.*`. |+| `Ingress` (optional) | External HTTP(S) entry point with the usual class/annotations/TLS knobs. |+| `RoleBinding` (per namespace) | When `rbac.enabled=true`, one per entry in `rbac.namespaces`, bound to the built-in `admin` ClusterRole. |+| `ClusterRoleBinding` (optional) | When `rbac.clusterAdmin=true`, binds the SA to `cluster-admin` cluster-wide. |++## Persistence++The chart provisions **one** PVC and mounts it at multiple well-known+subdirectories of the openhands user's HOME (`/home/openhands`) via+`subPath`. That preserves the pristine home directory the base image+ships (dotfiles like `~/.bashrc` and `~/.profile`) while persisting the+directories that actually contain state:++- `~/.openhands` β agent-server settings, encrypted secrets,+ conversation history and event stores, automation SQLite database+ (unless `config.automationDbUrl` is set), auto-generated+ `OH_SECRET_KEY`, session API key+- `~/workspace` β the agent's default working directory: cloned repos,+ worktrees, anything the agent writes when it treats `~` as the+ workspace root++Both paths share the same underlying disk. Add more entries to+`persistence.mounts` if you want other subtrees persisted (e.g.+`~/.cache`, `~/.config`).++The pod runs as `openhands` (UID 10001) from the upstream image;+`podSecurityContext.fsGroup=10001` makes the kubelet chown the PVC+so that user can write to it.++Point at an existing PVC with `persistence.existingClaim=<name>` if you+manage the volume out of band; otherwise the chart uses the+`StatefulSet`'s `volumeClaimTemplates` (recommended β data survives pod+rescheduling and image upgrades).++## RBAC++RBAC is **off by default** β the pod runs under its own ServiceAccount+but has no in-cluster permissions.++Two independent switches:++```yaml+rbac:+ enabled: true+ # Full access to all resources in these namespaces (bound to the+ # built-in `admin` ClusterRole via one RoleBinding per namespace).+ namespaces:+ - default+ - agent-sandbox+ # Optionally grant cluster-admin. OFF by default. Very broad β enable+ # only when the agent truly needs to manage the whole cluster.+ clusterAdmin: false+```++- `rbac.namespaces` creates one `RoleBinding` per namespace, referencing+ the built-in `admin` ClusterRole. Those namespaces must already exist+ in the cluster.+- `rbac.clusterAdmin=true` creates an additional `ClusterRoleBinding` to+ `cluster-admin`. This overrides / supersedes any per-namespace grant.++## Ingress++Standard knobs:++```yaml+ingress:+ enabled: true+ className: nginx+ annotations:+ nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"+ nginx.ingress.kubernetes.io/proxy-body-size: "50m"+ cert-manager.io/cluster-issuer: letsencrypt-prod+ hosts:+ - host: agent-canvas.example.com+ paths:+ - path: /+ pathType: Prefix+ tls:+ - hosts:+ - agent-canvas.example.com+ secretName: agent-canvas-tls+```++The agent-server uses WebSockets on `/sockets`, so long+`proxy-read-timeout` / `proxy-send-timeout` values are recommended when+using `ingress-nginx`. File uploads honor `proxy-body-size`.++## Common overrides++Provide an LLM key via secret:++```yaml+config:+ extraEnv:+ - name: LLM_MODEL+ value: openhands/claude-sonnet-4-5-20250929+ - name: LLM_API_KEY+ valueFrom:+ secretKeyRef:+ name: my-llm-secret+ key: api-key+```++Bring your own `OH_SECRET_KEY` (must match the value used to encrypt any+existing PVC contents):++```yaml+secrets:+ ohSecretKey:+ existingSecret: agent-canvas-keys+ key: ohSecretKey+```++Point automation at an external Postgres:++```yaml+config:+ automationDbUrl: postgresql+asyncpg://user:pass@postgres/agentcanvas+```++## Security++The agent server can read and write the pod filesystem, execute shell+commands, and β when RBAC is enabled β mutate the Kubernetes cluster it runs+in. There is no built-in authentication in Agent Canvas, so treat the release+namespace as trusted infrastructure:++- Put it behind an **authenticated** ingress (oauth2-proxy, Cloudflare Access,+ tailscale-serve, etc.) before exposing it to the internet.+- Avoid a bare `LoadBalancer` β the agent server accepts any request with the+ right `LOCAL_BACKEND_API_KEY`, so exposing it directly means anyone who can+ guess the key can drive the agent.+- Only turn on `rbac.clusterAdmin` when you truly need cluster-wide access;+ prefer scoping to specific namespaces via `rbac.namespaces`.++For authentication, role-based access control, multi-tenancy, and isolated+agent sandboxes, see [OpenHands Enterprise](#relationship-to-openhands-enterprise).++## Uninstall++```bash+helm uninstall agent-canvas+```++By default the PVC created by `volumeClaimTemplates` is **retained**+after uninstall β delete it manually if you want the data gone. Set+`statefulSet.persistentVolumeClaimRetentionPolicy` (Kubernetes 1.27+) if+you want the PVC lifecycle tied to the StatefulSet.diff --git a/helm/agent-canvas/templates/NOTES.txt b/helm/agent-canvas/templates/NOTES.txtnew file mode 100644index 0000000000..e81d002fdf--- /dev/null+++ b/helm/agent-canvas/templates/NOTES.txt@@ -0,0 +1,55 @@+agent-canvas has been installed as release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.++1. Wait for the StatefulSet pod to be ready:+ kubectl -n {{ .Release.Namespace }} rollout status statefulset/{{ include "agent-canvas.fullname" . }}++2. Access the UI:+{{- if .Values.ingress.enabled }}+ {{- range .Values.ingress.hosts }}+ {{- $scheme := "http" -}}+ {{- range $.Values.ingress.tls -}}+ {{- if has $.host .hosts -}}+ {{- $scheme = "https" -}}+ {{- end -}}+ {{- end }}+ {{- range .paths }}+ {{ $scheme }}://{{ $.host }}{{ .path }}+ {{- end }}+ {{- end }}+{{- else if contains "NodePort" .Values.service.type }}+ export NODE_PORT=$(kubectl -n {{ .Release.Namespace }} get svc {{ include "agent-canvas.fullname" . }} -o jsonpath='{.spec.ports[0].nodePort}')+ export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[0].address}')+ echo "http://$NODE_IP:$NODE_PORT"+{{- else if contains "LoadBalancer" .Values.service.type }}+ Waiting for the LoadBalancer to be provisioned...+ kubectl -n {{ .Release.Namespace }} get svc -w {{ include "agent-canvas.fullname" . }}+{{- else }}+ kubectl -n {{ .Release.Namespace }} port-forward svc/{{ include "agent-canvas.fullname" . }} 8000:{{ .Values.service.port }}+ # Then open http://localhost:8000+{{- end }}++3. Retrieve the auto-generated session API key (needed for direct API calls):+ kubectl -n {{ .Release.Namespace }} exec {{ include "agent-canvas.fullname" . }}-0 -- \+ cat {{ .Values.persistence.mountPath }}/session-api-key.txt++{{- if .Values.rbac.enabled }}++4. RBAC is enabled for this release. The agent has been granted:+ {{- if .Values.rbac.namespaces }}+ - Admin access (built-in `admin` ClusterRole) in namespaces:+ {{- range .Values.rbac.namespaces }}+ * {{ . }}+ {{- end }}+ {{- end }}+ {{- if .Values.rbac.clusterAdmin }}+ - CLUSTER-ADMIN access to the entire cluster (via `cluster-admin`+ ClusterRoleBinding). This is a very broad privilege β audit+ access accordingly.+ {{- end }}+{{- else }}++4. RBAC is disabled β the agent has no in-cluster permissions beyond+ what the default ServiceAccount can do. Set `rbac.enabled=true` and+ populate `rbac.namespaces` (and optionally `rbac.clusterAdmin=true`)+ to grant it cluster access.+{{- end }}diff --git a/helm/agent-canvas/templates/_helpers.tpl b/helm/agent-canvas/templates/_helpers.tplnew file mode 100644index 0000000000..9e3dfd7dcd--- /dev/null+++ b/helm/agent-canvas/templates/_helpers.tpl@@ -0,0 +1,102 @@+{{/*+Expand the name of the chart.+*/}}+{{- define "agent-canvas.name" -}}+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}+{{- end -}}++{{/*+Create a fully qualified app name.+*/}}+{{- define "agent-canvas.fullname" -}}+{{- if .Values.fullnameOverride -}}+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}+{{- else -}}+{{- $name := default .Chart.Name .Values.nameOverride -}}+{{- if contains $name .Release.Name -}}+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}+{{- else -}}+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}+{{- end -}}+{{- end -}}+{{- end -}}++{{- define "agent-canvas.chart" -}}+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}+{{- end -}}++{{/*+Common labels+*/}}+{{- define "agent-canvas.labels" -}}+helm.sh/chart: {{ include "agent-canvas.chart" . }}+{{ include "agent-canvas.selectorLabels" . }}+{{- if .Chart.AppVersion }}+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}+{{- end }}+app.kubernetes.io/managed-by: {{ .Release.Service }}+{{- end -}}++{{/*+Selector labels+*/}}+{{- define "agent-canvas.selectorLabels" -}}+app.kubernetes.io/name: {{ include "agent-canvas.name" . }}+app.kubernetes.io/instance: {{ .Release.Name }}+{{- end -}}++{{/*+Immutable labels β the subset of common labels that are safe to stamp+into resource fields that Kubernetes rejects modifications to after+creation. Excludes `helm.sh/chart` and `app.kubernetes.io/version`,+both of which change whenever the chart version or appVersion is+bumped.++Use this (not `agent-canvas.labels`) inside anything under+`StatefulSet.spec.volumeClaimTemplates[].metadata` β that subtree is+immutable, and any diff there causes `helm upgrade` to fail with:++ StatefulSet.apps ... is invalid: spec: Forbidden: updates to+ statefulset spec for fields other than 'replicas', 'ordinals',+ 'template', ... are forbidden++Object-level `metadata.labels` (on the STS itself, Services, etc.)+are mutable, so those keep the full `agent-canvas.labels` set.+*/}}+{{- define "agent-canvas.immutableLabels" -}}+{{ include "agent-canvas.selectorLabels" . }}+app.kubernetes.io/managed-by: {{ .Release.Service }}+{{- end -}}++{{/*+ServiceAccount name to use.+*/}}+{{- define "agent-canvas.serviceAccountName" -}}+{{- if .Values.serviceAccount.create -}}+{{- default (include "agent-canvas.fullname" .) .Values.serviceAccount.name -}}+{{- else -}}+{{- default "default" .Values.serviceAccount.name -}}+{{- end -}}+{{- end -}}++{{/*+Effective image reference.+*/}}+{{- define "agent-canvas.image" -}}+{{- $tag := default .Chart.AppVersion .Values.image.tag -}}+{{- printf "%s:%s" .Values.image.repository $tag -}}+{{- end -}}++{{/*+PVC name β either the user-provided existing claim or the templated one+that StatefulSet.volumeClaimTemplates generates as "<claimName>-<pod>".+When existingClaim is set we mount it as a plain volume (not via+volumeClaimTemplates), which is why the StatefulSet template branches.+*/}}+{{- define "agent-canvas.pvcClaimName" -}}+{{- if .Values.persistence.existingClaim -}}+{{- .Values.persistence.existingClaim -}}+{{- else -}}+data+{{- end -}}+{{- end -}}diff --git a/helm/agent-canvas/templates/ingress.yaml b/helm/agent-canvas/templates/ingress.yamlnew file mode 100644index 0000000000..973f3c0ac0--- /dev/null+++ b/helm/agent-canvas/templates/ingress.yaml@@ -0,0 +1,48 @@+{{- if .Values.ingress.enabled -}}+{{- $fullName := include "agent-canvas.fullname" . -}}+{{- $svcPort := .Values.service.port -}}+apiVersion: networking.k8s.io/v1+kind: Ingress+metadata:+ name: {{ $fullName }}+ namespace: {{ .Release.Namespace }}+ labels:+ {{- include "agent-canvas.labels" . | nindent 4 }}+ {{- with .Values.ingress.annotations }}+ annotations:+ {{- toYaml . | nindent 4 }}+ {{- end }}+spec:+ {{- if .Values.ingress.className }}+ ingressClassName: {{ .Values.ingress.className }}+ {{- end }}+ {{- with .Values.ingress.tls }}+ tls:+ {{- range . }}+ - hosts:+ {{- range .hosts }}+ - {{ . | quote }}+ {{- end }}+ {{- if .secretName }}+ secretName: {{ .secretName }}+ {{- end }}+ {{- end }}+ {{- end }}+ rules:+ {{- range .Values.ingress.hosts }}+ - {{- if .host }}+ host: {{ .host | quote }}+ {{- end }}+ http:+ paths:+ {{- range .paths }}+ - path: {{ .path }}+ pathType: {{ default "Prefix" .pathType }}+ backend:+ service:+ name: {{ $fullName }}+ port:+ number: {{ $svcPort }}+ {{- end }}+ {{- end }}+{{- end }}diff --git a/helm/agent-canvas/templates/rbac.yaml b/helm/agent-canvas/templates/rbac.yamlnew file mode 100644index 0000000000..fc94e2a2ca--- /dev/null+++ b/helm/agent-canvas/templates/rbac.yaml@@ -0,0 +1,55 @@+{{- if .Values.rbac.enabled -}}+{{- $fullName := include "agent-canvas.fullname" . -}}+{{- $saName := include "agent-canvas.serviceAccountName" . -}}+{{- $saNs := .Release.Namespace -}}+{{- $labels := include "agent-canvas.labels" . -}}++{{/*+ Per-namespace bindings. Each entry in .Values.rbac.namespaces gets a+ RoleBinding to the built-in `admin` ClusterRole, granting the agent+ full access to all resources in that namespace (create/update/delete+ Pods, Deployments, Services, etc.) but NOT to cluster-scoped resources.+*/}}+{{- range $ns := .Values.rbac.namespaces }}+---+apiVersion: rbac.authorization.k8s.io/v1+kind: RoleBinding+metadata:+ name: {{ $fullName }}-admin+ namespace: {{ $ns }}+ labels:+ {{- $labels | nindent 4 }}+roleRef:+ apiGroup: rbac.authorization.k8s.io+ kind: ClusterRole+ name: admin+subjects:+ - kind: ServiceAccount+ name: {{ $saName }}+ namespace: {{ $saNs }}+{{- end }}++{{/*+ Optional cluster-admin binding. Off by default because it grants full+ control of the whole cluster including all namespaces, nodes, CRDs,+ RBAC itself, etc. Turn on with rbac.clusterAdmin=true only when the+ agent legitimately needs to manage the entire cluster.+*/}}+{{- if .Values.rbac.clusterAdmin }}+---+apiVersion: rbac.authorization.k8s.io/v1+kind: ClusterRoleBinding+metadata:+ name: {{ $fullName }}-cluster-admin+ labels:+ {{- $labels | nindent 4 }}+roleRef:+ apiGroup: rbac.authorization.k8s.io+ kind: ClusterRole+ name: cluster-admin+subjects:+ - kind: ServiceAccount+ name: {{ $saName }}+ namespace: {{ $saNs }}+{{- end }}+{{- end }}diff --git a/helm/agent-canvas/templates/service.yaml b/helm/agent-canvas/templates/service.yamlnew file mode 100644index 0000000000..65414f0e5a--- /dev/null+++ b/helm/agent-canvas/templates/service.yaml@@ -0,0 +1,43 @@+apiVersion: v1+kind: Service+metadata:+ name: {{ include "agent-canvas.fullname" . }}+ namespace: {{ .Release.Namespace }}+ labels:+ {{- include "agent-canvas.labels" . | nindent 4 }}+ {{- with .Values.service.annotations }}+ annotations:+ {{- toYaml . | nindent 4 }}+ {{- end }}+spec:+ type: {{ .Values.service.type }}+ ports:+ - name: http+ port: {{ .Values.service.port }}+ targetPort: http+ protocol: TCP+ {{- if and (eq .Values.service.type "NodePort") .Values.service.nodePort }}+ nodePort: {{ .Values.service.nodePort }}+ {{- end }}+ selector:+ {{- include "agent-canvas.selectorLabels" . | nindent 4 }}+---+# Headless service required by the StatefulSet for stable network IDs.+apiVersion: v1+kind: Service+metadata:+ name: {{ include "agent-canvas.fullname" . }}-headless+ namespace: {{ .Release.Namespace }}+ labels:+ {{- include "agent-canvas.labels" . | nindent 4 }}+spec:+ type: ClusterIP+ clusterIP: None+ publishNotReadyAddresses: true+ ports:+ - name: http+ port: {{ .Values.service.port }}+ targetPort: http+ protocol: TCP+ selector:+ {{- include "agent-canvas.selectorLabels" . | nindent 4 }}diff --git a/helm/agent-canvas/templates/serviceaccount.yaml b/helm/agent-canvas/templates/serviceaccount.yamlnew file mode 100644index 0000000000..aad5925867--- /dev/null+++ b/helm/agent-canvas/templates/serviceaccount.yaml@@ -0,0 +1,14 @@+{{- if .Values.serviceAccount.create -}}+apiVersion: v1+kind: ServiceAccount+metadata:+ name: {{ include "agent-canvas.serviceAccountName" . }}+ namespace: {{ .Release.Namespace }}+ labels:+ {{- include "agent-canvas.labels" . | nindent 4 }}+ {{- with .Values.serviceAccount.annotations }}+ annotations:+ {{- toYaml . | nindent 4 }}+ {{- end }}+automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }}+{{- end }}diff --git a/helm/agent-canvas/templates/statefulset.yaml b/helm/agent-canvas/templates/statefulset.yamlnew file mode 100644index 0000000000..261a70c0aa--- /dev/null+++ b/helm/agent-canvas/templates/statefulset.yaml@@ -0,0 +1,174 @@+{{- $fullName := include "agent-canvas.fullname" . -}}+apiVersion: apps/v1+kind: StatefulSet+metadata:+ name: {{ $fullName }}+ namespace: {{ .Release.Namespace }}+ labels:+ {{- include "agent-canvas.labels" . | nindent 4 }}+spec:+ serviceName: {{ $fullName }}-headless+ replicas: {{ .Values.replicaCount }}+ podManagementPolicy: {{ .Values.statefulSet.podManagementPolicy }}+ {{- with .Values.statefulSet.updateStrategy }}+ updateStrategy:+ {{- toYaml . | nindent 4 }}+ {{- end }}+ {{- with .Values.statefulSet.persistentVolumeClaimRetentionPolicy }}+ persistentVolumeClaimRetentionPolicy:+ {{- toYaml . | nindent 4 }}+ {{- end }}+ selector:+ matchLabels:+ {{- include "agent-canvas.selectorLabels" . | nindent 6 }}+ template:+ metadata:+ labels:+ {{- include "agent-canvas.selectorLabels" . | nindent 8 }}+ {{- with .Values.podLabels }}+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.podAnnotations }}+ annotations:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ spec:+ serviceAccountName: {{ include "agent-canvas.serviceAccountName" . }}+ automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }}+ {{- with .Values.imagePullSecrets }}+ imagePullSecrets:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.podSecurityContext }}+ securityContext:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ containers:+ - name: agent-canvas+ image: {{ include "agent-canvas.image" . }}+ imagePullPolicy: {{ .Values.image.pullPolicy }}+ {{- with .Values.securityContext }}+ securityContext:+ {{- toYaml . | nindent 12 }}+ {{- end }}+ ports:+ - name: http+ containerPort: {{ .Values.config.port }}+ protocol: TCP+ env:+ - name: PORT+ value: {{ .Values.config.port | quote }}+ - name: AGENT_SERVER_PORT+ value: {{ .Values.config.agentServerPort | quote }}+ - name: AUTOMATION_PORT+ value: {{ .Values.config.automationPort | quote }}+ {{- if .Values.config.automationDbUrl }}+ - name: AUTOMATION_DB_URL+ value: {{ .Values.config.automationDbUrl | quote }}+ {{- end }}+ {{- if .Values.secrets.ohSecretKey.existingSecret }}+ - name: OH_SECRET_KEY+ valueFrom:+ secretKeyRef:+ name: {{ .Values.secrets.ohSecretKey.existingSecret }}+ key: {{ .Values.secrets.ohSecretKey.key }}+ {{- end }}+ {{- if .Values.secrets.sessionApiKey.existingSecret }}+ - name: OH_SESSION_API_KEYS_0+ valueFrom:+ secretKeyRef:+ name: {{ .Values.secrets.sessionApiKey.existingSecret }}+ key: {{ .Values.secrets.sessionApiKey.key }}+ {{- end }}+ {{- with .Values.config.extraEnv }}+ {{- toYaml . | nindent 12 }}+ {{- end }}+ {{- if .Values.probes.startup.enabled }}+ startupProbe:+ httpGet:+ path: {{ .Values.probes.startup.path }}+ port: http+ periodSeconds: {{ .Values.probes.startup.periodSeconds }}+ timeoutSeconds: {{ .Values.probes.startup.timeoutSeconds }}+ failureThreshold: {{ .Values.probes.startup.failureThreshold }}+ {{- end }}+ {{- if .Values.probes.liveness.enabled }}+ livenessProbe:+ httpGet:+ path: {{ .Values.probes.liveness.path }}+ port: http+ initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}+ periodSeconds: {{ .Values.probes.liveness.periodSeconds }}+ timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds }}+ failureThreshold: {{ .Values.probes.liveness.failureThreshold }}+ {{- end }}+ {{- if .Values.probes.readiness.enabled }}+ readinessProbe:+ httpGet:+ path: {{ .Values.probes.readiness.path }}+ port: http+ initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}+ periodSeconds: {{ .Values.probes.readiness.periodSeconds }}+ timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds }}+ failureThreshold: {{ .Values.probes.readiness.failureThreshold }}+ {{- end }}+ {{- with .Values.resources }}+ resources:+ {{- toYaml . | nindent 12 }}+ {{- end }}+ {{- if .Values.persistence.enabled }}+ volumeMounts:+ {{- range .Values.persistence.mounts }}+ - name: {{ include "agent-canvas.pvcClaimName" $ }}+ mountPath: {{ .mountPath }}+ {{- if .subPath }}+ subPath: {{ .subPath }}+ {{- end }}+ {{- end }}+ {{- end }}+ {{- with .Values.nodeSelector }}+ nodeSelector:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.tolerations }}+ tolerations:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.affinity }}+ affinity:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- with .Values.topologySpreadConstraints }}+ topologySpreadConstraints:+ {{- toYaml . | nindent 8 }}+ {{- end }}+ {{- if and .Values.persistence.enabled .Values.persistence.existingClaim }}+ volumes:+ - name: {{ include "agent-canvas.pvcClaimName" . }}+ persistentVolumeClaim:+ claimName: {{ .Values.persistence.existingClaim }}+ {{- end }}+ {{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}+ volumeClaimTemplates:+ - metadata:+ name: {{ include "agent-canvas.pvcClaimName" . }}+ labels:+ {{- /* MUST use immutableLabels here, not the full label set.+ volumeClaimTemplates is under STS.spec (not spec.template)+ and is rejected by the apiserver on any diff, including+ label churn from `appVersion` / chart `version` bumps. */}}+ {{- include "agent-canvas.immutableLabels" . | nindent 10 }}+ {{- with .Values.persistence.annotations }}+ annotations:+ {{- toYaml . | nindent 10 }}+ {{- end }}+ spec:+ accessModes:+ {{- toYaml .Values.persistence.accessModes | nindent 10 }}+ {{- if .Values.persistence.storageClassName }}+ storageClassName: {{ .Values.persistence.storageClassName | quote }}+ {{- end }}+ resources:+ requests:+ storage: {{ .Values.persistence.size | quote }}+ {{- end }}diff --git a/helm/agent-canvas/values.yaml b/helm/agent-canvas/values.yamlnew file mode 100644index 0000000000..6f9eb3376c--- /dev/null+++ b/helm/agent-canvas/values.yaml@@ -0,0 +1,235 @@+# Default values for agent-canvas.+# This chart deploys the all-in-one agent-canvas image (frontend ++# agent-server + automation) as a single-replica StatefulSet with a+# PersistentVolumeClaim mounted at $HOME/.openhands.++# -- Number of replicas. The all-in-one image stores conversation state,+# settings, and the automation SQLite DB on a single PVC β keep this at 1+# unless you point AUTOMATION_DB_URL at an external Postgres and are ready+# to run the agent-server in a genuinely shareable mode.+replicaCount: 1++image:+ repository: ghcr.io/openhands/agent-canvas+ # Image tag is pinned to the chart's appVersion. Override with+ # `--set image.tag=sha-<...>` when you need a specific build (e.g. a PR+ # image or a hotfix that doesn't match the chart's appVersion).+ # tag: ""+ pullPolicy: IfNotPresent++imagePullSecrets: []+# - name: ghcr-pull-secret++nameOverride: ""+fullnameOverride: ""++# ββ ServiceAccount + RBAC ββββββββββββββββββββββββββββββββββββββββββββββββββββ+# When rbac.enabled is true, the ServiceAccount gets permissions inside+# the cluster. Two independent knobs:+#+# rbac.namespaces β list of namespaces where the SA is granted+# full ("*") access to all resources via a+# per-namespace RoleBinding to the cluster's+# built-in `admin` ClusterRole.+# rbac.clusterAdmin β if true, additionally bind the SA to the+# built-in `cluster-admin` ClusterRole.+# OFF by default.+#+# Leave rbac.enabled=false to run the agent with no cluster access at all+# (the ServiceAccount is still created so pods run under a stable+# identity, but no Role/ClusterRole bindings are created).+serviceAccount:+ create: true+ name: ""+ annotations: {}+ automountServiceAccountToken: true++rbac:+ # Master switch for creating any RoleBinding / ClusterRoleBinding.+ enabled: false+ # Namespaces the agent-server is allowed to manage all resources in.+ # Each entry produces a RoleBinding in that namespace binding this+ # release's ServiceAccount to the built-in `admin` ClusterRole (full+ # namespace-scoped access, but no cluster-wide privileges).+ #+ # Example:+ # namespaces:+ # - default+ # - agent-sandbox+ namespaces: []+ # If true, additionally grant cluster-admin via a ClusterRoleBinding.+ # This is a very broad privilege β off by default.+ clusterAdmin: false++# ββ Service ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+service:+ type: ClusterIP+ port: 8000+ # nodePort: 30800 # only used when type is NodePort+ annotations: {}++# ββ Ingress ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+ingress:+ enabled: false+ className: ""+ annotations: {}+ # nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"+ # nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"+ # nginx.ingress.kubernetes.io/proxy-body-size: "50m"+ # cert-manager.io/cluster-issuer: letsencrypt-prod+ hosts:+ - host: agent-canvas.local+ paths:+ - path: /+ pathType: Prefix+ tls: []+ # - hosts:+ # - agent-canvas.example.com+ # secretName: agent-canvas-tls++# ββ Persistence ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+# The chart provisions ONE PVC and mounts it in the pod at multiple+# well-known subdirectories of $HOME so those trees survive pod+# restarts, rescheduling, and image upgrades β while leaving the rest+# of $HOME untouched (the base image ships dotfiles like ~/.bashrc and+# ~/.profile there that must not be shadowed).+#+# Defaults cover the two paths users care about:+# * $HOME/.openhands β agent-server settings, encrypted secrets,+# conversation history, event stores, automation SQLite DB (unless+# AUTOMATION_DB_URL is overridden), session API key, OH_SECRET_KEY+# * $HOME/workspace β the agent's default working directory: cloned+# repos, worktrees, generated files, anything the agent writes when+# it treats ~ as the workspace root+#+# The upstream agent-server image runs as `openhands` (UID 10001) with+# HOME=/home/openhands. Add more entries to `mounts` if you want other+# subtrees persisted (e.g. ~/.cache, ~/.config).+persistence:+ enabled: true+ # List of paths inside $HOME to persist. Each entry becomes a+ # volumeMount on the container backed by the same PVC via `subPath`,+ # so multiple paths share the same disk. `mountPath` is the absolute+ # path inside the container; `subPath` is a directory name inside+ # the PVC (must be unique across entries and safe on ext4).+ mounts:+ - mountPath: /home/openhands/.openhands+ subPath: openhands+ - mountPath: /home/openhands/workspace+ subPath: workspace+ size: 20Gi+ # storageClassName: "" # empty β cluster default+ accessModes:+ - ReadWriteOnce+ annotations: {}+ # If you prefer to bring your own PVC (already existing in the+ # namespace), set existingClaim to its name. That disables the+ # StatefulSet volumeClaimTemplates path.+ existingClaim: ""++# ββ Configuration ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+config:+ # Unified entry point port inside the container.+ port: 8000+ # Internal ports used by the entrypoint's process manager.+ agentServerPort: 18000+ automationPort: 18001+ # Optional Postgres connection string for the automation backend.+ # When empty, the entrypoint falls back to SQLite on the PVC.+ # automationDbUrl: "postgresql+asyncpg://user:pass@host/db"+ automationDbUrl: ""+ # Extra environment variables to pass through to the container.+ # Each entry is `{ name: ..., value: ... }` or `{ name: ..., valueFrom: ... }`.+ extraEnv: []+ # - name: LLM_MODEL+ # value: "openhands/claude-sonnet-4-5-20250929"+ # - name: LLM_API_KEY+ # valueFrom:+ # secretKeyRef:+ # name: my-llm-secret+ # key: api-key++secrets:+ # If provided, seed OH_SECRET_KEY (settings encryption) and the+ # session API key from Kubernetes Secrets instead of letting the+ # entrypoint auto-generate them on first boot.+ # Auto-generation persists to the PVC, so leaving these empty is fine+ # for most single-tenant deployments.+ ohSecretKey:+ existingSecret: ""+ key: "ohSecretKey"+ sessionApiKey:+ existingSecret: ""+ key: "sessionApiKey"++# ββ Pod-level knobs ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ+podAnnotations: {}+podLabels: {}++podSecurityContext:+ # The upstream agent-server image runs as `openhands` (UID 10001).+ # fsGroup 10001 makes the kubelet chown the PVC to that gid on mount+ # so the process can write to it. runAsUser/runAsGroup are pinned to+ # the same values as a belt-and-suspenders check against future image+ # rebuilds β if the image's USER changes, override these to match.+ fsGroup: 10001+ runAsNonRoot: true+ runAsUser: 10001+ runAsGroup: 10001++securityContext: {}+ # capabilities:+ # drop: [ALL]+ # readOnlyRootFilesystem: false+ # allowPrivilegeEscalation: false++resources:+ requests:+ cpu: 500m+ memory: 1Gi+ limits:+ cpu: "2"+ memory: 4Gi++nodeSelector: {}+tolerations: []+affinity: {}+topologySpreadConstraints: []++# Probes hit the unified entry point.+probes:+ liveness:+ enabled: true+ path: /alive+ initialDelaySeconds: 30+ periodSeconds: 30+ timeoutSeconds: 5+ failureThreshold: 5+ readiness:+ enabled: true+ path: /alive+ initialDelaySeconds: 10+ periodSeconds: 10+ timeoutSeconds: 5+ failureThreshold: 3+ startup:+ enabled: true+ path: /alive+ periodSeconds: 5+ timeoutSeconds: 5+ # Allow up to 5 minutes for first-boot dependencies / DB migration.+ failureThreshold: 60++# StatefulSet-specific knobs.+statefulSet:+ # Whether the StatefulSet uses OrderedReady or Parallel pod management.+ # OrderedReady is safer for stateful workloads; use Parallel only if+ # you understand the implications.+ podManagementPolicy: OrderedReady+ # updateStrategy for rollouts.+ updateStrategy:+ type: RollingUpdate+ # Retained volumes on scale-down/deletion. Kubernetes 1.27+.+ # persistentVolumeClaimRetentionPolicy:+ # whenDeleted: Retain+ # whenScaled: Retain